@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/README.md

@@ -75,6 +75,15 @@ forgeloop next --task demo --json
 O último comando informa a ação segura seguinte; ele não executa código nem
 agenda agentes.
 
+### Ações externas duráveis
+
+Para efeitos externos, registre a intenção com `action-propose`, aplique a
+política de capacidade e a aprovação vinculada ao fingerprint, e execute apenas
+com `run-action` usando argv exato. Um resultado `COMMIT_UNKNOWN` nunca é
+repetido automaticamente: observe o sistema externo e use `action-reconcile`.
+As métricas mantêm tokens/custos como desconhecidos quando o host não os
+fornece, e eficiência só existe quando um cenário de referência foi declarado.
+
 Antes de um harness criar ou retomar uma tarefa, ele pode confirmar a
 compatibilidade pública sem depender de detalhes internos:
 
@@ -195,6 +204,15 @@ forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --
 # List active and completed tasks
 forgeloop task-list --json
 
+# Ask for deterministic conflict/recovery guidance
+forgeloop next --task auth-feature --json
+
+# Only for a task classified STALE or ABANDONED: release effective claims
+forgeloop task-recover --task auth-feature --acknowledge-recovery --json
+
+# Reacquire conflict-free claims before mutating a recovered task again
+forgeloop task-resume --task auth-feature --json
+
 # Run standard lifecycle commands targeting the task
 forgeloop route --task auth-feature --work clean-code --surface backend
 forgeloop preflight --task auth-feature --json
@@ -205,6 +223,16 @@ forgeloop complete --task auth-feature --json
 forgeloop task-migrate --json
 ```
 
+Recovery is not completion. Effective claims become empty only when the
+canonical claim-state resolver validates the relationship between `task.json`,
+`work-state.json`, `recovery.json`, and the complete hash-chained recovery
+history. Fake, missing, corrupt, deleted, or mismatched recovery evidence is
+`INCONSISTENT`: historical claims remain reserved and mutation remains
+disabled. The standalone acknowledgement flag is not host-attested authority.
+`task-resume` removes recovery state only after validated ownership, stale-lock
+settlement, normal claim-overlap, and clean-checkout checks succeed. Never
+create, edit, or delete `recovery.json` manually.
+
 ### Executable policy verification & brownfield baselines
 
 ForgeLoop enforces automated, non-interactive verification rules (`rules.json`) with zero interactive dependencies:
@@ -241,12 +269,24 @@ See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.
 
 ## Architecture flow
 
-The canonical source is [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd),
-and the committed render is [`docs/assets/forgeloop-flow.svg`](./docs/assets/forgeloop-flow.svg).
+The canonical source is the typed Archify workflow
+[`docs/diagrams/forgeloop-engineering-flow.workflow.json`](./docs/diagrams/forgeloop-engineering-flow.workflow.json).
+The committed animated interactive explorer is
+[`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html),
+which opens in the dark presentation stage and traces the workflow. The
+animated, self-contained SVG fallback is
+[`docs/assets/diagrams/forgeloop-engineering-flow.svg`](./docs/assets/diagrams/forgeloop-engineering-flow.svg),
+and the deterministic hash receipt is
+[`docs/assets/diagrams/forgeloop-engineering-flow.receipt.json`](./docs/assets/diagrams/forgeloop-engineering-flow.receipt.json).
+The governance source is [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json),
+and the source-bound visual approval is kept in
+[`docs/diagrams/reviews/forgeloop-engineering-flow.review.json`](./docs/diagrams/reviews/forgeloop-engineering-flow.review.json).
 The broader architecture and boundaries are in
 [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
 
-![ForgeLoop evidence-first engineering flow](./docs/assets/forgeloop-flow.svg)
+[Open the animated ForgeLoop evidence-first engineering flow](./docs/assets/diagrams/forgeloop-engineering-flow.html)
+
+![ForgeLoop evidence-first engineering flow (animated SVG fallback)](./docs/assets/diagrams/forgeloop-engineering-flow.svg)
 
 Text-only fallback: discovery creates the contract and route; required gates
 and `PREFLIGHT_READY` authorize execution; verification creates structured
@@ -272,6 +312,11 @@ Consumers must reject unknown artifact fields rather than silently treating
 unrecognized protocol data as valid. The compatibility marker is
 [`tests/fixtures/compatibility/protocol-v1.json`](./tests/fixtures/compatibility/protocol-v1.json).
 
+A project containing active task recovery state requires ForgeLoop 1.4.0 or
+newer. A reader that does not advertise
+`features.taskClaimRecovery.validatedClaimProjection=true` must fail closed;
+it must not infer current ownership from `task.json` or `recovery.json` alone.
+
 ## Security and dependency boundary
 
 The runtime uses Node built-ins only and does not install agents, providers,
@@ -281,9 +326,10 @@ values are checked; and install-capable verification requires trusted host
 authority. See [`THREAT_MODEL.md`](./THREAT_MODEL.md) for the full inventory.
 
 Development tooling is intentionally separate from runtime dependencies. The
-repository policy allows only ESLint, c8, and Mermaid CLI as development
-dependencies; `npm run dependency:policy` fails if runtime or unapproved
-dependencies appear.
+repository policy allows only ESLint and c8 as development dependencies;
+`npm run dependency:policy` fails if runtime or unapproved dependencies
+appear. The documentation renderer is vendored and pinned under
+`vendor/archify/v2.15.0/` rather than installed as a package dependency.
 
 Para reportar vulnerabilidades ou contribuir com alterações, consulte
 [`SECURITY.md`](./SECURITY.md) e [`CONTRIBUTING.md`](./CONTRIBUTING.md).
@@ -353,7 +399,7 @@ npm run lint
 npm run coverage
 npm run pack:check
 npm run dependency:policy
-npm run docs:flow
+npm run docs:diagrams
 npm run docs:check
 ```
 
@@ -363,8 +409,8 @@ npm run docs:check
 src/                    npm CLI and protocol implementation
 schemas/                versioned artifact schemas
 ENG/                    package-source engineering guides
-docs/forgeloop-flow.mmd canonical Mermaid source
-docs/assets/            committed diagram render
+docs/diagrams/          typed Archify diagram source and inventory
+docs/assets/diagrams/   committed HTML, SVG, and generation receipt
 scripts/                checks, renderer, release identity, CI notes
 tests/                  Node and Python regression coverage
 .forgeloop/             project-scoped ForgeLoop configuration
@@ -378,3 +424,17 @@ Task-scoped mutable protocol state is stored under
 
 For document ownership, guide routing, capability degradation, and integration
 details, start at [`DOCS_INDEX.md`](./DOCS_INDEX.md).
+
+## Programmatic integration and MCP
+
+ForgeLoop exposes a stable programmatic surface:
+
+```js
+import { executeForgeLoopCommand } from "@cassiomc1/forgeloop/integration";
+```
+
+The local MCP server (`@cassiomc1/forgeloop-mcp`, stdio) is an adapter over
+this exact API — it never reimplements ForgeLoop. See
+[`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) and
+[`docs/MCP.md`](./docs/MCP.md). MCP is optional; the CLI and instruction-only
+hosts remain fully supported without it.

package/TERMINOLOGY.md

@@ -18,9 +18,24 @@
 | Runtime | A process that owns execution, scheduling, model calls, or persistence; `ForgeLoop` intentionally does not provide one. |
 | Evidence kind | One of `OBSERVED`, `INFERRED`, `NOT_VERIFIED`, or `BLOCKED`; evidence never upgrades an unverified claim by itself. |
 | Required artifact | A checkpoint-recorded relative path and SHA-256 hash that must still match before resume. |
+| Integration API | The stable programmatic surface (`@cassiomc1/forgeloop/integration`) used by structured consumers instead of parsing CLI output. |
+| MCP adapter | The local-first Model Context Protocol server package; an adapter over canonical ForgeLoop commands, never a second implementation. |
+| Server mode | The MCP launch policy tier (`readonly`, `safe`, `full`) that determines which tool classes are available. |
+| Launch capability | A process-scoped, immutable MCP flag (`--allow-*`) required by higher-risk invocation classes; tool input cannot grant it. |
+| Claim state | Canonical ownership classification (`ACTIVE`, `RELEASED_BY_COMPLETION`, `RELEASED_BY_RECOVERY`, `INCONSISTENT`) produced only by the validated claim resolver. |
+| Historical write claims | Claims recorded as evidence in the task descriptor/recovery history after validated release. |
+| Effective write claims | The claims currently enforced against overlapping acquisition; empty only for validated completion or recovery. |
+| Completion ownership proof | The validated lifecycle/ledger evidence (canonical `COMPLETION_VALIDATED` + coherence) required before COMPLETE releases claims. |
+| Caller acknowledgement | Explicit current-caller authorization for recovery actions; never equivalent to host attestation. |
+| Legacy recovery migration | The narrow append-only repair that materializes one recognized historical recovery boundary into the modern durable representation. |
 | Conformance | Relationship validation across route, state, receipt, task brief, and delegated-result artifacts. |
 | Universal applicability | ForgeLoop applies whenever an execution environment discovers a project adapter, regardless of model, provider, agent, IDE, or tool name. |
 | Integration level | The capability tier of an execution environment (`INSTRUCTION_DISCOVERED`, `PROTOCOL_CAPABLE`, `PROTOCOL_LIMITED`, `CONFORMANCE_VERIFIED`). |
+| Recovered task | A non-terminal task whose ordinary mutation authority is suspended and whose effective write claims are released by durable `recovery.json` state. |
+| Recovery acknowledgement | A caller declaration that it intends to recover a task classified `STALE` or `ABANDONED`; it is not a host-attested authority grant. |
+| 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. |
 
 | 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/THIRD_PARTY_NOTICES.md

@@ -64,6 +64,21 @@ inclusion does not install, bundle, or declare any project as a dependency of
 this collection. Check the specific project's current license, terms,
 dependencies, version, and distribution conditions before adoption.
 
+### Archify v2.15.0 — vendored documentation renderer
+
+- Project/source: [tt-a1i/archify](https://github.com/tt-a1i/archify/tree/v2.15.0).
+- Pinned source commit: `e1ac748f19cf805e44bf74fb93c796662152e273`.
+- License declared by the upstream project: MIT; the vendored license is at
+  `vendor/archify/v2.15.0/archify/LICENSE`.
+- Use in this collection: deterministic generation and validation of the
+  typed workflow diagram under `docs/diagrams/`.
+- Boundary: this is a documentation-only vendored toolchain, not a ForgeLoop
+  runtime dependency. It is not installed from a registry, and its exact pin,
+  source, license, and raw-byte tree hashes are recorded in
+  `vendor/archify/v2.15.0/PIN.json`; output hashes are recorded in the receipt.
+  The vendor integrity check rejects modified, missing, extra, renamed, or
+  symlinked files before the renderer is trusted.
+
 ### Superpowers
 
 - Project: [Superpowers](https://github.com/obra/superpowers).
@@ -195,3 +210,18 @@ The contextual frontend taste guide is informed by Taste Skill:
 ForgeLoop includes a short, adapted guide under `ENG/taste-frontend-eng.md`.
 It does not vendor upstream runtime code, depend on its repository at runtime,
 or make its prescriptive examples universal.
+
+## Runtime dependencies with upstream notices
+
+### Model Context Protocol SDK (MCP package only)
+
+- Packages: `@modelcontextprotocol/server` and `@modelcontextprotocol/client`
+  (test/smoke only), used by `integrations/mcp`. Published from the canonical
+  upstream repository:
+  [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk).
+- License declared by the upstream project: MIT.
+- Use in this collection: official SDK transport/server primitives for the
+  local stdio ForgeLoop MCP adapter.
+- Boundary: the ForgeLoop core package (`@cassiomc1/forgeloop`) has no
+  dependency on the MCP SDK; the SDK ships only inside
+  `@cassiomc1/forgeloop-mcp`. Review upstream terms before redistribution.

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` |
@@ -18,7 +57,26 @@ remaining trust boundaries and their executable evidence.
 | Forged preparation | Makes an agent's prose claim look like a completed preflight | Contract, route, gate, and preflight artifacts | Canonical SHA-256 fingerprints, guide-declared gate requirements, stale-artifact checks, and `E_*` failures | The CLI cannot stop a separate process from writing project files before preflight | `tests/protocol-artifacts.test.js`, `tests/preflight.test.js` |
 | Chronology rewrite | Hides execution before route, gates, or verification | `.forgeloop/events.ndjson` | Append-only local ledger, sequence numbers, hash chaining, and chronology validation without prompts or hidden reasoning | A privileged process can still replace the ledger after validation | `tests/lifecycle.test.js` |
 | Concurrent protocol mutation | Two writers read the same state or ledger tail and silently overwrite each other | Task state, task event ledger, and transaction journal | Mutations acquire a lease-bearing task lock, stage writes in `.forgeloop/.txn/`, preserve a recovery manifest, and publish only after the callback completes; state mutators use an expected revision, while ledger appends validate a tail checkpoint and stage only a synchronized suffix | The filesystem does not provide a multi-file atomic commit primitive; a process killed during append is recovered by truncating to the journaled pre-append size rather than treated as complete | `tests/state-revision.test.js`, `tests/concurrent-ledger.test.js`, `tests/scale-ledger.test.js`, `tests/transaction.test.js` |
-| Stale lock theft | A live process loses exclusive ownership because another process removes its lock | `.forgeloop/locks/<taskKey>.lock` | Locks record hostname, owner instance ID, heartbeat, and lease; inspection classifies `LIVE`, `STALE`, or `UNKNOWN`; ordinary recovery releases only an expired lease and `--force` is explicit | A malicious or separately privileged actor can still delete local locks | `tests/task-cli.test.js`, `tests/task-foundation.test.js` |
+| Stale lock theft | A live process loses exclusive ownership because another process removes or replaces its lock | `.forgeloop/locks/<taskKey>.lock` | Locks record hostname, owner instance ID, heartbeat, and lease; inspection distinguishes `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`; stale-only release quarantines the observed inode and compares lock ID, heartbeat, and owner instance before deletion | A malicious or separately privileged actor can still delete local locks; an expired lease remains a recovery heuristic rather than remote liveness proof | `tests/task-lock.test.js`, `tests/task-recover.test.js` |
+| Forged recovery tombstone | A schema-valid fake `recovery.json` makes historical claims disappear without an official recovery event | Task descriptor, recovery artifact, and complete event ledger | The canonical claim-state resolver releases claims only when every artifact field matches one unresolved recovery history cycle; a tombstone alone is `INCONSISTENT`, retains historical claims, and disables mutation | A privileged actor can replace every linked local artifact; validation proves consistency, not remote attestation | `tests/task-claim-state.test.js`, `tests/task-claim-ownership-integration.test.js`, `tests/task-recovery-invariants.test.js` |
+| Forged completion claim release | An actor changes `work-state.phase` to `COMPLETE` to make write claims disappear without canonical completion | Work state, canonical completion event, and the complete validated event ledger | Claim ownership releases COMPLETE claims only when state and a validated lifecycle ledger prove canonical completion (`COMPLETION_VALIDATED` bound to the task, coherent state/ledger, no contradicting later lifecycle event); otherwise ownership is `INCONSISTENT` with historical claims retained, mutation disabled, and overlapping acquisition blocked (`E_COMPLETION_OWNERSHIP_UNPROVEN`) | A separately privileged actor can rewrite all local artifacts consistently; ForgeLoop provides consistency verification, not external cryptographic attestation | `tests/completion-claim-ownership.test.js`, `tests/task-claim-state.test.js` |
+| Incomplete task-lock identity theft | A structurally incomplete persisted task lock (missing lockId, owner instance, operation, or lease) with plausible timestamps is classified LIVE/STALE and removed as stale | `.forgeloop/locks/<taskKey>.lock` identity validation | Task lock identity requires `taskId`, `lockId`, `ownerInstanceId`, `operation`, heartbeat, and a positive integer lease; incomplete metadata classifies `UNKNOWN` (never stale-releasable), lease values are never defaulted at validation time, and CAS release additionally requires `lock.taskId === requested taskId` plus unchanged observed identity | A privileged writer can still forge a fully identified lock; classification proves structure, not liveness | `tests/task-lock.test.js` |
+| Partial already-repaired relationship | A tampered recovery artifact (claims, classification, revision, fingerprint, or authority edited after migration) is accepted as an idempotent already-repaired no-op | Full canonical relationship validation in `alreadyRepaired` | Idempotency requires the complete validated ownership projection (`RELEASED_BY_RECOVERY` with matching recovery id/seq) and every artifact field agreeing with the canonical migration event; any mismatch fails closed | A separately privileged actor can rewrite all local artifacts consistently; validation proves consistency, not attestation | `tests/task-repair-legacy-recovery.test.js` |
+| Forged legacy-migration authority | A forged `LEGACY_RECOVERY_MIGRATION_RECORDED` claims `HOST_ATTESTED` authority to impersonate a host grant | Migration event authority validation | Legacy migration v1 accepts only `CALLER_ACKNOWLEDGED`; any other authority kind makes the event invalid and the ledger INCONSISTENT | Normal recovery events retain their own host-attestation boundary with trusted grant references | `tests/task-repair-legacy-recovery.test.js` |
+| MCP project-root substitution | A tool call supplies a different project root to read or mutate an unintended target | Immutable server-pinned project context | The ForgeLoop MCP server realpaths the project root once at startup and freezes it; project root is never a tool input | A privileged local process can still target other roots by launching its own server | `integrations/mcp/tests/` |
+| MCP claim-projection fork | An adapter derives claim ownership from raw artifacts (task.json, recovery.json) and disagrees with the canonical resolver | Canonical ownership resource | The `task/ownership` resource is derived exclusively from `resolveTaskClaimState()`; forged COMPLETE stays INCONSISTENT with retained claims through the resource surface | Presentation bugs could still mislabel values; the resolver remains the single authority | `integrations/mcp/tests/ownership.test.js`, `tests/integration-resources.test.js` |
+| MCP capability escalation via tool input | Tool input (e.g. `force: true`, `acknowledgeRecovery: true`) elevates a server started without the matching capability | Launch-level capability gates re-checked per invocation | Risk classification is invocation-level; disabled capabilities refuse with `E_MCP_CAPABILITY_DISABLED`; recovery acknowledgement never upgrades launch policy; legacy repair stays hidden by default; deprecated `operatorAuthorized` is absent from schemas | A separately authorized local actor can restart the server in full mode | `integrations/mcp/tests/policy.test.js`, `integrations/mcp/tests/safety.test.js` |
+| MCP HTTP unauthenticated remote bind | A network-bound MCP endpoint exposes ForgeLoop operations to any reachable client without authentication | Loopback-only bind policy | The HTTP transport refuses every non-loopback bind with `E_MCP_REMOTE_NOT_SUPPORTED`; Host/Origin validation is defense against DNS rebinding, not authentication; remote access stays disabled until a separately designed authenticated boundary exists | A same-host process can still reach the loopback endpoint | `integrations/mcp/tests/http.test.js` |
+| MCP protocol downgrade / legacy fallback | Legacy-era traffic is silently served, weakening the declared 2026 security posture | Strict modern mode | The HTTP handler is constructed with the SDK strict-modern setting (`legacy: "reject"`); legacy handshakes are answered with an unsupported-protocol-version rejection instead of being served | Stdio remains available for clients that only speak older protocol generations | `integrations/mcp/tests/http.test.js` |
+| MCP HTTP resource exhaustion | Slow headers, slow bodies, oversized bodies, or connection floods exhaust server resources | Bounded transport controls | Header/request/keepalive timeouts are set on the HTTP server; request bodies are hard-bounded at 4 MiB (413 on exceed); an in-flight ceiling sheds load with 503 `E_MCP_HTTP_BUSY`; only POST is served | Bounds protect availability, not authorization | `integrations/mcp/tests/http.test.js` |
+| Transport metadata as authority | An MCP session id, HTTP source address, Origin/Host header, or tool-supplied acknowledgement is treated as ForgeLoop authority | Authority-free adapter design | No session identity is issued or consumed; capability policy is fixed at launch and re-checked per invocation; acknowledgement fields satisfy canonical command semantics only after launch-level capability was granted | None within the adapter boundary; host-level network controls remain external | `integrations/mcp/tests/policy.test.js` |
+| MCP stdout corruption / shell injection | Protocol transport polluted by diagnostics, or a generic shell tool enabling arbitrary execution | Transport discipline and exact-argv policy | stdout carries only MCP protocol; logging goes to stderr; no shell/exec tools exist; external execution passes exact argv arrays through canonical provenance | Compromised dependencies remain out of scope of transport discipline | `scripts/mcp-package-smoke.mjs` |
+| Recovery tombstone deletion / claim resurrection | Deleting `recovery.json` lets a recovered task mutate after another task adopts the released scope | Recovery history and all ordinary task mutation entry points | The complete ledger derives unresolved recovery independently; a missing tombstone with unresolved history is `INCONSISTENT`, and the canonical mutation guard rejects it with `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT` | A separately privileged process can still deny service by corrupting local artifacts | `tests/task-claim-state.test.js`, `tests/task-claim-ownership-integration.test.js` |
+| Corrupt task namespace claim disappearance | An unreadable descriptor or recovery artifact is interpreted as claim-free during task creation or scope change | Modern task namespace discovery and project claim acquisition | Readable historical claims are retained conservatively; an unhealthy namespace with unknown ownership blocks claim mutation globally with `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT` | Recovery requires repairing protocol-owned evidence; ForgeLoop does not invent unknown claims | `tests/task-claim-ownership-integration.test.js`, `tests/task-recovery-tamper.test.js` |
+| Recovery event-tail eviction | Later ledger events push recovery history beyond a bounded read window and reactivate old claims | Recovery state versus append-only event history | Claim ownership validates the complete ledger and binds the artifact to its exact recovery event, recovery ID, claims, classification, authority, revision, and repository fingerprint | Full validation is intentionally correctness-first and may be optimized only with verdict-equivalent checkpoints | `tests/task-recover.test.js`, `tests/task-recovery-validation.test.js`, `tests/task-recovery-invariants.test.js` |
+| Project claims lock deadlock or theft | A crashed process blocks every ownership transition, or stale cleanup removes a replacement owner | `.forgeloop/.claims.lock` | Project claim locks classify `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`; acquisition may quarantine and remove only an unchanged stale inode after matching lock ID, heartbeat, and owner instance, while unknown/corrupt/CAS-mismatch state fails closed | Lease expiry is a recovery heuristic; separately privileged filesystem writers remain outside the boundary | `tests/project-claims-lock.test.js`, `tests/task-recovery-concurrency.test.js` |
+| Self-asserted recovery authority | An actor labels its own recovery request operator- or host-authorized | Caller input, recovery authority metadata, and host integration boundary | Standalone recovery records only `CALLER_ACKNOWLEDGED`; the deprecated operator flag is only an alias; `HOST_ATTESTED` requires a host-owned grant reference and cannot be minted by the CLI | Host attestation remains only as strong as the host-controlled boundary and grant source | `tests/task-recovery-cli.test.js`, `tests/task-recovery-validation.test.js` |
+| Recovery TOCTOU and reacquisition collision | State changes between inspection and claim release, or two tasks acquire the same released path | Project claims lock, task lock, revision, ledger sequence, and scope checks | Project-claims lock precedes task lock; recovery revalidates validated ownership, classification, revision, phase, and ledger sequence; resume validates the same ownership, CAS-settles stale task locks, and reuses normal conflict and clean-scope enforcement; concurrent tests assert at most one active owner | The filesystem cannot make repository content and multi-file metadata globally atomic against separately privileged writers | `tests/task-recovery-concurrency.test.js`, `tests/project-claims-lock.test.js`, `tests/task-lock.test.js`, `tests/task-resume.test.js` |
 | Lifecycle artifact repair | Direct state or receipt edits fabricate a legal recovery or terminal phase | Work state, receipt, evidence checks, and event ledger | New verification cycles record phase events and fingerprints; validators reject state/ledger divergence and future lifecycle evidence | Local artifacts are detection-oriented, not cryptographically tamper-proof against a privileged process rewriting every linked artifact | `tests/lifecycle-evidence-recovery.test.js`, `tests/completion-ergonomics.test.js` |
 | 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` |

package/docs/ARTIFACT_REFERENCE.md

@@ -30,6 +30,11 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `policy/baseline.json` | `policy-baseline` | Protocol Generated Or Operator | Monotonic Ratchet Down | Brownfield Baseline |
 | `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 -->
 
@@ -370,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`)*
@@ -570,6 +585,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 -->
@@ -598,6 +614,173 @@ 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 -->
+
+---
+
+### 2.19 `task-state/<taskKey>/recovery.json`
+
+<!-- forgeloop-doc: schema=task-recovery artifact=.forgeloop/task-state/<task-key>/recovery.json -->
+
+Durable current-state input for claim-release recovery. It records the
+classification and exact claims released while leaving lifecycle work state,
+receipts, failures, policy, and continuity unchanged. Structural validity alone
+does not release claims: ForgeLoop must also validate the descriptor, work
+state, full ledger, referenced recovery event, and absence of a later matching
+resume. A mismatch is `INCONSISTENT`, preserves historical claims, and suspends
+ordinary mutation until the protocol-owned evidence is repaired.
+
+`CALLER_ACKNOWLEDGED` is not host attestation. `HOST_ATTESTED` requires a
+host-owned `grantRef`; the standalone CLI does not self-issue that authority.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:task-recovery -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `status` *(string, required, const: `RECOVERED`)*
+- `recoveredAt` *(string, required)*
+- `recoveryId` *(string, required, pattern: `^recovery-[A-Za-z0-9-]+$`)*
+- `recoveryEventSeq` *(integer, required, minimum: 1)*
+- `classificationAtRecovery` *(string, required, enum: `STALE`, `ABANDONED`, `LEGACY_BOUNDARY_MIGRATED`)*
+- `reasonCodes` *(array<string>, required)*
+- `releasedClaims` *(array<string>, required)*
+- `previousPhase` *(string, required, minLength: 1)*
+- `previousRevision` *(integer, required, minimum: 0)*
+- `repositoryFingerprint` *(object, required)*
+  - `branch` *(string,null, required)*
+  - `head` *(string,null, required)*
+- `authority` *(object, required)*
+  - `kind` *(string, required, enum: `CALLER_ACKNOWLEDGED`, `HOST_ATTESTED`)*
+  - `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 -->