@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -0,0 +1,281 @@
+# ForgeLoop Agent Protocol Summary
+
+> Generated from the ForgeLoop protocol registries. This file is a concise navigation aid; the normative documents, schemas, and CLI implementation remain authoritative.
+
+## Scope
+
+ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
+
+Protocol version: 1
+Package version: 1.6.4
+
+## Canonical loop
+
+1. Discover existing work with forgeloop task-list --json.
+2. Select or create one task, then run forgeloop next --task <id> --json.
+3. Persist the contract, route, gates, and source registry; require forgeloop preflight to return READY.
+4. Execute bounded checks through the canonical CLI and preserve execution provenance.
+5. Reconcile continuity, inspect evidence, and advance through VERIFYING and REVIEWING.
+6. Run forgeloop complete; accept completion only when the validator returns VALID.
+7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
+
+## Authority boundaries
+
+- Protocol-derived facts outrank actor-provided labels, free-form summaries, and guessed identities.
+- Optional artifacts are reported as NOT_APPLICABLE when absent; malformed active security artifacts fail closed.
+- Workspace binding confirms an explicit Git worktree identity but is not a portability requirement for attestation.
+- Handoff envelopes record immutable intent and state snapshots; they do not delegate work or grant completion authority.
+- Responsibility contracts constrain paths, checks, and frozen inputs; they do not prove identity or authorship.
+- Verification scope describes planned verification breadth. Attestation coverage proves content for a concrete revision. These are separate claims.
+- Attestation manifests exclude ForgeLoop protocol metadata and bind to the completion receipt and append-only ledger without circular references.
+- Verification commands are read-only. Signing is external; private keys and credentials are never persisted by ForgeLoop.
+
+## Lifecycle
+
+Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECUTING, VERIFYING, DIAGNOSING, CORRECTING, REVIEWING, COMPLETE, BLOCKED
+
+## Feature registry
+
+| Feature | Version | Supported |
+| --- | --- | --- |
+| canonicalHandoffs | 1 | yes |
+| capabilityPolicy | 1 | yes |
+| codeAttestation | 1 | yes |
+| diagnostics | n/a | yes |
+| differentialVerificationScope | 1 | yes |
+| durableActions | 1 | yes |
+| durableApprovals | 1 | yes |
+| executionHistory | 1 | yes |
+| integrationApi | 1 | yes |
+| observabilityStability | n/a | yes |
+| reflection | 1 | yes |
+| responsibilityConstraints | 1 | yes |
+| structuredTrace | 1 | yes |
+| taskClaimRecovery | 1 | yes |
+| taskInspection | 1 | yes |
+| trajectoryEvaluation | 1 | yes |
+| trajectoryMetrics | 1 | yes |
+| verificationExecutionIsolation | 1 | yes |
+| workspaceBinding | 1 | yes |
+
+## Public artifact registry
+
+| Key | Scope | Path | Schema | Trust role |
+| --- | --- | --- | --- | --- |
+| actions | TASK | .forgeloop/task-state/<task-key>/actions/action-<id>.json | action | EXTERNAL_ACTION_PROVENANCE |
+| approvals | TASK | .forgeloop/task-state/<task-key>/approvals/approval-<id>.json | approval | ACTION_APPROVAL_ATTESTATION |
+| attestationBundle | TASK | .forgeloop/task-state/<task-key>/attestations/statement.sigstore.json | n/a | EXTERNAL_SIGNATURE_BUNDLE |
+| attestationStatement | TASK | .forgeloop/task-state/<task-key>/attestations/statement.json | in-toto-statement | CODE_ATTESTATION_STATEMENT |
+| capabilityPolicy | PROJECT | .forgeloop/policy/capabilities.json | capability-policy | CAPABILITY_POLICY_SPECIFICATION |
+| codeManifest | TASK | .forgeloop/task-state/<task-key>/attestations/code-manifest.json | code-manifest | CONTENT_INTEGRITY_SNAPSHOT |
+| config | PROJECT | .forgeloop/config.json | config | PROJECT_CONFIGURATION |
+| continuity | TASK | .forgeloop/task-state/<task-key>/continuity.json | continuity | NON_EVIDENCE_HANDOFF |
+| contract | TASK | .forgeloop/task-state/<task-key>/contract.json | current-contract | OPERATIONAL_SPECIFICATION |
+| descriptor | TASK | .forgeloop/task-state/<task-key>/task.json | task-descriptor | TASK_DESCRIPTOR |
+| evaluations | TASK | .forgeloop/task-state/<task-key>/evaluations/eval-<id>.json | trajectory-evaluation | TRAJECTORY_EVALUATION |
+| events | TASK | .forgeloop/task-state/<task-key>/events.ndjson | event | AUDIT_LEDGER |
+| executions | TASK | .forgeloop/task-state/<task-key>/executions/exec-<id>.json | execution | EXECUTION_PROVENANCE |
+| gates | TASK | .forgeloop/task-state/<task-key>/gates/<gate>.json | gate | GATE_APPROVAL_ATTESTATION |
+| handoffs | TASK | .forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json | handoff-envelope | CANONICAL_HANDOFF_SNAPSHOT |
+| policyBaseline | PROJECT | .forgeloop/policy/baseline.json | policy-baseline | BROWNFIELD_BASELINE |
+| policyDiscovery | PROJECT | .forgeloop/policy/discovery.json | policy-discovery | DISCOVERED_POLICY_SPECIFICATION |
+| policyLock | PROJECT | .forgeloop/policy/policy.lock | policy-lock | POLICY_INTEGRITY_LOCK |
+| policyRules | PROJECT | .forgeloop/policy/rules.json | policy-rules | POLICY_SPECIFICATION |
+| policySnapshot | TASK | .forgeloop/task-state/<task-key>/policy-snapshot.json | policy-snapshot | TASK_POLICY_ATTESTATION |
+| preflight | TASK | .forgeloop/task-state/<task-key>/preflight.json | preflight | READINESS_ATTESTATION |
+| receipt | TASK | .forgeloop/task-state/<task-key>/execution-receipt.json | execution-receipt | EVIDENCE_COMPILATION |
+| recovery | TASK | .forgeloop/task-state/<task-key>/recovery.json | task-recovery | TASK_RECOVERY_STATE |
+| responsibility | TASK | .forgeloop/task-state/<task-key>/responsibility.json | responsibility | RESPONSIBILITY_CONSTRAINT |
+| route | TASK | .forgeloop/task-state/<task-key>/routing-result.json | routing-result | GUIDE_ROUTING_SPECIFICATION |
+| session | SESSION | .forgeloop/sessions/<session-id>.json | activation | SESSION_MARKER |
+| sources | PROJECT | .forgeloop/sources.json | source-registry | SOURCE_ATTESTATION |
+| state | TASK | .forgeloop/task-state/<task-key>/work-state.json | work-state | CANONICAL_LIFECYCLE_STATE |
+| verificationScope | TASK | .forgeloop/task-state/<task-key>/verification-scope.json | verification-scope | VERIFICATION_SCOPE_PLAN |
+| workspaceBinding | TASK | .forgeloop/task-state/<task-key>/workspace-binding.json | workspace-binding | WORKSPACE_IDENTITY_BINDING |
+
+## Command catalog
+
+### actions
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| action-authorize | MUTATING | Authorizes one PROPOSED durable action through the canonical capability-policy and approval service. |
+| action-propose | MUTATING | Proposes a caller-reported durable action without executing it. |
+| action-reconcile | MUTATING | Reconciles a COMMIT_UNKNOWN action from externally observed evidence without retrying it. |
+| action-record | MUTATING | Records a caller-reported or externally observed non-authority action transition. |
+| action-show | READ_ONLY | Reads one canonical durable action artifact. |
+| action-verify | MUTATING | Verifies a COMMITTED action against independent canonical evidence; caller claims can never verify. |
+| approval-request | MUTATING | Creates a durable fingerprint-bound approval request. |
+| approval-resolve | MUTATING | Resolves one durable approval exactly once. |
+| run-action | EXTERNAL_EXECUTION | Executes one policy-authorized durable action using exact argv and shell:false semantics. |
+
+### attestation
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| attestation-create | MUTATING | Builds a deterministic in-toto ForgeLoop statement from a valid completed task manifest. |
+| attestation-status | READ_ONLY | Reports local ForgeLoop attestation status and trust level without network access. |
+| attestation-verify | READ_ONLY | Verifies a task attestation and current revision without mutating task state. |
+| attestation-verify-range | READ_ONLY | Verifies complete attestation coverage for an opaque revision range through a provider-neutral contract. |
+
+### continuity
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| clear-continuity | MUTATING | Removes continuity.json for the active task without affecting lifecycle work state. |
+| continuity | READ_ONLY | Reads and displays current cross-harness continuity handoff notes. |
+| handoff-create | MUTATING | Creates an immutable protocol-derived handoff snapshot without delegation or review side effects. |
+| handoff-list | READ_ONLY | Lists immutable handoff snapshots for a task. |
+| handoff-show | READ_ONLY | Reads and verifies one immutable handoff snapshot. |
+| reconcile-continuity | READ_ONLY | Reconciles continuity handoff notes with active work state and checkout state. |
+| record-continuity | MUTATING | Persists cross-harness operational continuity handoff notes bound to current state fingerprints. |
+
+### diagnostics
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| doctor | MUTATING | Diagnoses project health, discovers adapters, and optionally repairs missing template files. |
+| eval | MUTATING | Evaluates the current trajectory against a validated project-local reference scenario. |
+| history | READ_ONLY | Shows chronological protocol history reconstructed from canonical ForgeLoop state. |
+| inspect | READ_ONLY | Inspects target repository health, dirty files, active branch, and artifact freshness. |
+| metrics | READ_ONLY | Projects trajectory, action, execution, timing, and known usage metrics without mutating state. |
+| profile-interview | READ_ONLY | Optional interactive or dry-run interview to refine project profile facts. |
+| progress | READ_ONLY | Evaluates task progress across verification cycles and detects stalls deterministically. |
+| protocol-info | READ_ONLY | Reports versioning, lifecycle, command, guide, and public error compatibility metadata for external harnesses. |
+| reflect | READ_ONLY | Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation. |
+| status | READ_ONLY | Displays current lifecycle phase, active checks, blockers, and artifact freshness bindings. |
+| trace | READ_ONLY | Emits detailed structured task trace with provenance and artifact relationships. |
+| validate-protocol | READ_ONLY | Validates end-to-end cryptographic freshness, fingerprint bindings, and ledger integrity. |
+| validate-state | READ_ONLY | Validates schema adherence and internal consistency of work-state.json. |
+
+### lifecycle
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| activate | MUTATING | Emits an active session marker recording sessionId and activationMarker. |
+| advance | MUTATING | Transitions the canonical lifecycle work state to an allowed target phase. |
+| clear-state | MUTATING | Removes work-state.json for the active task only, preserving sibling contract, routing, and ledger files. |
+| complete | MUTATING | Evaluates verification receipt coverage, gates, and ledger integrity to authorize task completion. |
+| next | READ_ONLY | Returns deterministic next-action guidance and command recommendations based on active state. |
+| preflight | MUTATING | Evaluates pre-implementation contract, routing, and gates; synchronizes work state when READY. |
+| reconcile-closure | MUTATING | Refreshes the work-state checkpoint of an EXECUTING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed. |
+| record-decision-criterion | MUTATING | Records an append-only decision settlement criterion bound to the active contract fingerprint. |
+| record-diagnosis | MUTATING | Records an append-only diagnosis event or structured diagnostic case in the lifecycle event ledger. |
+| record-hypothesis-disposition | MUTATING | Records an evidence-bound hypothesis disposition update in the lifecycle event ledger. |
+| record-intervention | MUTATING | Records an append-only intervention bound to hypotheses; the described change is never executed by ForgeLoop. |
+| route | MUTATING | Evaluates task characteristics and deterministically routes required engineering guides. |
+| task-create | MUTATING | Creates a new task descriptor and initializes its isolated task state namespace. |
+| task-list | READ_ONLY | Lists all discovered task descriptors and their current lifecycle phases. |
+| task-lock-status | READ_ONLY | Reports a task lock record and its lease-based stale-lock classification. |
+| task-scope | MUTATING | Updates or inspects write claims for a task before execution. |
+| task-show | READ_ONLY | Shows details of a specific task descriptor and its scoped artifacts. |
+
+### policy-audit
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| baseline | MUTATING | Manages brownfield policy baseline violations with monotonic downward ratcheting. |
+| bundle | MUTATING | Exports current task artifacts into a portable task bundle archive. |
+| policy | READ_ONLY | Evaluates active task state against named enterprise policy packs. |
+| policy-diff | READ_ONLY | Performs semantic diffing between policy versions to detect tightening or weakening. |
+| policy-discover | MUTATING | Discovers repository policy facts and candidate rules deterministically. |
+| policy-status | READ_ONLY | Evaluates repository and task state against effective policy rules and baseline. |
+| rule-verify | READ_ONLY | Verifies policy rules against mutation fixtures to prove detector efficacy. |
+
+### project-maintenance
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| init | MUTATING | Initializes a target project directory with ForgeLoop discovery adapters, schemas, and templates. |
+| migrate-protocol | MUTATING | Safely migrates explicitly supported protocol state; unknown target versions fail without rewriting artifacts. |
+| task-migrate | MUTATING | Migrates a legacy 1.0 singleton task state layout into a task-namespaced layout. |
+| task-recover | MUTATING | Caller-acknowledged recovery of a STALE or ABANDONED task; records durable state and releases effective write claims. |
+| task-repair-legacy-recovery | MUTATING | Migrates one recognized legacy OPERATOR_RECOVERY_RECORDED boundary event into the modern durable recovery representation (append-only; original event unchanged). |
+| task-resume | MUTATING | Reacquires a recovered task's write claims under project serialization and restores ordinary mutation authority. |
+| task-unlock | MUTATING | Removes an orphaned task lock file to recover an interrupted task. |
+| update | MUTATING | Updates installed templates, discovery adapters, and canonical engineering guides to the latest version. |
+
+### scope
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| responsibility-set | MUTATING | Creates immutable, mechanically verifiable constraints for a task pass. |
+| responsibility-status | READ_ONLY | Validates active responsibility constraints against current paths, inputs, and checks. |
+
+### verification
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| audit | READ_ONLY | Performs read-only evaluation of verification receipt coverage and gate satisfaction. |
+| prepare-completion | MUTATING | Initializes execution-receipt.json with empty requirement evidence slots for the active cycle. |
+| record-check | MUTATING | Records structured verification evidence (command, manual review, or test output) against a requirement. |
+| record-terminal-result | MUTATING | Records external terminal result evidence (PUBLICATION or PRODUCTION_READINESS) into receipt. |
+| report | READ_ONLY | Emits a human-readable or structured JSON summary report of protocol state. |
+| run-check | EXTERNAL_EXECUTION | Runs an exact command, records the execution provenance artifact, and binds observed check evidence. |
+| validate-receipt | READ_ONLY | Validates schema conformance and cryptographic bounds of an execution receipt file. |
+| verify-scope | MUTATING | Resolves a provable changed, claimed, full, or unresolved verification boundary without launching checks. |
+
+### workspace
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| workspace-bind | MUTATING | Binds a task to the current Git worktree identity; rebinding is not implicit. |
+| workspace-status | READ_ONLY | Reports whether the current Git worktree matches an optional task binding. |
+
+## Stable boundary and attestation errors
+
+| Code | Meaning |
+| --- | --- |
+| E_ATTESTATION_CONFIGURATION_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_CONTENT_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_CONTRACT_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_COVERAGE_CONFLICT | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_COVERAGE_GAP | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_DISABLED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_GIT_REQUIRED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_IDENTITY_UNTRUSTED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_ISSUER_UNTRUSTED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_LEDGER_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_MANIFEST_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_MANIFEST_MISSING | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_MANIFEST_STALE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_RECEIPT_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_ROUTE_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_SCOPE_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_SIGNATURE_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_SIGNER_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_STATE_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_STATEMENT_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_STATEMENT_MISSING | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_SUBJECT_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_TARGET_REF_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_ATTESTATION_UNSIGNED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_CLI_INVOCATION_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_NOT_FOUND | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_STATE_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_TAMPERED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_RESPONSIBILITY_FROZEN_INPUT_DRIFT | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_RESPONSIBILITY_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_RESPONSIBILITY_REQUIRED_CHECK_MISSING | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_RESPONSIBILITY_SCOPE_VIOLATION | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_REVISION_CONTENT_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_REVISION_NOT_FOUND | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_REVISION_PROVIDER_AMBIGUOUS | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_REVISION_PROVIDER_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_REVISION_PROVIDER_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_VERIFICATION_SCOPE_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_VERIFICATION_SCOPE_STALE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_VERIFICATION_SCOPE_UNRESOLVED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_WORKSPACE_BINDING_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_WORKSPACE_BINDING_MISMATCH | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_WORKSPACE_IDENTITY_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+
+## Authoritative implementation surfaces
+
+- Normative protocol: LOOP_ENGINEERING.md and PROTOCOL_INTEGRATION.md.
+- Artifact contracts: schemas/.
+- Lifecycle and command behavior: src/core/ and src/cli.js.
+- Integration surface: src/integration.js, src/integration.d.ts, and integrations/.
+- User-facing command and artifact references: docs/CLI_REFERENCE.md and docs/ARTIFACT_REFERENCE.md.

package/docs/ARTIFACT_REFERENCE.md

@@ -35,6 +35,13 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `task-state/<task-key>/approvals/approval-<id>.json` | `approval` | Protocol Managed | Append Decision Once | Action Approval Attestation |
 | `policy/capabilities.json` | `capability-policy` | Operator Or Agent | Mutable Configuration | Capability Policy Specification |
 | `task-state/<task-key>/evaluations/eval-<id>.json` | `trajectory-evaluation` | Protocol Compiled | Immutable Once Written | Trajectory Evaluation |
+| `task-state/<task-key>/workspace-binding.json` | `workspace-binding` | Protocol Generated | Immutable After Bind | Workspace Identity Binding |
+| `task-state/<task-key>/handoffs/handoff-<id>.json` | `handoff-envelope` | Protocol Compiled | Immutable Once Written | Canonical Handoff Snapshot |
+| `task-state/<task-key>/responsibility.json` | `responsibility` | Agent Or Harness Constrained | Immutable During Pass | Responsibility Constraint |
+| `task-state/<task-key>/verification-scope.json` | `verification-scope` | Protocol Compiled | Recomputed On Scope Change | Verification Scope Plan |
+| `task-state/<task-key>/attestations/code-manifest.json` | `code-manifest` | Protocol Generated | Immutable Once Written | Content Integrity Snapshot |
+| `task-state/<task-key>/attestations/statement.json` | `in-toto-statement` | Protocol Compiled | Immutable Once Written | Code Attestation Statement |
+| `task-state/<task-key>/attestations/statement.sigstore.json` | `null` | External Signing Provider | External Immutable | External Signature Bundle |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 
@@ -227,6 +234,25 @@ Local ForgeLoop configuration settings and policy bindings.
 - `policy` *(string, optional, minLength: 1)*
 - `requiredGates` *(array<string>, optional)*
 - `requiredEvidence` *(array<string>, optional)*
+- `verification` *(object, optional)*
+  - `checkers` *(array<object>, required)*
+    - `checkId` *(string, required, minLength: 1)*
+    - `scopeMode` *(string, required, const: `PATH_ARGUMENTS`)*
+    - `argvPrefix` *(array<string>, required, minItems: 1)*
+    - `pathInsertion` *(string, required, const: `APPEND`)*
+- `attestation` *(object, optional)*
+  - `mode` *(string, required, enum: `off`, `optional`, `required`)*
+  - `revisionProvider` *(string, required, minLength: 1)*
+  - `requireCompleteCoverage` *(boolean, required)*
+  - `coverage` *(object, required)*
+    - `exclude` *(array<string>, required)*
+  - `signing` *(object, required)*
+    - `provider` *(string, required, enum: `none`, `sigstore`)*
+    - `required` *(boolean, required)*
+    - `policy` *(object, required)*
+      - `issuer` *(string, optional)*
+      - `identities` *(array<string>, required)*
+      - `requireTransparencyLog` *(boolean, required)*
 
 <!-- END FORGELOOP GENERATED: schema:config -->
 
@@ -803,3 +829,203 @@ evidence and never override lifecycle validation.
 - `evaluationFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
 
 <!-- END FORGELOOP GENERATED: schema:trajectory-evaluation -->
+
+### 2.24 `task-state/<taskKey>/workspace-binding.json`
+
+<!-- forgeloop-doc: schema=workspace-binding artifact=.forgeloop/task-state/<task-key>/workspace-binding.json -->
+
+Optional immutable binding between a task and the exact Git repository/worktree
+identity used for protocol mutations. A binding is enforced when present; it
+does not fabricate a binding when absent.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:workspace-binding -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `mode` *(string, required, const: `GIT_WORKTREE`)*
+- `repositoryIdentity` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `workspaceIdentity` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `branchAtBind` *(string or null, required)*
+- `headAtBind` *(string or null, required)*
+- `boundAt` *(string, required, minLength: 1)*
+- `metadata` *(object, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:workspace-binding -->
+
+### 2.25 `task-state/<taskKey>/handoffs/handoff-<id>.json`
+
+<!-- forgeloop-doc: schema=handoff-envelope artifact=.forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json -->
+
+Immutable protocol-derived handoff snapshot. The caller may provide only
+recipient intent; lifecycle state, evidence, continuity, and the artifact
+digest are derived by ForgeLoop. A handoff is not delegation, review,
+completion, or authority evidence.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:handoff-envelope -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `handoffId` *(string, required, pattern: `^handoff-[A-Za-z0-9_-]+$`)*
+- `taskId` *(string, required, minLength: 1)*
+- `createdAt` *(string, required, minLength: 1)*
+- `intent` *(object, required)*
+  - `recipientHint` *(string, optional, minLength: 1)*
+  - `note` *(string, optional, minLength: 1)*
+- `state` *(object, required)*
+  - `phase` *(string, required, minLength: 1)*
+  - `revision` *(integer, required, minimum: 0)*
+  - `verificationCycle` *(integer, required, minimum: 1)*
+  - `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `routeFingerprint` *(string or null, required)*
+  - `repositoryFingerprint` *(object, required)*
+  - `writeClaims` *(array<string>, required)*
+  - `changedPaths` *(array<string>, required)*
+- `evidence` *(object, required)*
+  - `executionRefs` *(array<string>, required)*
+  - `checkIds` *(array<string>, required)*
+- `continuity` *(object, required)*
+  - `ref` *(string, required, minLength: 1)*
+  - `fingerprint` *(string or null, required)*
+- `artifactDigest` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+
+<!-- END FORGELOOP GENERATED: schema:handoff-envelope -->
+
+### 2.26 `task-state/<taskKey>/responsibility.json`
+
+<!-- forgeloop-doc: schema=responsibility artifact=.forgeloop/task-state/<task-key>/responsibility.json -->
+
+Optional immutable pass constraints for allowed paths, read-only paths, frozen
+inputs, and required checks. The constraints are checked at mutation, audit,
+and completion boundaries.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:responsibility -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `label` *(string, required, minLength: 1)*
+- `createdAt` *(string, required, minLength: 1)*
+- `allowedPaths` *(array<string>, required)*
+- `readOnlyPaths` *(array<string>, required)*
+- `requiredCheckIds` *(array<string>, required)*
+- `frozenInputs` *(object, required)*
+  - `contract` *(boolean, optional)*
+  - `route` *(boolean, optional)*
+  - `claims` *(boolean, optional)*
+- `baseline` *(object, required)*
+  - `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `routeFingerprint` *(string or null, required)*
+  - `claimsFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+
+<!-- END FORGELOOP GENERATED: schema:responsibility -->
+
+### 2.27 `task-state/<taskKey>/verification-scope.json`
+
+<!-- forgeloop-doc: schema=verification-scope artifact=.forgeloop/task-state/<task-key>/verification-scope.json -->
+
+Read-only verification planning artifact. `AUTO` resolves to `CHANGED` or
+`CLAIMED` only when a trusted scoped-checker capability is available;
+otherwise it resolves to `FULL`. ForgeLoop does not publish a heuristic
+`IMPACTED` mode.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:verification-scope -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `requestedMode` *(string, required, enum: `AUTO`, `CHANGED`, `CLAIMED`, `FULL`)*
+- `resolvedMode` *(string, required, enum: `CHANGED`, `CLAIMED`, `FULL`, `UNRESOLVED`)*
+- `verificationCycle` *(integer, required, minimum: 1)*
+- `changedPaths` *(array<string>, required)*
+- `claimedPaths` *(array<string>, required)*
+- `selectedPaths` *(array<string>, required)*
+- `reasons` *(array<string>, required)*
+- `fallback` *(null or object, required)*
+- `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `repositoryFingerprint` *(object, required)*
+- `claimsFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `checkerCapabilityFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `createdAt` *(string, required, minLength: 1)*
+
+<!-- END FORGELOOP GENERATED: schema:verification-scope -->
+
+### 2.28 `task-state/<taskKey>/attestations/code-manifest.json`
+
+<!-- forgeloop-doc: schema=code-manifest artifact=.forgeloop/task-state/<task-key>/attestations/code-manifest.json -->
+
+Deterministic raw-byte source-content manifest. Entries are sorted by safe
+slash-separated paths, symlinks are represented by link bytes, Git links are
+represented by provider identities, and `.forgeloop/**` is excluded.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:code-manifest -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `verificationCycle` *(integer, required, minimum: 1)*
+- `capture` *(object, required)*
+  - `mode` *(string, required, enum: `WORKTREE`, `INDEX`, `COMMIT`)*
+  - `revisionProvider` *(string, required, minLength: 1)*
+  - `baseRevision` *(string or null, required)*
+  - `observedRevision` *(string, required, minLength: 1)*
+  - `providerMetadata` *(object, required)*
+- `bindings` *(object, required)*
+  - `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `routeFingerprint` *(string or null, required)*
+  - `stateFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `receiptFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `ledgerSeq` *(integer, required, minimum: 1)*
+  - `ledgerHash` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `entries` *(array<object>, required)*
+  - `path` *(string, required, minLength: 1)*
+  - `sourcePath` *(string, optional, minLength: 1)*
+  - `operation` *(string, required, enum: `ADDED`, `MODIFIED`, `DELETED`, `RENAMED`, `COPIED`, `TYPE_CHANGED`)*
+  - `kind` *(string, required, enum: `FILE`, `SYMLINK`, `GITLINK`, `DELETED`)*
+  - `sha256` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+  - `providerContentId` *(string, optional, minLength: 1)*
+  - `providerMetadata` *(object, optional)*
+- `contentDigest` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+
+<!-- END FORGELOOP GENERATED: schema:code-manifest -->
+
+### 2.29 `task-state/<taskKey>/attestations/statement.json`
+
+<!-- forgeloop-doc: schema=in-toto-statement artifact=.forgeloop/task-state/<task-key>/attestations/statement.json -->
+
+Deterministic in-toto Statement v1 binding a code-manifest digest to the
+completed ForgeLoop evidence tuple. The statement is immutable and does not
+back-reference itself from the execution receipt.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:in-toto-statement -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `_type` *(string, required, const: `https://in-toto.io/Statement/v1`)*
+- `subject` *(array<object>, required, minItems: 1)*
+  - `name` *(string, required, minLength: 1)*
+  - `digest` *(object, required)*
+    - `sha256` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `predicateType` *(string, required, const: `https://forgeloop.dev/attestation/v1`)*
+- `predicate` *(object, required)*
+
+<!-- END FORGELOOP GENERATED: schema:in-toto-statement -->
+
+### 2.30 `task-state/<taskKey>/attestations/statement.sigstore.json`
+
+<!-- forgeloop-doc: external-artifact=.forgeloop/task-state/<task-key>/attestations/statement.sigstore.json -->
+
+Optional external signing-provider bundle. Its presence is not proof of a
+valid signature; verification must be performed by the configured signing
+provider with the requested identity and issuer policy.