@cassiomc1/forgeloop 1.6.3 → 1.6.5

package/DOCS_INDEX.md

@@ -16,6 +16,7 @@ integration and guide context. Use this map before editing documentation.
 | --- | --- | --- |
 | Getting started tutorial | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) | First-time walkthrough from init to completion |
 | Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
+| Agent bootstrap summary | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) | Generated concise navigation aid for protocol invariants and commands |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
 | Durable actions and trajectory evidence | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) and [`docs/RECIPES.md`](./docs/RECIPES.md) | Action provenance, reconciliation, metrics, and project-local evaluation |
@@ -23,10 +24,15 @@ integration and guide context. Use this map before editing documentation.
 | Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
 | Diagnostic model | [`docs/DIAGNOSTIC_MODEL.md`](./docs/DIAGNOSTIC_MODEL.md) | Structured diagnostic cases, interventions, hypothesis dispositions, information gain |
 | Execution trace and observability | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) | `history`, `trace`, `reflect`, and task-level `inspect` read-only projections |
+| Workspace, handoff, responsibility, and scope | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) and [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Optional task boundaries and deterministic verification planning |
+| Code attestation and revision coverage | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md) | Source-content manifests, in-toto statements, signatures, and range verification |
+| Revision and signing providers | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md) and [`docs/SIGNING_PROVIDERS.md`](./docs/SIGNING_PROVIDERS.md) | Provider-neutral extension contracts |
+| Platform adapters | [`docs/PLATFORM_ADAPTERS.md`](./docs/PLATFORM_ADAPTERS.md) | Generic CI boundary and platform mapping guidance |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
 | Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
-| ForgeLoop 1.6.1 release checklist (current) | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) | Verification adapter boundary, isolation invariants, and publication gates |
+| Current release checklist | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) | Package, protocol, attestation, integration, and publication gates |
+| ForgeLoop 1.6.1 release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) | Verification adapter boundary, isolation invariants, and publication gates |
 | ForgeLoop 1.5/MCP release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) | Integration API v1, MCP package, and publication gates |
 | ForgeLoop 1.4 release checklist | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) | Claim-recovery, compatibility, package, and publication gates |
 | Lifecycle, gates, planning, verification, and recovery | [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) | Normative process for agents and developer workflows |
@@ -40,6 +46,9 @@ integration and guide context. Use this map before editing documentation.
 | Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides |
 | Diagram governance | [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json) | Authoritative taxonomy, renderer mapping, canonical purposes, artifact ownership, and references |
 | Diagram maintainer entrypoint | [`docs/diagrams/README.md`](./docs/diagrams/README.md) | Typed Archify source, animated HTML explorer, animated SVG fallback, review, and regeneration workflow |
+| Engineering flow diagram | [`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html) | Conceptual lifecycle from request through validator-backed completion |
+| Verification Trust Flow | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) | Claims, changed paths, trusted checker capability, exact argv, and observed evidence |
+| Code Attestation Chain | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#completion-flow) | Completion, exact-content manifest, in-toto statement, optional signing, and range coverage |
 | Real Execution Proof of Concept (PoC) | [`poc/README.md`](./poc/README.md) | Non-normative, reproducible public engineering workload, audit evidence, and technical audit. Normative behavior remains owned by [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md). |
 
 ## Audience map
@@ -47,7 +56,7 @@ integration and guide context. Use this map before editing documentation.
 | I am a... | Start here |
 | --- | --- |
 | **First-time user or developer** | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) |
-| **AI coding agent / harness** | [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
+| **AI coding agent / harness** | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) → [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
 | **Technical auditor / Evaluator** | [`poc/README.md`](./poc/README.md) → [`poc/reports/poc-20260826-real-execution-technical-audit-v2.md`](./poc/reports/poc-20260826-real-execution-technical-audit-v2.md) |
 | **Harness integrator** | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) |
 | **External runtime / orchestrator integrator** | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) |
@@ -56,8 +65,11 @@ integration and guide context. Use this map before editing documentation.
 | **Inspecting `.forgeloop/` files** | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) |
 | **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
+| **Understanding verification trust** | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) |
+| **Understanding attestation trust** | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#trust-levels) |
+| **Maintaining generated diagrams** | [`docs/diagrams/README.md`](./docs/diagrams/README.md) |
 | **Documentation contributor** | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) |
-| **Release maintainer (current)** | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) |
+| **Release maintainer (current)** | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) |
 | **Release maintainer (historical 1.5/MCP)** | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) |
 | **Release maintainer (historical 1.4)** | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) |
 | **Protocol architect / maintainer** | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) + [`schemas/`](./schemas/) |
@@ -78,6 +90,9 @@ integration and guide context. Use this map before editing documentation.
 - **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
 - **Map ForgeLoop state into an external runtime/orchestrator**: [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md)
 - **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
+- **Verify source-content attestations**: [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
+- **Understand narrow verification and checker binding**: [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
+- **Inspect the governed diagrams**: [`docs/diagrams/README.md`](./docs/diagrams/README.md)
 
 `README.md` is intentionally a catalog and quickstart. Do not copy the full
 process into adapters or README sections; link to the canonical source.
@@ -93,11 +108,15 @@ process into adapters or README sections; link to the canonical source.
 5. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select only relevant guides.
 6. Use [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and schemas when a
    change affects protocol invariants or artifact shape.
+7. Use [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md) and
+   [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md) when verification
+   scope, provider boundaries, signing, or revision-range coverage is involved.
 
 ## Verification and release
 
 The Node regression suite, ESLint, c8, dependency policy, package boundary,
-and Archify diagram render are the local executable checks. Python validators remain
+attestation coverage, generated summaries/completions, and Archify diagram
+render are the local executable checks. Python validators remain
 frozen CI-only compatibility tools because they cover historical Markdown,
 loop, and secret-scanning contracts that have not been migrated to Node. Their
 scope, exact commands, and migration boundary are recorded in
@@ -121,3 +140,6 @@ uses trusted OIDC publishing and is not implied by local verification.
   external publication or production state.
 - Run `npm run lint`, `npm run coverage`, `npm run pack:check`, and the Python
   CI-only validators proportionally to the change.
+- Run `npm run summary:check`, `npm run completions:check`, and
+  `npm run changelog:check` when changing registries, release metadata, or
+  documentation.

package/EXECUTION_STATE.md

@@ -110,6 +110,13 @@ Any material difference produces `REVALIDATION_REQUIRED`. A non-Git target
 reports that branch/HEAD drift is not verifiable. Cheap checks may be rerun,
 but a completed destructive or publication action is never rerun automatically.
 
+When `workspace-binding.json` is present, it is an additional execution-safety
+boundary: the binding records the derived repository/worktree identity, and
+both task mutations and `run-check` validate the current checkout against it.
+A matching branch name or HEAD alone is not sufficient. When the optional
+artifact is absent, workspace binding is not applicable; it must not be
+invented from continuity notes, handoff prose, or actor input.
+
 The current contract is compared when resolving the target task:
 
 ```bash

package/LOOP_ENGINEERING.md

@@ -1300,6 +1300,64 @@ completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
 installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
+## Optional task boundaries and code attestation
+
+ForgeLoop keeps the following extensions optional so existing task artifacts
+remain readable without migration. When an extension artifact is present, its
+schema and canonical bindings are validated before the artifact affects a
+mutation, verification, or trust result.
+
+<a id="FL-WS-001"></a> **FL-WS-001 — A bound task MUST validate the current workspace**
+before a task mutation or ForgeLoop-owned verification launch. Workspace
+identity is derived from the repository/worktree and is never accepted from
+actor input; a mismatch fails closed before a child process starts. A branch
+name or HEAD value by itself is insufficient to identify a checkout: the
+binding also covers the repository/worktree identity that the protocol derives.
+The artifact is optional; when absent, workspace binding is not applicable.
+When present, `workspace-status` and `run-check` cross the same boundary.
+
+<a id="FL-HANDOFF-001"></a> **FL-HANDOFF-001 — A canonical handoff MUST remain an immutable**
+protocol-derived snapshot. It can carry intent and resume context, but it does
+not delegate work, establish identity, grant authority, provide independent
+review evidence, or prove completion. An optional actor note or recipient hint
+is descriptive metadata only. This envelope is distinct from mutable
+`continuity.json`, which is operational resume context and non-evidence.
+
+<a id="FL-SCOPE-001"></a> **FL-SCOPE-001 — A verification scope MUST narrow execution only from**
+current canonical changed paths, effective claims, or an explicit full-project
+requirement. The resolver never guesses impacted tests, and a stale scope is
+not used as verification evidence. The modes are `AUTO`, `CHANGED`, `CLAIMED`,
+and `FULL`; there is no heuristic `IMPACTED` mode. `AUTO` may resolve to
+`CHANGED` or `CLAIMED` only when a trusted scoped checker is configured,
+otherwise it resolves to `FULL`. An explicit `CHANGED` or `CLAIMED` request
+without that checker fails closed with `E_VERIFICATION_SCOPE_UNRESOLVED`.
+The selected paths, checker capability fingerprint, verification cycle,
+contract fingerprint, and repository fingerprint are bound before launch.
+`run-check` must match the configured `argvPrefix` plus the selected paths;
+drift is rejected before the process starts.
+
+<a id="FL-ATTEST-001"></a> **FL-ATTEST-001 — A code attestation MUST bind exact source content**
+to a valid completion receipt and event-ledger checkpoint. Protocol metadata is
+excluded from the source subject, verification is read-only, and a plain
+fingerprint is not a signature. The binding includes exact bytes, per-entry
+SHA-256 content digests, a deterministic in-toto Statement v1, and the
+provider-specific revision identity. `PROCESSED` means artifacts exist and can
+be parsed; `VERIFIED` means the applicable completion, evidence, manifest, and
+content relationships validate; `ATTESTED` additionally requires a valid
+external signature under the configured identity and issuer policy. Attestation
+does not claim authorship, bug-free code, or absolute security. Verification
+scope is a pre-completion execution decision; attestation coverage is a
+post-completion revision-range question, and one never proves the other.
+
+### Optional responsibility contracts
+
+An optional responsibility contract mechanically constrains a pass with
+allowed/read-only paths, required check IDs, and frozen contract, route, claim,
+and repository inputs. It is a boundary artifact, not an agent-role system.
+Labels such as `implementation` or `review` are descriptive; ForgeLoop has no
+built-in coder, reviewer, or cleaner roles. Completion and audit validate the
+constraint when it is present, and a path or frozen-input drift fails closed.
+
 ## Durable Actions and Trajectory Evidence
 
 Durable actions extend the existing task protocol; they do not turn ForgeLoop

package/LOOP_SYSTEM_DESIGN.md

@@ -322,6 +322,60 @@ same identity as the implementer. Simple documentation tasks may skip design,
 delegation, and full regression when the contract records why those states are
 not applicable.
 
+## Optional boundaries and provenance chain
+
+The current integration view keeps optional safety and provenance boundaries
+visible without turning them into a second state machine:
+
+```text
+Intent
+  ↓
+Contract
+  ↓
+Route
+  ↓
+Task + claim ownership
+  ↓
+Optional workspace binding
+  ↓
+Execution
+  ↓
+Optional responsibility constraint
+  ↓
+Verification planning
+  ↓
+Observed command evidence
+  ↓
+Review
+  ↓
+Transactional completion
+  ↓
+Optional code manifest / attestation
+  ↓
+Optional signing
+  ↓
+Read-only verification / range coverage
+```
+
+Each boundary has a distinct trust meaning. Repository and checkout state
+identify the implementation being inspected; task state owns lifecycle and
+claims; execution artifacts prove process provenance; the completion receipt
+summarizes validated evidence; the code manifest binds exact source bytes; the
+in-toto statement binds that manifest to completion; a signature is an
+external signer result; and a revision-range result evaluates coverage across
+multiple task attestations. A workspace binding is optional and a branch name
+or HEAD alone is not a complete checkout identity. A handoff is an immutable
+state snapshot, while mutable continuity is operational context; neither is
+independent review evidence. Verification scope decides which paths a specific
+checker may execute, whereas attestation coverage asks whether changed paths
+in a revision range are covered. These relationships are intentionally not
+interchangeable.
+
+The [Verification Trust Flow](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
+(`docs/diagrams/forgeloop-verification-trust-flow.workflow.json`) and [Code
+Attestation Chain](./docs/CODE_ATTESTATION.md#completion-flow) diagrams provide
+the focused visual fallbacks for these two boundaries.
+
 ## Precedence and conflicts
 
 The system respects this order:

package/ORCHESTRATOR_INTEGRATION.md

@@ -102,6 +102,29 @@ invariants and record why a skipped phase was not applicable.
 - `forgeloop progress` deterministically evaluates task progress across cycles as `ADVANCING`, `WATCH`, or `STALLED`.
 - `forgeloop record-decision-criterion` attaches contract-bound guidance to unresolved decisions without breaking the schema.
 
+## Optional serializable boundaries
+
+An external orchestrator may expose the following optional protocol artifacts
+without changing the lifecycle or adding a graph runtime:
+
+| Boundary | Serializable view | Required host behavior |
+| --- | --- | --- |
+| Workspace identity | `workspace-binding.json` | Preserve the current checkout and surface a mismatch before mutation or verification launch |
+| Handoff | Immutable handoff envelope | Carry protocol-derived state and any descriptive note without treating it as delegation, authority, or evidence |
+| Responsibility | Allowed/read-only paths, required checks, and frozen-input fingerprints | Enforce the declared boundary and report scope drift |
+| Verification scope | `AUTO`, `CHANGED`, `CLAIMED`, or `FULL` plus scope fingerprint | Consume the canonical result and exact scoped argv; do not infer an `IMPACTED` mode |
+| Attestation | Code manifest, in-toto Statement v1, optional signature, and range result | Preserve `PROCESSED`, `VERIFIED`, and `ATTESTED` distinctions and keep verification read-only |
+
+The host owns scheduling, workers, model calls, checkout selection, transport,
+and platform presentation. ForgeLoop owns schema validation, fingerprints,
+claims, lifecycle transitions, evidence binding, completion, and fail-closed
+trust decisions. Workspace binding, responsibility, narrow verification,
+signing, and MCP are not prerequisites for basic protocol compatibility.
+
+Focused visual fallbacks are maintained in the [Verification Trust
+Flow](./docs/REVISION_PROVIDERS.md#differential-verification-scope) and [Code
+Attestation Chain](./docs/CODE_ATTESTATION.md#completion-flow).
+
 ## Serializable interfaces
 
 The following JSON Schemas define the boundaries a host may implement:

package/PROTOCOL_INTEGRATION.md

@@ -428,6 +428,42 @@ because the executor changed.
 For the practical handoff and multi-tool takeover sequence, see
 [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md).
 
+### Optional workspace and attestation integrations
+
+The stable integration API exposes optional task workspace binding, immutable
+handoff snapshots, responsibility constraints, verification-scope planning,
+and provider-neutral code attestation. Integrations pass opaque revision IDs
+and optional signing policy to the canonical runtime; they do not reimplement
+content coverage, evidence binding, or signer trust.
+
+The ownership boundary for these extensions is explicit:
+
+| Capability | ForgeLoop owns | Host owns |
+| --- | --- | --- |
+| Workspace binding | Derives repository/worktree identity, persists the binding, and rejects mismatch before mutation or `run-check` launch | Chooses whether a task needs binding and provides the current checkout |
+| Handoff envelope | Creates immutable protocol-derived snapshots and verifies their digest and ledger relationships | Supplies any descriptive note or recipient hint; it cannot turn the envelope into delegation or evidence |
+| Responsibility contract | Validates allowed/read-only paths, required checks, and frozen-input fingerprints | Chooses the optional boundary and performs the work inside it |
+| Verification scope | Resolves `AUTO`, `CHANGED`, `CLAIMED`, or `FULL`, binds scoped-checker argv, and fails closed on stale or mismatched inputs | Declares checker configuration and consumes the returned scope without guessing a narrower one |
+| RevisionProvider | Reads opaque revisions, exact bytes, normalized changes, and range coverage through the provider contract | Supplies or selects the provider and revision identifiers |
+| SigningProvider | Validates provider results and preserves `VERIFIED` versus `ATTESTED` semantics | Owns the external signer, identity/issuer policy, credentials, and availability |
+| Generic CI / MCP | Keeps canonical command, evidence, and trust semantics | Owns the platform job, transport, scheduling, and presentation layer |
+
+These capabilities are additive. Basic ForgeLoop compatibility still consists
+of the canonical task, contract, route, preflight, lifecycle, evidence, and
+completion boundaries; a host must not make workspace binding, narrow
+checking, signing, Generic CI, or MCP prerequisites for the default loop.
+
+<a id="FL-ATTEST-002"></a> **FL-ATTEST-002 — An integration MUST consume the canonical**
+attestation result and preserve its distinction between `VALID`, invalid,
+uncovered, stale, and provider/environment failure. An adapter cannot upgrade
+an invalid result or treat npm provenance, a platform status, or a local
+fingerprint as a ForgeLoop signature.
+
+<a id="FL-ATTEST-003"></a> **FL-ATTEST-003 — A signing integration MUST keep private keys,**
+OIDC tokens, and credentials outside ForgeLoop artifacts. Signing and
+verification may use an external provider, while the persisted statement stays
+deterministic and provider-neutral.
+
 ## Executable Policy Protocol Integration
 
 ForgeLoop integrates executable verification rules directly into the lifecycle:

package/QUALITY_SCORECARD.md

@@ -35,6 +35,27 @@ policy are all present.
 | Trajectory evaluation | Read-only trace/reflection metrics, unknown usage preservation, canonical comparable-step definition, and scenario-bound efficiency without an arbitrary overall score. |
 | Maintenance quality | Small modules, built-in runtime, deterministic JSON contracts, malformed/version fixtures, package gates, and backward-compatible protocol versions. |
 
+## Capability evidence matrix
+
+The rows below record the protocol capabilities covered by the post-
+implementation correction plan. `VERIFIED` means the structure and local
+tests are present in this checkout; `ATTESTED` is reserved for evidence from
+an external runner, pull request, or publication boundary.
+
+| Capability | Contract/docs | Core implementation | Schema/artifacts | Positive tests | Negative/adversarial tests | CI/E2E | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Workspace Binding | `LOOP_ENGINEERING.md`, workspace binding contract | `src/core/workspace-binding.js` | `schemas/workspace-binding.schema.json`, task binding artifact | `tests/workspace-binding.test.js`, `tests/workspace-binding-cli.test.js` | `tests/workspace-binding-mutation.test.js`, `tests/workspace-binding-run-check.test.js` | Local protocol suite; external runner pending | VERIFIED / NOT_ATTESTED |
+| Canonical Handoff Envelope | `LOOP_ENGINEERING.md`, handoff contract | `src/core/handoff.js` | `schemas/handoff-envelope.schema.json` | `tests/handoff-envelope.test.js`, `tests/handoff-cli.test.js` | `tests/handoff-tamper.test.js`, `tests/handoff-continuity.test.js` | Local protocol suite; external runner pending | VERIFIED / NOT_ATTESTED |
+| Responsibility Contract | Responsibility and ownership rules in `LOOP_ENGINEERING.md` | `src/core/responsibility.js` | `schemas/responsibility.schema.json` | `tests/responsibility-cli.test.js` | `tests/responsibility-completion.test.js` | Local protocol suite; external runner pending | VERIFIED / NOT_ATTESTED |
+| Differential Verification Scope | Correction plan Section 1; `docs/CLI_REFERENCE.md` | `src/core/verification-scope.js`, `src/core/verification-scope-capability.js` | `schemas/verification-scope.schema.json`, scoped checker config | `tests/verification-scope.test.js`, `tests/revision-provider-conformance.test.js` | `tests/verification-scope-freshness.test.js`, `tests/run-check.test.js` | Node matrix and post-merge workflow pending | VERIFIED / NOT_ATTESTED |
+| RevisionProvider | `docs/REVISION_PROVIDERS.md` | `src/core/revision/provider.js`, `src/core/revision/registry.js`, `src/core/revision/git.js` | Normalized revision entries and provider identity artifacts | `tests/revision-provider-conformance.test.js` | Unsafe path, unavailable provider, ambiguity, deletion, and rename cases in the conformance suite | Local Node suite; external runner pending | VERIFIED / NOT_ATTESTED |
+| Code Manifest | `docs/CODE_ATTESTATION.md` | `src/core/code-manifest.js` | `schemas/code-manifest.schema.json`, code manifest artifact | `tests/code-manifest.test.js`, `tests/attestation-e2e.test.js` | Manifest mutation and coverage failures | Local attestation suite; external runner pending | VERIFIED / NOT_ATTESTED |
+| Code Attestation | `docs/CODE_ATTESTATION.md` | `src/core/attestation.js`, `src/core/attestation-verifier.js` | `schemas/code-attestation.schema.json`, statement artifact | `tests/attestation.test.js`, `tests/attestation-e2e.test.js` | `tests/attestation-verifier.test.js`, stale-content cases | Local attestation suite; external runner pending | VERIFIED / NOT_ATTESTED |
+| SigningProvider | `docs/SIGNING_PROVIDERS.md` | `src/core/signing/provider.js`, `src/core/signing/registry.js` | Sigstore bundle and signing provider contracts | `tests/signing-provider.test.js`, `tests/signing-provider-conformance.test.js` | Invalid provider, missing signature, and policy mismatch cases | Local conformance; external signer pending | VERIFIED / NOT_ATTESTED |
+| Revision-range coverage | `docs/CODE_ATTESTATION.md` | `src/core/attestation-coverage.js` | `schemas/attestation-verification-result.schema.json` | `tests/attestation-coverage.test.js`, `tests/attestation-e2e.test.js` | Missing, conflicting, stale, and incomplete coverage cases | Local range checks; external revision range pending | VERIFIED / NOT_ATTESTED |
+| Generic CI attestation | `integrations/generic-ci/verify.sh`, `docs/UNIVERSAL_INTEGRATION.md` | Generic CI verification and evidence boundary | CI verification outputs and attestation inputs | `tests/generic-ci-attestation.test.js` | Invalid or incomplete CI evidence cases | Pull-request workflow evidence required for ATTESTED | VERIFIED / NOT_ATTESTED |
+| Documentation diagrams | `docs/diagrams/manifest.json`, `docs/DOCUMENTATION_GUIDE.md`, `docs/diagrams/forgeloop-code-attestation-flow.workflow.json` | Typed Archify workflow sources and pinned renderer wrapper | Generated HTML/SVG/receipt/review artifacts | `tests/documentation-diagrams.test.js`, `tests/documentation-diagram-manifest.test.js`, `tests/documentation-portability.test.js` | Stale output, missing review, unsupported renderer, orphan, reduced-motion, and deterministic-generation cases | Local renderer and structural accessibility checks; visual review is source-bound | VERIFIED / NOT_ATTESTED |
+
 ## Score rules
 
 - `Observed` evidence is a command result, file, hash, or test output available

package/README.md

@@ -31,11 +31,13 @@ relevant guides.
 - **Inspect a real ForgeLoop execution** → [`poc/README.md`](./poc/README.md)
 - **Full protocol specification** → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrating an AI harness** → [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+- **Agent bootstrap summary** → [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md)
 - **Continuing another harness's task** → [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
 - **CLI command reference** → [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
 - **Artifact & schema reference** → [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
 - **Operational recipes** → [`docs/RECIPES.md`](./docs/RECIPES.md)
 - **Troubleshooting & error codes** → [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
+- **Code attestation & revision coverage** → [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
 - **System architecture & safety** → [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) & [`THREAT_MODEL.md`](./THREAT_MODEL.md)
 - **Documentation index & ownership** → [`DOCS_INDEX.md`](./DOCS_INDEX.md)
 
@@ -114,6 +116,41 @@ forgeloop next --task demo --json
 The last command reports the next safe action; it does not execute code or
 schedule agents.
 
+### Optional code attestation
+
+Projects may opt into source-content attestation after a valid completion. The
+attestation binds an exact source snapshot to the ForgeLoop evidence chain; it
+does not prove authorship or absolute security. See
+[`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md) for configuration,
+read-only verification, signatures, and revision-range coverage.
+
+### Optional task boundaries and differential verification
+
+Workspace binding, immutable handoff envelopes, and responsibility contracts
+are optional boundaries around a task. They constrain where a task may run and
+what a pass may change; they do not grant identity, delegation, review,
+authorship, or completion authority. Differential Verification Scope is a
+separate pre-completion execution decision:
+
+```text
+AUTO
+ ├─ trusted scoped checker + safe changed paths → CHANGED
+ ├─ trusted scoped checker + claims fallback   → CLAIMED
+ └─ otherwise                                  → FULL
+```
+
+Explicit `CHANGED` or `CLAIMED` fails closed when no trusted scoped checker is
+configured. A `RevisionProvider` supplies opaque revisions and normalized
+changed entries; a `SigningProvider` is an optional external authority for
+raising `VERIFIED` to `ATTESTED`. See [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md),
+[`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md), and
+[`docs/RECIPES.md`](./docs/RECIPES.md) for operational details.
+
+Generic CI provides a platform-neutral revision-range boundary; thin GitHub,
+GitLab, local, or enterprise adapters may translate revisions without adding
+trust rules to the protocol core. The CLI and integration API remain usable
+across supported platforms, with MCP as an optional local adapter.
+
 ### Durable external actions
 
 For external effects, record intent with `action-propose`, apply the capability
@@ -327,6 +364,21 @@ The broader architecture and boundaries are in
 
 ![ForgeLoop evidence-first engineering flow (animated SVG fallback)](./docs/assets/diagrams/forgeloop-engineering-flow.svg)
 
+The architecture flow is complemented by two focused, source-bound workflow
+diagrams. The [Verification Trust Flow source](./docs/diagrams/forgeloop-verification-trust-flow.workflow.json),
+[animated explorer](./docs/assets/diagrams/forgeloop-verification-trust-flow.html),
+[SVG fallback](./docs/assets/diagrams/forgeloop-verification-trust-flow.svg),
+[receipt](./docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json),
+and [visual review](./docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json)
+show why narrow verification is fail-closed. The [Code Attestation Chain
+source](./docs/diagrams/forgeloop-code-attestation-flow.workflow.json),
+[animated explorer](./docs/assets/diagrams/forgeloop-code-attestation-flow.html),
+[SVG fallback](./docs/assets/diagrams/forgeloop-code-attestation-flow.svg),
+[receipt](./docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json),
+and [visual review](./docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json)
+show exact content binding, optional signing, and separate revision-range
+coverage.
+
 Text-only fallback: discovery creates the contract and route; required gates
 and `PREFLIGHT_READY` authorize execution; verification creates structured
 evidence; failures enter diagnosis and correction; review precedes
@@ -440,6 +492,9 @@ npm run pack:check
 npm run dependency:policy
 npm run docs:diagrams
 npm run docs:check
+npm run completions:check
+npm run summary:check
+npm run changelog:check
 ```
 
 ## Repository structure

package/TERMINOLOGY.md

@@ -36,6 +36,17 @@
 | Historical claims | The write claims retained in `task.json` as task history, including while recovery releases their active ownership. |
 | Effective claims | The claims currently enforced for ownership conflicts: descriptor claims for an active task, or an empty set after validator-backed completion or active recovery. |
 | Claim reacquisition | The serialized `task-resume` operation that rechecks conflicts and checkout cleanliness before removing recovery state and restoring mutation authority. |
+| Workspace binding | An optional protocol-derived repository/worktree identity boundary that blocks mutation or `run-check` when the current checkout differs. |
+| Handoff envelope | An immutable protocol-derived task snapshot; it is not delegation, authority, independent review evidence, or completion evidence. |
+| Responsibility contract | An optional mechanical boundary for allowed/read-only paths, required checks, and frozen inputs; labels are descriptive rather than roles. |
+| Verification scope | The pre-completion set of paths a specific checker may execute, resolved as `AUTO`, `CHANGED`, `CLAIMED`, or `FULL`. |
+| Scoped checker | A trusted checker configuration whose exact argv prefix and selected paths are bound before launch. |
+| RevisionProvider | The provider-neutral boundary for opaque revisions, exact content, normalized changes, and revision-range coverage. |
+| SigningProvider | An optional external authority that can raise a valid attestation from `VERIFIED` to `ATTESTED` under identity and issuer policy. |
+| Code manifest | A deterministic source-content snapshot with per-entry SHA-256 digests and an aggregate content digest. |
+| Attestation statement | A deterministic in-toto Statement v1 binding the code manifest to valid ForgeLoop completion evidence. |
+| Revision-range coverage | A post-completion result asking whether changed paths between two revisions are covered by valid task attestations. |
+| Generic CI | The provider-neutral range-verification boundary that thin platform adapters may invoke without adding platform trust rules to the core. |
 
 | Execution continuity | Bounded current-task implementation context used to resume the same ForgeLoop task across sessions or harnesses. |
 | Continuity artifact | `.forgeloop/continuity.json`; non-evidence operational context bound to canonical work state. |

package/THREAT_MODEL.md

@@ -116,6 +116,13 @@ provide a universal exactly-once guarantee.
 | Legacy snapshot semantic confusion | A legacy task snapshot lacking baseline state is assumed to have empty baseline, creating false `WEAKEN` drift | Semantic baseline snapshotting in `policy-snapshot.json` | Snapshots retain full semantic baseline entries; snapshots lacking baseline state classify drift as `UNKNOWN` rather than inventing state | Modern tasks retain semantic baseline entries for exact diff | `tests/policy-hardening.test.js` |
 | Cross-task state confusion | Concurrent processes or alternative harnesses mutate or read the wrong task's state in a multi-task workspace | Task-scoped isolation in `.forgeloop/task-state/<taskKey>/` | Deterministic SHA-256 task directory namespacing, explicit `--task` / `FORGELOOP_TASK` selectors, separate file-level lease locks under `.forgeloop/locks/`, and claim overlap detection in `task-create` | Tasks must declare non-overlapping write claims or operate in isolated worktrees | `tests/task-namespace.test.js`, `tests/task-scope.test.js` |
 | Modern namespace descriptor deletion | Corruption or an attacker removes `task.json` from a modern task namespace (leaving contract/work-state/receipt/events), the resolver ignores the namespace, and stale legacy singleton state becomes authoritative | Descriptor boundary between modern task namespaces and the legacy singleton | Descriptor-less 64-hex directories are classified by contents: directories containing modern task artifacts (or empty directories) fail closed with `E_TASK_DESCRIPTOR_INVALID`; only directories containing exclusively the explicitly recognized legacy-incidental artifact (`policy-snapshot.json`) are ignored; `resolveTaskContext` fails closed when all namespaces are corrupt | A separately privileged process can rewrite task-state directories after validation | `tests/validate-receipt-task.test.js` |
+| Workspace binding substitution | A valid task is mutated or verified from another Git checkout or worktree | Task workspace binding and final mutation/execution boundary | `workspace-binding.json` stores protocol-derived repository/worktree identities; every bound mutation and ForgeLoop-owned check validates the current identity before launch and fails closed on mismatch | A privileged process can rewrite both the binding and workspace after validation | `tests/workspace-binding.test.js`, `tests/workspace-binding-run-check.test.js` |
+| Handoff authority inflation | An actor treats a handoff note or recipient hint as delegation, identity, or completion authority | Immutable handoff envelope and continuity boundary | Handoffs contain protocol-derived state, claims, changed paths, and evidence references; digest/schema validation rejects tampering and no lifecycle authority is inferred | The recipient still controls how it interprets non-evidence intent outside the protocol | `tests/handoff-envelope.test.js` |
+| Responsibility scope bypass | A pass changes files outside its declared boundary or after frozen inputs drift | Responsibility constraint artifact and completion/audit validation | Allowed/read-only paths, required checks, and contract/route/claim fingerprints are validated; descriptive labels never select behavior | Filesystem privileges outside ForgeLoop can bypass local enforcement | `tests/responsibility.test.js` |
+| Unsafe differential narrowing | A verifier skips impacted work based on guessed dependency relationships | Verification-scope artifact and canonical claim/change projection | `AUTO` narrows only to exact changed paths or effective claims; ambiguous inputs escalate or remain unresolved, and stale scope is rejected | A project verifier may still ignore an explicitly returned scope if it is not configured to consume it | `tests/verification-scope.test.js`, `tests/verification-scope-freshness.test.js` |
+| Attestation content substitution | A source byte, receipt, state, route, contract, or ledger checkpoint changes after attestation | Code manifest, in-toto statement, revision provider, and read-only verifier | Per-entry content digests, provider identities, canonical aggregate digest, evidence fingerprints, and ledger sequence/hash are checked before a verified result | Local filesystem access can rewrite all artifacts consistently; this remains local consistency validation, not remote trust | `tests/code-manifest.test.js`, `tests/attestation-verifier.test.js` |
+| Signature confusion | A plain digest or platform publication signal is presented as a cryptographic signature | External signing-provider boundary | `ATTESTED` requires a valid external signature under the requested signer policy; private keys and tokens never enter persisted artifacts | Trust in the external signer and transparency infrastructure remains outside ForgeLoop | `tests/signing-provider.test.js` |
+| Incomplete revision coverage | A changed source path has no valid task attestation or overlaps another task with a conflicting digest | Provider-neutral range coverage evaluator | Changed, covered, uncovered, and overlapping paths are computed from the selected revision provider; enforcement fails closed on gaps or conflicts | Coverage is limited to the provider's observable revision/content boundary | `tests/attestation-coverage.test.js`, `tests/generic-ci-attestation.test.js` |
 
 ## Boundary rules