@cassiomc1/forgeloop 1.5.0 → 1.6.1

package/THREAT_MODEL.md

@@ -8,6 +8,45 @@ not an agent runtime. It does not execute commands found in those files, call
 an LLM, or publish on behalf of a target. The controls below describe the
 remaining trust boundaries and their executable evidence.
 
+## Durable action boundary
+
+Durable actions make external side effects explicit, but they do not make an
+arbitrary remote system transactional. Side-effecting actions require an
+immutable idempotency key; `COMMIT_UNKNOWN` forbids automatic retry and can be
+resolved only by explicit reconciliation. Capability policy is project-local
+configuration and never creates `HOST_ATTESTED` authority. Current capability
+policy is the source of truth for guidance only after its identity is bound to
+the active policy epoch: historical approvals are consulted
+only when the current policy returns `REQUIRE_APPROVAL`. Approvals bind to the
+action fingerprint, contract fingerprint, task revision, and capability; drift
+makes them stale. Host-bound authorization is exposed as structured guidance
+with no standalone CLI command that could lose the trusted context. `run-action`
+accepts exact argv with `shell: false`, and host-reported actions remain distinct
+from ForgeLoop-executed actions.
+
+Residual limitation: ForgeLoop cannot atomically commit local protocol state
+and an arbitrary external system in one transaction. Idempotency, durable
+intent, evidence, and reconciliation reduce duplicate-effect risk but do not
+provide a universal exactly-once guarantee.
+
+### Hardened durable-action threats (T-DURABLE-01 … T-DURABLE-13)
+
+| ID | Threat | Mitigation | Test evidence |
+| --- | --- | --- | --- |
+| T-DURABLE-01 | Caller walks `PROPOSED -> AUTHORIZED -> STARTED -> COMMITTED -> VERIFIED` through the generic record surface | Generic transitions refuse `AUTHORIZED`/`VERIFIED`; dedicated core services own those transitions and require complete policy-bound or canonical-evidence details | `tests/action-security.test.js`, `tests/action-authorization.test.js`, `tests/action-cli.test.js` |
+| T-DURABLE-02 | Actor marks an externally committed action `NOT_COMMITTED` to enable a duplicate retry | Settling `COMMITTED`/`NOT_COMMITTED` requires trusted out-of-band host attestation plus bounded evidence; actor observations may only record `UNKNOWN` | `tests/action-reconciliation.test.js`, `tests/integration-authority-context.test.js` |
+| T-DURABLE-03 | Actor weakens `capabilities.json` immediately before an action launch | Current capability policy must match the persisted policy lock and task policy snapshot before authorization; drift fails closed before `ACTION_STARTED` (`E_ACTION_POLICY_DRIFT`) | `tests/action-authorization.test.js`, `tests/policy-lock.test.js` |
+| T-DURABLE-04 | Model places `authorityContext` inside tool arguments or command input | Authority context is a separate host-provided parameter excluded from command input schemas; MCP tool registries strip it from args and accept it only from an embedding-controlled provider | `tests/integration-authority-context.test.js`, `integrations/mcp/tests/authority-context.test.js` |
+| T-DURABLE-05 | Command validation failures are misclassified as external ambiguity | Deterministic pre-launch preparation runs before authorization; `ACTION_STARTED` is recorded only after argv normalization, resolution, installation authority, policy identity, and approval validation succeed, so pre-launch failure leaves the action `PROPOSED` with no ambiguity | `tests/run-action.test.js`, `tests/durable-action-hardening.test.js` |
+| T-DURABLE-06 | Exit code 0 is mistaken for verified external state | `COMMITTED` and `VERIFIED` remain separate states; verification requires an independent passed ForgeLoop execution artifact and rejects the action's own commit execution as evidence | `tests/action-verification.test.js`, `tests/action-readiness.test.js` |
+| T-DURABLE-07 | Partial ledger forgery: artifact edits or incomplete transition-like events | Deterministic ledger replay validates revision continuity, fingerprint constancy, legal chronology, modern authorization/verification evidence, reconciliation ordering, and artifact/projection equivalence during audit and completion | `tests/action-ledger-replay.test.js`, `tests/action-security.test.js` |
+| T-DURABLE-08 | Reconciliation mirror replay confusion: one settlement is represented by two events and replay double-applies it | `ACTION_RECONCILED(outcome=COMMITTED)` owns the transition; a following `ACTION_COMMIT_RECORDED(reconciled=true)` is validated as a same-revision non-transition mirror and never increments state/revision; mismatched or orphaned mirrors invalidate the ledger | `tests/action-ledger-replay.test.js`, `tests/durable-action-chains.test.js` |
+| T-DURABLE-09 | Cross-requirement verification substitution: a passed check for requirement A verifies action requirement B | Verification evidence must be an independent passed execution whose immutable `requirement` exactly equals the action's requirement; new required actions cannot omit their requirement | `tests/action-verification.test.js`, `tests/durable-action-chains.test.js`, `tests/action-readiness.test.js` |
+| T-DURABLE-10 | Authority dropped between host and reconciliation core: trusted host supplies authority but an adapter discards it | Top-level `authorityContext` propagates through every command executor (including `action-reconcile` and `action-authorize`) to the core service; actor-controlled input remains stripped and cannot mint trust | `tests/integration-authority-context.test.js`, `integrations/mcp/tests/authority-context.test.js` |
+| T-DURABLE-11 | Post-authorization approval mutation: the approval artifact changes after its fingerprint was bound into `ACTION_AUTHORIZED` | Readiness and audit recompute the canonical approval fingerprint via `validateBoundApprovalFingerprint()` for `REQUIRE_APPROVAL` authorizations; any mismatch yields UNTRUSTED / invalid audit | `tests/approval-fingerprint-integrity.test.js` |
+| T-DURABLE-12 | Stale approval precedence: a pending approval created under an older policy blocks, resurrects, or obscures the current decision | `next` selects the required `PROPOSED` action and evaluates current capability policy first; only `REQUIRE_APPROVAL` validates the approval binding tuple before resolving it. `ALLOW`, `DENY`, and `REQUIRE_AUTHORITY` ignore historical approval state, while `approval-request` refuses unnecessary or weaker approvals | `tests/next-action-policy-guidance.test.js`, `tests/approval-request-policy.test.js` |
+| T-DURABLE-13 | Guidance or approval creation trusts a modified `capabilities.json` before checking the active task policy epoch | `next`, `approval-request`, and `action-authorize` all validate the canonical `loadPolicyIdentity()` result before capability decisions can produce authorization-related behavior; drift fails closed with `E_ACTION_POLICY_DRIFT` and no approval artifact is persisted | `tests/next-action-policy-guidance.test.js`, `tests/approval-request-policy.test.js`, `tests/action-authorization.test.js` |
+
 | Threat | Impact | Trust boundary | Mitigation | Residual limitation | Test evidence |
 | --- | --- | --- | --- | --- | --- |
 | Path traversal | Writes or reads outside the selected target | Target path and every managed relative path | `ensureWithin`, safe-path checks, realpath containment, Windows-drive rejection | A separately privileged process can change the filesystem after validation | `tests/core.test.js`, `tests/portability.test.js`, `tests/fixtures/protocol/invalid/path-traversal.json` |
@@ -42,6 +81,7 @@ remaining trust boundaries and their executable evidence.
 | Unsupported profile fact | Turns an agent decision into a durable user fact | `PROJECT_PROFILE.md` and `.forgeloop/sources.json` | Source IDs, source-kind validation, unknown-reference rejection, and explicit misclassification failures | Arbitrary Markdown semantics still require a human or host-specific parser | `tests/profile-provenance.test.js`, `src/core/profile.js` |
 | Weak verification | Treats a vague or inferred claim as observed evidence | Receipt checks and coverage | Versioned check schema, contradictory-status rejection, observed-evidence requirements, and coverage matrix | Evidence remains local and declarative; it is not a remote attestation service | `tests/evidence-coverage.test.js`, `tests/completion.test.js` |
 | Unattested observed command | An actor supplies `--command "..."` or forged command metadata and makes an unrun process appear to be observed evidence | Check provenance, execution artifact, and process boundary | `run-check` captures exact argv, cwd, resolution, timestamps, exit status, and task/check binding; it classifies before launch, uses `shell: false`, and rejects install-capable resolution without trusted authority. `record-check --command` is metadata only; command `OBSERVED` checks require `FORGELOOP_EXECUTED` plus a valid `executionRef`; completion, audit, protocol validation, and bundles revalidate it | The local execution artifact is not cryptographic remote attestation, and a separately privileged process can alter the target after execution | `tests/run-check.test.js`, `tests/completion-cli.test.js`, `tests/verification-capability.test.js`, `tests/validate-protocol-cli.test.js` |
+| Contradictory execution isolation metadata | A custom execution adapter reports guarantees the host does not enforce, for example `NATIVE_PROJECT` claiming `isolated=true`, an isolated mode claiming `liveProjectWritable=true`, or `SYSTEM_ISOLATED` claiming inherited network access | Verification execution adapter boundary and execution evidence | Adapter results are normalized and validated before evidence persistence: canonical mode/guarantee invariants are intrinsically enforced, isolated execution must use a cwd separate from the protocol project root, and violations fail closed with `E_VERIFICATION_EXECUTION_INVALID` or `E_VERIFICATION_ISOLATION_UNAVAILABLE` | The isolation report is still host-supplied; ForgeLoop validates coherence and policy satisfaction, not the underlying OS enforcement | `tests/verification-execution-isolation.test.js` |
 | Malicious receipt | Turns local claims into false publication or completion claims | Execution receipt JSON | Semantic evidence checks for completion, checks, review, push, commit, and deployment; explicit publication booleans | Evidence text is declarative and must still be reviewed for provenance | `tests/receipt-semantics.test.js`, `tests/observability.test.js` |
 | Malicious task brief | Grants a child task more authority than intended | Delegation brief JSON and host harness | Relative path boundaries, guide/verification/authority checks, secret-free validation, set validation, parent integration ownership | The host harness remains responsible for OS permissions and execution policy | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
 | Artifact content exposure | Sensitive material enters portable artifacts or diagnostics | State, receipt, delegation, evidence, and repository text | Nested key/value detection, shaped marker patterns, scanner coverage, no content echo in errors | Content scanners cannot prove that an unknown encoding is harmless | `tests/security-limits.test.js`, `tests/test_scan_secrets.py`, `scripts/scan_secrets.py` |
@@ -62,7 +102,7 @@ remaining trust boundaries and their executable evidence.
 | Environment-injected trust root | The active actor creates an authority file outside the project target and sets `FORGELOOP_AUTHORITY_FILE` or `FORGELOOP_AUTHORITY_DIR` when invoking ForgeLoop | Actor-controlled process environment versus host-attested runtime authority | Standalone CLI uses `trustMode: NONE`; environment-selected sources are metadata/candidates only and fail with `E_AUTHORITY_UNTRUSTED_SOURCE`; trusted authority requires an internal `HOST_ATTESTED` context not exposed as a self-assertable CLI option | If the host integration allows the actor to mutate or replace the attested source/context, the host trust boundary is compromised | Environment-injection rejection, standalone audit/complete rejection, host-attested positive path |
 | Stale receipt recovery dead-end | Work state changes after preparing a receipt, leaving a mismatch that cannot be refreshed because the old receipt is rejected during re-preparation | Preparation lifecycle and recovery action resolution | Recoverable stale receipt binding in `prepareCompletion`, executable `PREPARE_COMPLETION` return from `next`, atomic refresh of stateFingerprint and changedPaths | Manual file corruption outside CLI commands requires manual diagnostic recovery | `tests/stale-receipt-recovery.test.js`, `tests/next-executability.test.js` |
 | Recursive npm script dispatch | A recognized npm lifecycle script invokes another npm script, which later invokes an installation-capable resolver (e.g. `test` -> `npm run visual` -> `npx package`) | Recognized npm dispatcher semantics before ForgeLoop process launch | Recursive npm-script resolution with cycle detection, maximum depth (16), lifecycle hook inspection, restart special semantics, and fail-closed behavior when the resolver cannot prove the chain is non-installing | Opaque executables may spawn arbitrary descendants. Full descendant-process attestation requires host-level process controls and is outside this release | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
-| npm invocation rewriting and workspace dispatch | npm configuration flags appear before the subcommand, or npm workspace selectors cause script execution to occur against a package.json different from the ForgeLoop target root | Raw npm argv versus effective npm command and execution context | Canonical npm invocation parsing, effective subcommand extraction, workspace flag detection across the full npm argv, and fail-closed workspace script handling when the selected package.json cannot be proven from the current target | ForgeLoop 0.1.15 intentionally does not implement full npm workspace resolution. Users should execute run-check from the selected workspace target directory | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
+| npm invocation rewriting and workspace dispatch | npm configuration flags appear before the subcommand, or npm workspace selectors cause script execution to occur against a package.json different from the ForgeLoop target root | Raw npm argv versus effective npm command and execution context | Canonical npm invocation parsing, effective subcommand extraction, workspace flag detection across the full npm argv, and fail-closed workspace script handling when the selected package.json cannot be proven from the current target | ForgeLoop intentionally does not implement full npm workspace resolution. Users should execute run-check from the selected workspace target directory | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
 | Unclassified npm Install-Capable Command | The npm security classifier recognizes only a small denylist of package-mutating commands. Another official npm command or alias with install/update/bootstrap semantics falls through as a local package command | Effective npm command semantics versus ForgeLoop's command classifier | Semantic npm command classification with explicit install-capable families, explicit script-dispatch families, a deliberately small non-installing allowlist, and fail-closed behavior for unknown or ambiguous npm commands | Future npm commands are blocked until ForgeLoop explicitly classifies them | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
 | Policy weakening bypass | An actor weakens complexity or security thresholds mid-task to bypass verification failures | Task policy snapshot (`policy-snapshot.json`) and semantic policy diff | `policy-diff` classifies rule relaxations as `WEAKEN`, preflight snapshots enforce baseline digests, and `complete` blocks on `E_POLICY_WEAKENING` | A project operator with local filesystem access can authoritatively update project rules | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
 | Inert check evasion | An actor relies on an inert or non-matching checker to create false verification pass | Policy engine checker inspection | Scanned file counters and adapter target checks; unproven or inert project rules trigger `E_CHECK_INERT` | Discovered rules gracefully downgrade to advisory without stopping execution | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |

package/docs/ARTIFACT_REFERENCE.md

@@ -31,6 +31,10 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `policy/policy.lock` | `policy-lock` | Protocol Generated | Atomic Digest Compilation | Policy Integrity Lock |
 | `task-state/<task-key>/policy-snapshot.json` | `policy-snapshot` | Protocol Generated | Mutable Before Execution | Task Policy Attestation |
 | `task-state/<task-key>/recovery.json` | `task-recovery` | Protocol Generated | Recovery State Transitions | Task Recovery State |
+| `task-state/<task-key>/actions/action-<id>.json` | `action` | Protocol Managed | State Machine Transitions | External Action Provenance |
+| `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 |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 
@@ -371,6 +375,16 @@ The cryptographically compiled verification receipt required for task completion
 - `selectedGuides` *(array<string>, required)*
 - `changedPaths` *(array<string>, required)*
 - `checks` *(array<object>, required)*
+- `actions` *(object, optional)*
+  - `count` *(integer, required, minimum: 0)*
+  - `required` *(integer, required, minimum: 0)*
+  - `verified` *(integer, required, minimum: 0)*
+  - `trustedSatisfied` *(integer, optional, minimum: 0)*
+  - `unresolvedRequired` *(integer, optional, minimum: 0)*
+  - `failed` *(integer, required, minimum: 0)*
+  - `ambiguous` *(integer, required, minimum: 0)*
+  - `pending` *(integer, required, minimum: 0)*
+  - `actionRefs` *(array<string>, required)*
 - `evidence` *(array<object>, optional)*
   - `schemaVersion` *(number, optional, const: 1)*
   - `kind` *(string, required, enum: `OBSERVED`, `INFERRED`, `NOT_VERIFIED`, `BLOCKED`)*
@@ -409,8 +423,17 @@ Attested command execution provenance artifact generated by `forgeloop run-check
 - `requirement` *(string, required, minLength: 1)*
 - `verificationCycle` *(integer, required, minimum: 1)*
 - `kind` *(string, required, const: `COMMAND_EXECUTION`)*
+- `executionKind` *(string, optional, enum: `VERIFICATION`, `DURABLE_ACTION`)*
 - `argv` *(array<string>, required, minItems: 1)*
+- `protocolProjectRoot` *(string, optional, minLength: 1)*
 - `cwd` *(string, required, minLength: 1)*
+- `executionIsolation` *(string, optional, enum: `NATIVE_PROJECT`, `PROJECT_ISOLATED`, `SYSTEM_ISOLATED`)*
+- `isolation` *(object, optional)*
+  - `mode` *(string, required, enum: `NATIVE_PROJECT`, `PROJECT_ISOLATED`, `SYSTEM_ISOLATED`)*
+  - `isolated` *(boolean, required)*
+  - `liveProjectWritable` *(boolean, required)*
+  - `networkPolicy` *(string, required, minLength: 1)*
+  - `environmentPolicy` *(string, required, minLength: 1)*
 - `resolution` *(object, required)*
   - `resolutionMode` *(string, required, minLength: 1)*
   - `mayInstall` *(boolean, required)*
@@ -436,6 +459,16 @@ Attested command execution provenance artifact generated by `forgeloop run-check
 
 <!-- END FORGELOOP GENERATED: schema:execution -->
 
+Isolation metadata must be intrinsically truthful. `liveProjectWritable` is an
+enforced host guarantee reported by the trusted execution adapter, not a claim
+implied by a different working directory; a disposable copy alone is
+insufficient. Canonical combinations are `NATIVE_PROJECT` (`isolated=false`,
+`liveProjectWritable=true`), `PROJECT_ISOLATED` (`isolated=true`,
+`liveProjectWritable=false`), and `SYSTEM_ISOLATED` (`isolated=true`,
+`liveProjectWritable=false`, `networkPolicy=DENIED`). Contradictory metadata is
+rejected with `E_VERIFICATION_EXECUTION_INVALID` before the execution artifact
+is persisted, even when the required isolation policy would be `NONE`.
+
 ---
 
 ### 2.13 `task-state/<taskKey>/task.json`
@@ -571,6 +604,7 @@ silently ignored.
 - `digest` *(string, required, minLength: 1)*
 - `rulesDigest` *(string, required)*
 - `baselineDigest` *(string, required)*
+- `capabilityPolicyDigest` *(string, optional, pattern: `^sha256:[a-f0-9]{64}$`)*
 - `capturedAt` *(string, optional)*
 
 <!-- END FORGELOOP GENERATED: schema:policy-lock -->
@@ -599,6 +633,8 @@ comparison explicitly `UNKNOWN` rather than assuming an empty baseline.
 - `rules` *(array<string,object>, required)*
 - `baseline` *(object, optional)*
 - `baselineDigest` *(string, optional)*
+- `capabilityPolicyDigest` *(string, optional, pattern: `^sha256:[a-f0-9]{64}$`)*
+- `capabilityPolicyFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
 - `capturedAt` *(string, optional)*
 
 <!-- END FORGELOOP GENERATED: schema:policy-snapshot -->
@@ -644,3 +680,126 @@ host-owned `grantRef`; the standalone CLI does not self-issue that authority.
   - `grantRef` *(string, optional, minLength: 1)*
 
 <!-- END FORGELOOP GENERATED: schema:task-recovery -->
+
+---
+
+### 2.20 `task-state/<taskKey>/actions/action-<id>.json`
+
+<!-- forgeloop-doc: schema=action artifact=.forgeloop/task-state/<task-key>/actions/action-<id>.json -->
+
+Durable external action artifact recording intent, capability policy binding,
+authority, execution provenance, ambiguity, and reconciliation state for a
+side-effecting operation. The `actionFingerprint` covers immutable identity
+fields only; mutable state lives in `state` and `revision`.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:action -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1, maxLength: 256)*
+- `actionId` *(string, required, pattern: `^action-[A-Za-z0-9_-]+$`)*
+- `actionFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `effectClass` *(string, required, enum: `READ_ONLY`, `REVERSIBLE_WRITE`, `IRREVERSIBLE_WRITE`, `EXTERNAL_PUBLICATION`, `DESTRUCTIVE`)*
+- `capability` *(string, required, enum: `filesystem.read`, `filesystem.write`, `process.execute`, `dependency.install`, `network.read`, `network.write`, `repository.commit`, `repository.push`, `repository.pull_request`, `external.publish`, `external.delete`, `deployment.execute`)*
+- `operation` *(string, required, minLength: 1, maxLength: 512)*
+- `target` *(string, required, minLength: 1, maxLength: 512)*
+- `idempotencyKey` *(string or null, required)*
+- `requiredForCompletion` *(boolean, required)*
+- `requirement` *(string or null, required)*
+- `provenance` *(string, required, enum: `FORGELOOP_EXECUTED`, `HOST_ATTESTED`, `CALLER_REPORTED`, `HOST_REPORTED`, `EXTERNAL_OBSERVED`)*
+- `state` *(string, required, enum: `PROPOSED`, `AUTHORIZED`, `STARTED`, `COMMITTED`, `VERIFIED`, `FAILED`, `COMMIT_UNKNOWN`, `CANCELLED`)*
+- `revision` *(integer, required, minimum: 0)*
+- `createdAt` *(string, required, minLength: 1)*
+- `updatedAt` *(string, required, minLength: 1)*
+- `lastEvidenceRef` *(string or null, optional)*
+- `lastReconciliationAt` *(string or null, optional)*
+- `commitResultCode` *(object or null, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:action -->
+
+---
+
+### 2.21 `task-state/<taskKey>/approvals/approval-<id>.json`
+
+<!-- forgeloop-doc: schema=approval artifact=.forgeloop/task-state/<task-key>/approvals/approval-<id>.json -->
+
+Crash-safe durable approval request cryptographically bound to the exact action
+fingerprint, contract fingerprint, task revision, and capability. Any drift
+makes the approval stale. Resolution is one-time; approvals persist across
+process and harness boundaries.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:approval -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1, maxLength: 256)*
+- `approvalId` *(string, required, pattern: `^approval-[A-Za-z0-9_-]+$`)*
+- `actionId` *(string, required, pattern: `^action-[A-Za-z0-9_-]+$`)*
+- `actionFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `taskRevision` *(integer, required, minimum: 0)*
+- `capability` *(string, required, enum: `filesystem.read`, `filesystem.write`, `process.execute`, `dependency.install`, `network.read`, `network.write`, `repository.commit`, `repository.push`, `repository.pull_request`, `external.publish`, `external.delete`, `deployment.execute`)*
+- `status` *(string, required, enum: `PENDING`, `APPROVED`, `REJECTED`)*
+- `requestedAt` *(string, required, minLength: 1)*
+- `reason` *(string or null, optional)*
+- `decision` *(string, optional, enum: `APPROVED`, `REJECTED`)*
+- `resolvedAt` *(string or null, optional)*
+- `authorityKind` *(string, optional, enum: `CALLER_ACKNOWLEDGED`, `HOST_ATTESTED`)*
+- `hostGrantRef` *(string or null, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:approval -->
+
+---
+
+### 2.22 `policy/capabilities.json`
+
+<!-- forgeloop-doc: schema=capability-policy artifact=.forgeloop/policy/capabilities.json -->
+
+Project-local machine-readable capability policy mapping canonical capability
+values to ALLOW, DENY, REQUIRE_AUTHORITY, or REQUIRE_APPROVAL decisions. This
+artifact is policy specification only; it can never mint host authority.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:capability-policy -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `defaultDecision` *(string, required, enum: `ALLOW`, `DENY`)*
+- `rules` *(array<object>, required)*
+  - `capability` *(string, required, enum: `filesystem.read`, `filesystem.write`, `process.execute`, `dependency.install`, `network.read`, `network.write`, `repository.commit`, `repository.push`, `repository.pull_request`, `external.publish`, `external.delete`, `deployment.execute`)*
+  - `decision` *(string, required, enum: `ALLOW`, `DENY`, `REQUIRE_AUTHORITY`, `REQUIRE_APPROVAL`)*
+
+<!-- END FORGELOOP GENERATED: schema:capability-policy -->
+
+---
+
+### 2.23 `task-state/<taskKey>/evaluations/eval-<id>.json`
+
+<!-- forgeloop-doc: schema=trajectory-evaluation artifact=.forgeloop/task-state/<task-key>/evaluations/eval-<id>.json -->
+
+Immutable trajectory evaluation result compiled from the canonical trace against
+a project-local reference scenario. Evaluations are projections over canonical
+evidence and never override lifecycle validation.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:trajectory-evaluation -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `evaluationId` *(string, required, pattern: `^eval-[A-Za-z0-9_-]+$`)*
+- `scenarioId` *(string, required, minLength: 1, maxLength: 128)*
+- `scenarioFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `taskId` *(string, required, minLength: 1, maxLength: 256)*
+- `result` *(string, required, enum: `PASS`, `FAIL`)*
+- `completionValid` *(boolean, required)*
+- `safetyValid` *(boolean, required)*
+- `missingMilestones` *(array<string>, optional)*
+- `limits` *(object, optional)*
+- `efficiency` *(object or null, optional)*
+- `computedAt` *(string, optional, minLength: 1)*
+- `source` *(string, optional, enum: `PROJECT_LOCAL_REFERENCE`)*
+- `evaluationFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+
+<!-- END FORGELOOP GENERATED: schema:trajectory-evaluation -->

package/docs/CLI_REFERENCE.md

@@ -39,11 +39,12 @@ ForgeLoop uses a definition-driven command-line parser:
 
 | Category | Commands |
 | --- | --- |
-| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **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-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) |
+| **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) |
+| **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) |
 
 <!-- END FORGELOOP GENERATED: cli-command-index -->
@@ -52,6 +53,163 @@ ForgeLoop uses a definition-driven command-line parser:
 
 ## 1. Setup & Maintenance
 
+## Durable Actions, Approvals, and Trajectory
+
+ForgeLoop is still a protocol/evidence layer, not an agent runtime. Use
+`COMMIT_UNKNOWN` as a hard stop: do not retry until an external observation is
+recorded with `action-reconcile`. `run-action` has no shell mode and executes
+only exact argv. Caller-reported and externally observed provenance are not host authority, and a project capability policy cannot mint host authority.
+
+### `run-action`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:run-action: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)
+- `--action <id>`: stable durable action ID
+- `--capability <capability>`: canonical action capability
+- `--effect-class <class>`: durable action effect class
+- `--target <target>`: bounded external action target
+- `--idempotency-key <key>`: immutable logical action idempotency key
+- `--requirement <id>`: bound completion requirement
+- `--required-for-completion`: mark the action as required for completion
+- `--approval <id>`: current fingerprint-bound approval
+- `--timeout-ms <number>`: maximum command duration before termination
+- `-- <argv...>`: exact command argv; shell mode is never used
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:run-action:options -->
+
+### `action-propose`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-propose: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>`: stable action ID
+- `--capability <capability>`: canonical capability
+- `--effect-class <class>`: effect class
+- `--target <target>`: bounded action target
+- `--operation <text>`: bounded operation description
+- `--idempotency-key <key>`: logical action idempotency key
+- `--requirement <id>`: bound requirement
+- `--required-for-completion`: mark required for completion
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-propose:options -->
+
+### `action-record`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-record: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)
+- `--action <id>`: durable action ID
+- `--state <state>`: next canonical action state
+- `--provenance <value>`: CALLER_REPORTED or EXTERNAL_OBSERVED
+- `--evidence-ref <ref>`: bounded external evidence reference
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-record:options -->
+
+### `action-show`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-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)
+- `--action <id>`: durable action ID
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-show:options -->
+
+### `action-verify`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-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)
+- `--action <id>`: durable action ID
+- `--evidence <ref>`: canonical execution or check reference proving the postcondition
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-verify:options -->
+
+### `action-authorize`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-authorize: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)
+- `--action <id>`: durable action ID
+- `--approval <id>`: current fingerprint-bound approval
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-authorize:options -->
+
+### `action-reconcile`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-reconcile: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)
+- `--action <id>`: ambiguous durable action ID
+- `--outcome <outcome>`: externally observed reconciliation outcome
+- `--evidence-ref <ref>`: bounded external evidence reference (repeatable)
+- `--observed-at <timestamp>`: external observation timestamp
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-reconcile:options -->
+
+### `metrics`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:metrics: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 trajectory metrics as JSON
+
+<!-- END FORGELOOP GENERATED: cli:metrics:options -->
+
+### `eval`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:eval: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)
+- `--scenario <path>`: project-local trajectory scenario JSON
+- `--json`: emit evaluation as JSON
+
+<!-- END FORGELOOP GENERATED: cli:eval:options -->
+
+### `approval-request`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:approval-request: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)
+- `--approval <id>`: approval artifact ID
+- `--action <id>`: bound action ID
+- `--reason <text>`: bounded approval reason
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:approval-request:options -->
+
+### `approval-resolve`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:approval-resolve: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)
+- `--approval <id>`: approval artifact ID
+- `--decision <decision>`: approval decision
+- `--authority <kind>`: CALLER_ACKNOWLEDGED or HOST_ATTESTED
+- `--host-grant-ref <ref>`: host boundary grant reference
+- `--reason <text>`: bounded resolution reason
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:approval-resolve:options -->
+
 ### `protocol-info`
 
 Reports the public compatibility handshake required by external ForgeLoop harnesses.
@@ -496,6 +654,7 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
 
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--file <path>`: structured diagnostic case JSON file (mutually exclusive with legacy diagnosis fields)
 - `--hypothesis <text>`: specific root-cause hypothesis explaining the verification failure
 - `--failure-class <class>`: canonical failure class taxonomy
 - `--evidence-ref <check-id>`: reference to failed/blocked check from current cycle (repeatable)
@@ -516,6 +675,63 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
     --next-safe-action="Adjust offset +1 in slice.js"
   ```
 
+### `record-intervention`
+
+Records an append-only intervention bound to hypotheses; the described change is never executed by ForgeLoop.
+
+- **Purpose**: Records corrective or experimental changes (code, config, tests, instrumentation) associated with one or more hypotheses.
+- **When to use**: In `CORRECTING` phase after a structured diagnostic case has been recorded.
+- **Mutation**: Appends `INTERVENTION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-intervention: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)
+- `--file <path>`: intervention JSON file describing the recorded change (never executed)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-intervention:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-intervention --task checkout --file intervention.json --json
+  ```
+
+### `record-hypothesis-disposition`
+
+Records an evidence-bound hypothesis disposition update in the lifecycle event ledger.
+
+- **Purpose**: Updates hypothesis status (SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, UNRESOLVED) based on recorded evidence.
+- **When to use**: After new verification evidence resolves an open hypothesis.
+- **Mutation**: Appends `HYPOTHESIS_DISPOSITION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-hypothesis-disposition: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)
+- `--hypothesis <id>`: existing hypothesis ID to disposition
+- `--status <status>`: SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, or UNRESOLVED
+- `--evidence-ref <check-id>`: check ID supporting this disposition (repeatable)
+- `--reason <text>`: evidence-bound reason for the disposition
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-hypothesis-disposition:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-hypothesis-disposition \
+    --task checkout \
+    --hypothesis h-timeout-latency \
+    --status SUPPORTED \
+    --evidence-ref checkout-tests \
+    --reason "Instrumented dependency time exceeded the timeout." \
+    --json
+  ```
+
 ### `validate-state`
 
 Validates `.forgeloop/task-state/<taskKey>/work-state.json` structure, hash chain, and repository binding.
@@ -821,7 +1037,7 @@ Displays human-readable or structured summary of current task state.
 
 ### `inspect`
 
-Inspects checkout changes and compares them against contract deliverables.
+Inspects checkout changes and compares them against contract deliverables. With `--task <id>`, human output renders a task inspection report (phase, cycle, ledger/snapshot health, progress, verification attempts, diagnostics, failure surface, signals, next command); `--json` keeps the full additive `taskInspection` section.
 
 - **Purpose**: Shows modified files, untracked files, and deliverable coverage.
 - **Mutation**: Read-only.
@@ -842,6 +1058,81 @@ Inspects checkout changes and compares them against contract deliverables.
   forgeloop inspect --json
   ```
 
+### `history`
+
+Shows chronological protocol history reconstructed from canonical ForgeLoop state.
+
+- **Purpose**: Answers "what happened during this task?" with deterministic, read-only reconstruction from the event ledger.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:history: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)
+- `--type <list>`: comma-separated event types or categories to include
+- `--phase <list>`: comma-separated lifecycle phases to include
+- `--failures`: show only failed/blocked verification events
+- `--checks`: show only verification events
+- `--since <timestamp>`: include events at or after this timestamp
+- `--until <timestamp>`: include events at or before this timestamp
+- `--limit <number>`: show only the last N events after filtering
+- `--compact`: one line per event
+- `--verbose`: show full event data
+- `--json`: emit structured history output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:history:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop history --task auth-feature --json
+  ```
+
+### `trace`
+
+Emits detailed structured task trace with provenance and artifact relationships.
+
+- **Purpose**: Machine-readable protocol reconstruction consumed by history, reflect, task-level inspect, and external integrations.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:trace: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 structured trace output as JSON (default rendering is a summary)
+
+<!-- END FORGELOOP GENERATED: cli:trace:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop trace --task auth-feature --json
+  ```
+
+### `reflect`
+
+Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation.
+
+- **Purpose**: Whole-task retrospective that reports whether the run actually learned anything, without calling an LLM.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:reflect: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 structured reflection output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:reflect:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop reflect --task auth-feature --json
+  ```
+
 ### `policy`
 
 Evaluates compliance against a named policy pack.