@cassiomc1/forgeloop 1.6.3 → 1.6.4

package/docs/CLI_REFERENCE.md

@@ -42,10 +42,13 @@ ForgeLoop uses a definition-driven command-line parser:
 | **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
 | **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
-| **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity) |
-| **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt) |
+| **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
+| **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
 | **Durable Actions & Approvals** | [`run-action`](#run-action), [`action-propose`](#action-propose), [`action-record`](#action-record), [`action-show`](#action-show), [`action-reconcile`](#action-reconcile), [`action-verify`](#action-verify), [`action-authorize`](#action-authorize), [`approval-request`](#approval-request), [`approval-resolve`](#approval-resolve) |
 | **Policy & Auditing** | [`policy`](#policy), [`policy-discover`](#policy-discover), [`policy-status`](#policy-status), [`policy-diff`](#policy-diff), [`rule-verify`](#rule-verify), [`baseline`](#baseline), [`bundle`](#bundle) |
+| **workspace** | [`workspace-bind`](#workspace-bind), [`workspace-status`](#workspace-status) |
+| **scope** | [`responsibility-set`](#responsibility-set), [`responsibility-status`](#responsibility-status) |
+| **attestation** | [`attestation-create`](#attestation-create), [`attestation-verify`](#attestation-verify), [`attestation-status`](#attestation-status), [`attestation-verify-range`](#attestation-verify-range) |
 
 <!-- END FORGELOOP GENERATED: cli-command-index -->
 
@@ -53,6 +56,308 @@ ForgeLoop uses a definition-driven command-line parser:
 
 ## 1. Setup & Maintenance
 
+## Workspace, Handoff, Responsibility, Scope, and Attestation
+
+These commands add optional, task-scoped protocol artifacts. They do not turn
+ForgeLoop into an agent runtime, scheduler, delegation service, SCM authority,
+or signing authority.
+
+### `workspace-bind`
+
+Binds the selected task to the current Git worktree identity. Rebinding is
+never implicit.
+
+- **Purpose**: Persist an immutable repository/worktree identity binding for the task.
+- **Mutation**: Writes the workspace binding and appends a `WORKSPACE_BOUND` event.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:workspace-bind:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit binding result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:workspace-bind:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop workspace-bind --task task-001 --json
+  ```
+
+### `workspace-status`
+
+Reports whether the current Git worktree matches the selected task binding.
+
+- **Purpose**: Inspect workspace binding status without changing task state.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:workspace-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit workspace status as JSON
+
+<!-- END FORGELOOP GENERATED: cli:workspace-status:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop workspace-status --task task-001 --json
+  ```
+
+### `handoff-create`
+
+Creates an immutable snapshot of current task state for cross-harness
+continuity. It does not delegate work or create a review assignment.
+
+- **Purpose**: Capture protocol-derived state, evidence, paths, and continuity with optional recipient intent.
+- **Mutation**: Writes an immutable handoff artifact and appends a `HANDOFF_CREATED` event.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:handoff-create:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--recipient <hint>`: non-authoritative recipient hint
+- `--note <text>`: non-authoritative handoff note
+- `--json`: emit handoff as JSON
+
+<!-- END FORGELOOP GENERATED: cli:handoff-create:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop handoff-create --task task-001 --recipient next-harness --note "Continue verification" --json
+  ```
+
+### `handoff-list`
+
+Lists immutable handoff snapshots for a task.
+
+- **Purpose**: Inspect existing handoff snapshots without changing them.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:handoff-list:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit handoff list as JSON
+
+<!-- END FORGELOOP GENERATED: cli:handoff-list:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop handoff-list --task task-001 --json
+  ```
+
+### `handoff-show`
+
+Reads and verifies one immutable handoff snapshot.
+
+- **Purpose**: Inspect one handoff by ID and validate its digest and bindings.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:handoff-show:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--id <id>`: handoff identifier
+- `--json`: emit handoff as JSON
+
+<!-- END FORGELOOP GENERATED: cli:handoff-show:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop handoff-show --task task-001 --id handoff-001 --json
+  ```
+
+### `responsibility-set`
+
+Creates immutable constraints for the current task pass.
+
+- **Purpose**: Freeze allowed paths, read-only paths, input fingerprints, and required checks.
+- **Mutation**: Writes responsibility constraints and appends a `RESPONSIBILITY_SET` event.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:responsibility-set:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--label <label>`: descriptive pass label; not an identity or role
+- `--allowed-path <path>`: path prefix allowed during this pass (repeatable)
+- `--read-only-path <path>`: path prefix that must not change during this pass (repeatable)
+- `--required-check <id>`: current-cycle check required by this pass (repeatable)
+- `--freeze-contract`: freeze the current contract fingerprint
+- `--freeze-route`: freeze the current route fingerprint
+- `--freeze-claims`: freeze the current effective claims fingerprint
+- `--json`: emit responsibility result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:responsibility-set:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop responsibility-set --task task-001 --label implementation --allowed-path src --required-check unit-tests --json
+  ```
+
+### `responsibility-status`
+
+Validates active responsibility constraints against current paths, inputs, and
+checks.
+
+- **Purpose**: Inspect whether the current task pass remains within its immutable responsibility boundary.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:responsibility-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit responsibility status as JSON
+
+<!-- END FORGELOOP GENERATED: cli:responsibility-status:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop responsibility-status --task task-001 --json
+  ```
+
+### `verify-scope`
+
+Resolves a provable verification boundary without launching checks.
+
+- **Purpose**: Persist exact changed, claimed, or full verification scope for the current cycle.
+- **Mutation**: Writes a verification-scope artifact and appends a `VERIFICATION_SCOPE_CAPTURED` event.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:verify-scope:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--mode <mode>`: requested deterministic verification boundary (default: AUTO)
+- `--json`: emit verification scope as JSON
+
+<!-- END FORGELOOP GENERATED: cli:verify-scope:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop verify-scope --task task-001 --mode AUTO --json
+  ```
+
+### `attestation-create`
+
+Creates a deterministic in-toto Statement after completion and manifest
+validation.
+
+- **Purpose**: Bind the final source-content manifest to valid completion and audit evidence.
+- **Mutation**: Writes the immutable attestation statement and appends an `ATTESTATION_STATEMENT_CREATED` event.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:attestation-create:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit attestation statement result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:attestation-create:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop attestation-create --task task-001 --json
+  ```
+
+### `attestation-verify`
+
+Verifies a task attestation and current revision without mutating task state.
+
+- **Purpose**: Check statement, manifest, evidence bindings, source bytes, and optional signing-provider policy.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:attestation-verify:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--ref <revision>`: target revision to compare with the manifest
+- `--bundle <path>`: optional external signature bundle
+- `--identity <identity>`: optional exact signer identity policy
+- `--issuer <issuer>`: optional exact signer issuer policy
+- `--revision-provider <provider>`: revision provider (default: git)
+- `--signing-provider <provider>`: signing provider (default: none)
+- `--trusted-root <path>`: trusted signing root path
+- `--require-signature`: require a valid external signature
+- `--json`: emit verification result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:attestation-verify:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop attestation-verify --task task-001 --json
+  ```
+
+### `attestation-status`
+
+Reports local attestation status and trust level without network access.
+
+- **Purpose**: Summarize the locally available manifest, statement, content, evidence, and signature state.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:attestation-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit attestation status as JSON
+
+<!-- END FORGELOOP GENERATED: cli:attestation-status:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop attestation-status --task task-001 --json
+  ```
+
+### `attestation-verify-range`
+
+Verifies attestation coverage for an opaque revision range through the
+provider-neutral revision contract.
+
+- **Purpose**: Detect uncovered changed paths, conflicting attestations, stale content, and required signature failures.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:attestation-verify-range:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--revision-provider <provider>`: revision provider (default: git)
+- `--base <revision>`: opaque base revision
+- `--head <revision>`: opaque head revision
+- `--require-complete-coverage`: fail when any changed source path lacks a valid attestation
+- `--require-signature`: require a valid external signature for covered attestations
+- `--signing-provider <provider>`: signing provider (default: none)
+- `--identity <identity>`: optional exact signer identity policy
+- `--issuer <issuer>`: optional exact signer issuer policy
+- `--trusted-root <path>`: trusted signing root path
+- `--json`: emit range verification result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:attestation-verify-range:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop attestation-verify-range --base base-ref --head head-ref --require-complete-coverage --json
+  ```
+
 ## Durable Actions, Approvals, and Trajectory
 
 ForgeLoop is still a protocol/evidence layer, not an agent runtime. Use
@@ -590,6 +895,7 @@ Executes a verification command with ForgeLoop-attested provenance.
 - `--requirement <id>`: completion requirement covered by the check
 - `--details <json>`: additional structured check details
 - `--timeout-ms <number>`: maximum command duration before termination
+- `--scope-ref <path>`: current verification-scope.json to bind to execution evidence
 - `-- <argv...>`: exact command argv to classify, execute, and attest
 - `--json`: emit structured output as JSON
 

package/docs/CODE_ATTESTATION.md

@@ -0,0 +1,141 @@
+# ForgeLoop Code Attestation
+
+ForgeLoop code attestation binds an exact source-content snapshot to a valid
+ForgeLoop completion and its referenced evidence chain. It does not claim who
+authored the code, whether the code was generated by AI, or that the code is
+bug-free or secure.
+
+## Trust levels
+
+| Level | Meaning |
+| --- | --- |
+| `PROCESSED` | Protocol artifacts exist but verification is not complete. |
+| `VERIFIED` | Completion, evidence bindings, manifest, and current content validate. |
+| `ATTESTED` | `VERIFIED` plus a cryptographically valid signature and trusted signer policy. |
+
+`PROCESSED` is an existence/parsing result, not a trust claim. A manifest or
+statement that merely exists never becomes `ATTESTED`; the signature must be
+verified against the configured signer identity, issuer, and trust policy.
+Attestation binds bounded source/evidence relationships. It does not prove
+authorship, AI or human origin, bug-free behavior, absolute security, or the
+absence of defects outside the captured subject.
+
+`code-manifest.json` is the ForgeLoop-generated source snapshot. It contains
+one SHA-256 digest per changed source entry and a deterministic aggregate
+`contentDigest`. Protocol metadata under `.forgeloop/**` is excluded from the
+source subject and is bound separately through canonical ForgeLoop fingerprints.
+
+The deterministic in-toto Statement v1 is written to `statement.json`:
+
+```text
+.forgeloop/task-state/<taskKey>/attestations/
+  code-manifest.json
+  statement.json
+  statement.sigstore.json       # optional external signature bundle
+```
+
+The source subject excludes ForgeLoop protocol metadata under `.forgeloop/**`.
+That metadata is bound separately through the task, receipt, route, contract,
+state, and ledger fingerprints. Configured coverage exclusions must be
+explicit and are still reported; an excluded path is not silently represented
+as covered source content.
+
+The [Code Attestation Chain](./assets/diagrams/forgeloop-code-attestation-flow.html)
+is the interactive visual fallback for this sequence, with a
+[self-contained SVG](./assets/diagrams/forgeloop-code-attestation-flow.svg).
+It also shows why verification scope and attestation coverage are separate
+questions.
+
+Its canonical source is `docs/diagrams/forgeloop-code-attestation-flow.workflow.json`.
+
+## Completion flow
+
+Configure attestation in `.forgeloop/config.json` when a project needs it:
+
+```json
+{
+  "schemaVersion": 1,
+  "protocolVersion": 1,
+  "complianceMode": "standard",
+  "attestation": {
+    "mode": "required",
+    "revisionProvider": "git",
+    "requireCompleteCoverage": true,
+    "coverage": { "exclude": [] },
+    "signing": {
+      "provider": "none",
+      "required": false,
+      "policy": { "identities": [], "requireTransparencyLog": true }
+    }
+  }
+}
+```
+
+With `mode = required`, completion captures the manifest in the same task
+transaction as final state, receipt, and the `COMPLETION_VALIDATED` event.
+`CODE_MANIFEST_CAPTURED` is appended only after the manifest is persisted. If
+capture fails, the transaction is aborted. `optional` reports unavailability;
+`off` preserves the legacy behavior.
+
+Create and inspect a statement without network access:
+
+```bash
+forgeloop attestation-create --task <taskId> --json
+forgeloop attestation-status --task <taskId> --json
+forgeloop attestation-verify --task <taskId> --ref HEAD --json
+```
+
+`attestation-verify` and `attestation-verify-range` are read-only. They never
+write verification records or append ledger events.
+
+## What the chain proves
+
+The chain proves a bounded relationship among a valid completion, its receipt
+and ledger checkpoint, the exact bytes represented by the code manifest, and
+the deterministic in-toto statement. The `RevisionProvider` supplies opaque
+revision identity and exact content. The optional `SigningProvider` can add a
+cryptographic signature, but neither provider changes the ForgeLoop evidence
+semantics.
+
+Revision-range coverage is a separate multi-task evaluation: a provider
+enumerates changed paths between a base and head, then the verifier computes a
+union of valid task attestations. Uncovered paths and conflicting digests fail
+closed. A `CHANGED` or `CLAIMED` verification scope only describes which paths
+one checker may execute before completion; it is not complete revision-range
+coverage.
+
+## Signature boundary
+
+ForgeLoop does not persist private keys, OIDC tokens, access tokens, or other
+credentials. The `sigstore` provider invokes an external Cosign-compatible
+binary with bounded output, an explicit timeout, and no shell interpolation.
+Signature existence is not signature validity. Only successful verification
+under the configured identity, issuer, and trusted-root policy produces
+`ATTESTED`.
+
+## Revision-range coverage
+
+Use the provider-neutral command in local or CI environments:
+
+```bash
+forgeloop attestation-verify-range \
+  --revision-provider git \
+  --base origin/main \
+  --head HEAD \
+  --require-complete-coverage \
+  --json
+```
+
+The result reports exact changed, covered, uncovered, and overlapping paths.
+An uncovered source path or conflicting overlapping digest returns an invalid
+verification result. Invocation, configuration, and provider failures are
+distinguished from invalid attestations by the stable exit-code contract:
+
+```text
+0 = VALID
+1 = INVALID, stale, uncovered, or untrusted
+2 = invocation, environment, configuration, or provider error
+```
+
+See [`REVISION_PROVIDERS.md`](./REVISION_PROVIDERS.md) and
+[`SIGNING_PROVIDERS.md`](./SIGNING_PROVIDERS.md) for extension boundaries.

package/docs/CROSS_HARNESS_CONTINUITY.md

@@ -46,6 +46,20 @@ Key continuity invariants:
 - **Task identity survives harness changes**: Work state remains the single source of lifecycle truth.
 - **Stale continuity cannot authorize transitions**: Forward lifecycle progression requires valid work-state checkpoints.
 
+These three surfaces must remain distinct:
+
+| Concept | Mutable? | Evidence? | Purpose |
+| --- | --- | --- | --- |
+| `continuity.json` | Yes | No | Mutable operational resume notes (`NON_EVIDENCE_HANDOFF`) |
+| Handoff envelope | No | No | Immutable protocol-derived state snapshot; not authority or independent review evidence |
+| Execution/completion evidence | Controlled by protocol | Yes when valid | Exact process provenance, observed checks, receipt, and validated ledger proof |
+
+The handoff envelope may carry an actor note or recipient hint, but it never
+delegates work, establishes identity, grants authority, or proves completion.
+The [Verification Trust Flow](./REVISION_PROVIDERS.md#differential-verification-scope)
+and [Code Attestation Chain](./CODE_ATTESTATION.md#completion-flow) diagrams
+show the evidence boundaries that continuity and handoff cannot replace.
+
 ---
 
 ## 2. Source-of-Truth Hierarchy
@@ -89,11 +103,17 @@ HARNESS B (Starting / Taking Over)
    ├── 4. Reconciles continuity: `forgeloop reconcile-continuity --task <id> --json`
    ├── 5. Inspects modified files: `forgeloop inspect --task <id> --json`
    └── 6. Asks for next action: `forgeloop next --task <id> --json`
-          │
-          ▼
+     │
+     ▼
      Continues execution without duplicating planning
 ```
 
+Harness B must trust the canonical task state and checkout over prose: inspect
+the task, read and reconcile continuity, inspect the latest handoff when one
+exists, compare the current checkout, and only then follow `forgeloop next`.
+Handoff notes can focus inspection, but only valid execution evidence,
+completion receipts, and the append-only ledger can satisfy verification.
+
 ---
 
 ## 4. Harness A — Recording Handoff Context

package/docs/DOCUMENTATION_GUIDE.md

@@ -14,7 +14,7 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
 | **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`) | Tutorials, command reference, handoff workflows, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
 | **Domain Engineering** | `ENG/` (`clean-code-eng.md`, `design-code-eng.md`, `test-code-eng.md`, etc.) | Domain-specific implementation and quality standards | Frontmatter must adhere to `validate_loop_system.py` standards. |
 | **Consumer Documentation Quality** | [`ENG/documentation-quality-eng.md`](../ENG/documentation-quality-eng.md) | Quality standards for documentation work in projects using ForgeLoop | Governs client/consumer project documentation tasks via guide routing. |
-| **Visual Architecture** | `docs/diagrams/manifest.json` + `docs/diagrams/forgeloop-engineering-flow.workflow.json` | Governance metadata and canonical typed Archify workflow source | Animated HTML explorer, animated SVG fallback, deterministic receipt, and source-bound human review are committed under `docs/assets/diagrams/` and `docs/diagrams/reviews/`. |
+| **Visual Architecture** | `docs/diagrams/manifest.json` + the three typed workflow sources under `docs/diagrams/` | Governance metadata and canonical typed Archify workflow sources | Animated HTML explorers, animated SVG fallbacks, deterministic receipts, and source-bound human reviews are committed under `docs/assets/diagrams/` and `docs/diagrams/reviews/`. |
 | **Documentation Index** | `DOCS_INDEX.md` | Single repository index and ownership map | Updated whenever documentation structure changes. |
 
 ---
@@ -84,7 +84,7 @@ cross-platform CI (.github/workflows/docs-quality.yml)
 | **CLI Command Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
 | **Work-State Transitions** | `WORK_PHASES` / `WORK_TRANSITIONS` (`src/core/protocol.js`) | `ORCHESTRATOR_INTEGRATION.md` | `<!-- BEGIN FORGELOOP GENERATED: work-transitions -->` |
 | **Public Error Codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `docs/TROUBLESHOOTING.md` | `<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->` |
-| **Architecture Flow** | `docs/diagrams/manifest.json` + `docs/diagrams/forgeloop-engineering-flow.workflow.json` | `docs/assets/diagrams/forgeloop-engineering-flow.{html,svg,receipt.json}` + `docs/diagrams/reviews/forgeloop-engineering-flow.review.json` | Verified via pinned Archify renderer, trace-animation markers, source/SVG fingerprints, artifact hashes, persistent review, and composition checks |
+| **Architecture and trust diagrams** | `docs/diagrams/manifest.json` + typed workflow sources | Generated HTML/SVG/receipt/review files for Engineering Flow, Verification Trust Flow, and Code Attestation Chain | Verified via the pinned Archify renderer, trace-animation and reduced-motion markers, source/SVG fingerprints, artifact hashes, persistent review, and composition checks |
 
 ### Maintenance Workflow
 
@@ -122,7 +122,7 @@ conformance checks detect omissions.
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
 | **Task-layout path freshness** | `TASK_LAYOUT_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Package-shipped docs** | `package.json` (`files`) | `tests/package.test.js` |
-| **Architecture diagram** | `docs/diagrams/forgeloop-engineering-flow.workflow.json` | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
+| **Architecture and trust diagrams** | `docs/diagrams/manifest.json` plus each typed workflow source | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
 
 ---
 
@@ -179,18 +179,19 @@ migration, or security-sensitive require `npm run docs:check` before merge.
 
 ## 7. Archify Diagrams and Animated SVG Generation
 
-1. **Typed source is canonical**: The architecture flow is authored in Archify workflow IR at `docs/diagrams/forgeloop-engineering-flow.workflow.json`. Never modify generated HTML or SVG files directly.
+1. **Typed source is canonical**: The Engineering Flow, Verification Trust Flow, and Code Attestation Chain are authored in Archify workflow IR under `docs/diagrams/`; the high-level source is `docs/diagrams/forgeloop-engineering-flow.workflow.json`. Never modify generated HTML, SVG, or receipt files directly.
 2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
-3. **Animated committed outputs**: The source uses `meta.animation: "trace"`. The interactive HTML is the primary animated explorer, and the self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. The deterministic receipt is committed under `docs/assets/diagrams/`.
+3. **Animated committed outputs**: Every active source uses `meta.animation: "trace"`. Each interactive HTML is the primary animated explorer, and each self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. Deterministic receipts are committed under `docs/assets/diagrams/`.
 4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
 5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The human-owned review at `docs/diagrams/reviews/` binds the current source and SVG hashes and is never generated or overwritten. Run `npm run docs:diagrams:check` before review.
 6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
 
 ForgeLoop governs five documentation-diagram categories: workflow,
-architecture, sequence, dataflow, and lifecycle. The current repository has
-one canonical workflow diagram. Governance support does not imply renderer
-support: a type requires an explicit renderer mapping before it can be added as
-an active diagram.
+architecture, sequence, dataflow, and lifecycle. The active repository set has
+three canonical workflow diagrams: the Engineering Flow, Verification Trust
+Flow, and Code Attestation Chain. The pinned wrapper currently maps only
+`workflow`; governance support does not imply renderer support, so a new type
+requires an explicit mapping and tests before activation.
 
 ---
 
@@ -215,8 +216,9 @@ The README hero is intentionally GitHub-repository-only:
   `tests/package.test.js`.
 
 Never edit or delete a generated diagram output independently of its source;
-regenerate `docs/assets/diagrams/` from the typed workflow and keep the receipt
-in sync.
+regenerate all declared outputs from the typed workflow sources and keep each
+receipt and human-owned review binding in sync. Every diagram must also have a
+concise text fallback in the canonical document named by its manifest.
 
 ---