Align architecture documentation and testing policies with current standards

docs/policy/documentation.md

@@ -1,5 +1,14 @@
 # Documentation Policy
 
+**Base Policy Version:** 1.3
+
+**Last Updated**: 2026-09-25
+
+**Upstream Source:** `policy` commit `45591a79004c6811950f14dca554f6ff69b7f58e`.
+
+Notarius retains subprocess-consumer ownership, the distinction between
+descriptive behavior and policy, and no placeholders for absent interfaces.
+
 ## Purpose
 
 This policy assigns each documentation topic to one canonical owner. Its goal is
@@ -24,8 +33,12 @@ contract, maintain it only in the owning document.
 Outside `docs/roadmap/`, documentation describes implemented behavior only.
 Partial features may be described only to their implemented boundary.
 
-ADRs are the narrow exception: an ADR may record an accepted architectural
-decision before implementation, but acceptance must not be presented as proof
+Architectural constraints may govern future changes without implying that the
+components or capabilities they would govern already exist. This does not permit
+describing a proposed system structure as implemented.
+
+ADRs may record an accepted architectural decision before implementation, but
+acceptance must not be presented as proof
 that the behavior exists. The roadmap owns implementation status and sequencing
 until the decision is implemented. Current architecture, user, operator,
 integration, and internal documentation are updated when the behavior lands.
@@ -71,7 +84,8 @@ secret values.
 | --- | --- | --- | --- |
 | Product orientation and minimal end-to-end quickstart | `README.md` | What Notarius is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. |
 | Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
-| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
+| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
+| Agent policy | `docs/policy/agents.md` | Implementation discipline, rules against invented restrictions or guarantees, and local commit authorization. | Application contracts, architecture, testing policy, and contributor procedures. |
 | Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
 | Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
 | CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
@@ -80,7 +94,7 @@ secret values.
 | Source release procedure | `docs/release.md` | Maintainer release selection, candidate validation, tagging, publication guards, verification, and immutable-tag recovery. | Product installation summary, CLI version semantics, historical release summaries, CI implementation detail. |
 | Release-note history | `docs/releases/` | One checked-in historical summary for each source release made under the procedure. The note at the immutable tag is that release's record. | Current commands, behavior, contracts, and compatibility definitions. |
 | Public HTTP contract, if introduced | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
-| Consumer guidance, if a public package or API is introduced | `docs/consumers/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
+| Consumer guidance | `docs/consumers/` | Task-oriented subprocess use, minimal client examples, consumer responsibilities, and guidance for any future public package or API. | Wire semantics, external protocol contracts, internal implementation detail. |
 | External and durable integration contracts | `docs/integrations/` | External file formats and protocols, upstream and downstream contracts, logical output bundle paths and schemas, media types, and compatibility behavior. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
 | Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
 | Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |