@cassiomc1/forgeloop 1.5.0 → 1.6.0

package/DOCS_INDEX.md

@@ -18,8 +18,11 @@ integration and guide context. Use this map before editing documentation.
 | Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
+| Durable actions and trajectory evidence | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) and [`docs/RECIPES.md`](./docs/RECIPES.md) | Action provenance, reconciliation, metrics, and project-local evaluation |
 | Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
 | Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
+| Diagnostic model | [`docs/DIAGNOSTIC_MODEL.md`](./docs/DIAGNOSTIC_MODEL.md) | Structured diagnostic cases, interventions, hypothesis dispositions, information gain |
+| Execution trace and observability | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) | `history`, `trace`, `reflect`, and task-level `inspect` read-only projections |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
 | Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
@@ -34,7 +37,8 @@ integration and guide context. Use this map before editing documentation.
 | Artifact and phase schemas | [`schemas/`](./schemas/) and [`CONTRACT_COVERAGE.md`](./CONTRACT_COVERAGE.md) | Versioned machine-readable contract |
 | CLI/package behavior | [`src/`](./src/) and [`tests/`](./tests/) | Executable implementation and regression evidence |
 | Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides |
-| Diagram | [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd) | Canonical Mermaid source; SVG is generated output |
+| Diagram governance | [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json) | Authoritative taxonomy, renderer mapping, canonical purposes, artifact ownership, and references |
+| Diagram maintainer entrypoint | [`docs/diagrams/README.md`](./docs/diagrams/README.md) | Typed Archify source, animated HTML explorer, animated SVG fallback, review, and regeneration workflow |
 
 ## Audience map
 
@@ -88,25 +92,26 @@ process into adapters or README sections; link to the canonical source.
 ## Verification and release
 
 The Node regression suite, ESLint, c8, dependency policy, package boundary,
-and Mermaid render are the local executable checks. Python validators remain
+and Archify diagram render are the local executable checks. Python validators remain
 frozen CI-only compatibility tools because they cover historical Markdown,
 loop, and secret-scanning contracts that have not been migrated to Node. Their
 scope, exact commands, and migration boundary are recorded in
 [`scripts/CI_VALIDATORS.md`](./scripts/CI_VALIDATORS.md).
 
 The package has no runtime dependencies. Development dependencies are limited
-to ESLint, c8, and Mermaid CLI and are checked by
+to ESLint and c8 and are checked by
 `npm run dependency:policy`. GitHub Actions use `npm ci`, pinned action SHAs,
 CodeQL, dependency review, and generated-release notes; npm publication still
 uses trusted OIDC publishing and is not implied by local verification.
 
 ## Editing rules
 
-- Keep lifecycle prose, the Mermaid source, and the text-only README fallback
-  synchronized.
-- Keep generated `docs/assets/forgeloop-flow.svg` synchronized with the Mermaid
-  source by running `npm run docs:flow` and `npm run docs:check`. CI validates
-  the source fingerprint instead of comparing renderer-specific SVG geometry.
+- Keep lifecycle prose, the typed Archify source, generated outputs, and the
+  text-only README fallback synchronized.
+- Keep the generated HTML, SVG, and receipt synchronized with the Archify
+  source by running `npm run docs:diagrams` and `npm run docs:check`. CI
+  validates the renderer pin, source fingerprint, artifact hashes, and SVG
+  safety constraints.
 - Preserve the distinction between implemented behavior, local evidence, and
   external publication or production state.
 - Run `npm run lint`, `npm run coverage`, `npm run pack:check`, and the Python

package/EXECUTION_STATE.md

@@ -179,3 +179,23 @@ repository context and is always operational context rather than evidence.
 | Stale | Any | Changed | Run `forgeloop route` and `forgeloop preflight` to revalidate |
 | Invalid / Corrupted | Any | Any | Fail closed; inspect errors via `forgeloop doctor --json` |
 | Different Task ID | Present | Any | Do not merge contexts; clear or finish previous task first |
+
+## Durable actions are a separate external-state checkpoint
+
+Action artifacts under `actions/` describe side-effect intent and its canonical
+state; they do not replace `work-state.json`. Approval artifacts bind a single
+decision to the exact action fingerprint, contract fingerprint, task revision,
+and capability. Capability policy is configuration, not host authority.
+
+`FORGELOOP_EXECUTED` means ForgeLoop launched exact argv through `run-action`;
+`HOST_REPORTED` means an external host performed the operation; and
+`EXTERNAL_OBSERVED` means a later observation supplied reconciliation evidence.
+If the external outcome is uncertain, the action is `COMMIT_UNKNOWN`. It must
+not be retried or used to satisfy required completion until
+`forgeloop action-reconcile` records `COMMITTED`, `NOT_COMMITTED`, or
+`UNKNOWN`. ForgeLoop does not claim universal exactly-once execution.
+
+`metrics` and `eval` read the canonical trace, reflection, action artifacts, and
+ledger events. They never mutate lifecycle truth, invent usage/cost data, or
+create a second execution history; reference efficiency is emitted only when a
+project-local scenario provides comparable steps.

package/LOOP_ENGINEERING.md

@@ -27,6 +27,7 @@
 - [Precedence & Stop Conditions](#precedence)
 - [Final Delivery](#final-delivery)
 - [Cross-Harness Continuity](#cross-harness-execution-continuity)
+- [Durable Actions and Trajectory Evidence](#durable-actions-and-trajectory-evidence)
 - [Multi-Task Concurrent Project State](#multi-task-concurrent-project-state)
 
 ## Protocol applicability
@@ -1278,6 +1279,86 @@ completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
 installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
+## Durable Actions and Trajectory Evidence
+
+Durable actions extend the existing task protocol; they do not turn ForgeLoop
+into an agent runtime, scheduler, queue, or workflow engine. Action intent,
+approval, execution provenance, reconciliation, and evaluation are task-local
+artifacts whose chronology remains in the same hash-chained `events.ndjson`.
+
+Every side-effecting action declares an explicit capability, effect class,
+bounded target, immutable idempotency key, and provenance. Project capability
+policy is a decision input (`ALLOW`, `DENY`, `REQUIRE_AUTHORITY`, or
+`REQUIRE_APPROVAL`); it is never host authority. `HOST_ATTESTED` authority can
+only cross the existing host trust boundary, and `run-action` accepts exact
+argv with no shell mode.
+
+### Durable action trust boundaries (hardened)
+
+The following invariants are enforced in core code and are regression-tested:
+
+- **Authorization is canonical.** No caller-controlled surface (`action-record`,
+  CLI flags, MCP tool arguments, project files, environment) can mint
+  `AUTHORIZED`. Only the core authorization service may transition
+  `PROPOSED -> AUTHORIZED` — through `run-action`, or explicitly through
+  `forgeloop action-authorize`, which is a pure adapter over the same service —
+  and only after the current capability policy, the persisted policy lock, and
+  the task policy snapshot agree. Every modern
+  `ACTION_AUTHORIZED` event binds the capability decision, capability-policy
+  fingerprint, policy-lock digest, task-policy digest, and — for
+  `REQUIRE_AUTHORITY`/`REQUIRE_APPROVAL` — the exact host authority or
+  fingerprint-bound approval. Post-authorization mutation of a bound approval
+  artifact is readiness/audit-visible.
+- **Verification is canonical, independent, and requirement-bound.**
+  `COMMITTED != VERIFIED`. A command exiting 0 proves only local completion.
+  `VERIFIED` is produced exclusively by `forgeloop action-verify` (or the
+  equivalent core service) against a passed ForgeLoop execution artifact that
+  is independent of the action's own commit execution and whose immutable
+  `requirement` exactly equals the action's requirement. New required actions
+  must declare a non-empty requirement at proposal time; historical required
+  artifacts without one remain readable but can never become trusted-satisfied.
+- **Reconciliation has exactly one replay truth.** A trusted `COMMITTED`
+  settlement emits `ACTION_RECONCILED(outcome=COMMITTED)` (the transition) plus
+  a same-revision informational mirror `ACTION_COMMIT_RECORDED(reconciled=true)`
+  (corroboration only). Ledger replay applies the transition exactly once and
+  validates mirror identity; forged or orphaned mirrors invalidate the ledger.
+- **Completion consumes readiness.** Required-action completion truth comes
+  from the canonical action-readiness projection, never from raw state labels.
+  A forged or legacy `VERIFIED` label without trusted authorization and
+  canonical verification evidence yields `UNTRUSTED` and blocks completion.
+- **Settling ambiguity requires trust.** Recording an `UNKNOWN`
+  reconciliation observation is always safe. Settling `COMMIT_UNKNOWN` as
+  `COMMITTED` or `NOT_COMMITTED` requires a trusted out-of-band host authority
+  context plus bounded evidence references bound to the event. Trusted
+  `NOT_COMMITTED` returns the action to `PROPOSED`, so any retry re-evaluates
+  policy, approval, authority, and the task policy snapshot; stale
+  authorization can never be reused.
+- **STARTED marks the launch boundary.** Deterministic pre-launch checks
+  (argv normalization, command resolution, installation authority, policy
+  identity, approvals) all run before `ACTION_STARTED`; post-start outcomes
+  remain conservative: spawn failure without launch is `FAILED`; anything
+  unproven is `COMMIT_UNKNOWN`.
+- **Capability policy participates in policy identity.** When
+  `.forgeloop/policy/capabilities.json` exists, its digest participates in the
+  policy lock, the active task policy snapshot, and authorization evidence.
+  Drift blocks before any side effect (`E_ACTION_POLICY_DRIFT`).
+- **Host context is out-of-band.** Trusted authority travels as an execution
+  context object supplied by an embedding host (`executeForgeLoopCommand` /
+  `createForgeLoopMcpServer({ authorityContextProvider })`). CLI flags such as
+  `--authority HOST_ATTESTED` are requested kinds, never proof. MCP launch
+  flags expose transport surfaces only; tool arguments can never carry
+  `authorityContext`.
+- **Guidance never lies about authority.** `forgeloop next` returns a
+  structured `authorityRequired` requirement for host-bound approvals instead
+  of recommending a command that cannot satisfy the blocker.
+
+Trajectory metrics and reference evaluations are read-only projections over the
+canonical trace, reflection, actions, and events. Missing tokens, costs,
+provider, model, or optimal-path data remain `null`/`UNKNOWN`; a comparative
+efficiency ratio exists only when a project-local reference scenario supplies
+`reference.comparableSteps`. Existing information-gain, intervention, failure
+signature, and oscillation diagnostics remain canonical.
+
 ## Multi-task concurrent project state
 
 ForgeLoop supports isolated, concurrent tasks within the same repository workspace.

package/LOOP_SYSTEM_DESIGN.md

@@ -442,3 +442,35 @@ machine and not a general memory subsystem. Work state owns lifecycle truth;
 the checkout owns implementation truth; checks/executions own verification
 truth; completion owns certification. Continuity only narrows what a receiving
 executor should inspect and continue.
+
+## Durable action and trajectory boundary
+
+Durable actions are protocol-owned task artifacts (`actions/`, `approvals/`,
+and `evaluations/`) projected through the existing hash-chained event ledger.
+They record intent, capability policy, approval binding, execution provenance,
+commit uncertainty, reconciliation, and verification without introducing a
+workflow runtime, scheduler, queue, or second ledger.
+
+The external side-effect boundary is deliberately conservative: exact argv is
+launched only through `run-action` with no shell mode; project capability
+policy cannot manufacture `HOST_ATTESTED` authority, and trusted host context
+travels out-of-band only (never inside command input, CLI flags, or tool
+arguments). Authorization and verification are canonical core services:
+callers cannot mint `AUTHORIZED` or `VERIFIED`, verification requires an
+independent passed ForgeLoop execution artifact, and required completion
+consumes the canonical action-readiness projection rather than raw state
+labels. Capability policy participates in policy identity: its digest is bound
+into the policy lock, the task policy snapshot, and authorization evidence, so
+drift blocks before any side effect. A started action whose external result is
+uncertain becomes `COMMIT_UNKNOWN`, which forbids retry until explicit
+reconciliation; settling ambiguity as `COMMITTED`/`NOT_COMMITTED` requires
+trusted host attestation plus evidence, and a trusted `NOT_COMMITTED` returns
+the action to `PROPOSED` so stale authorization can never be reused. This
+reduces duplicate-effect risk but cannot provide a universal exactly-once
+guarantee for arbitrary external systems.
+
+Metrics and trajectory evaluation are deterministic read-only projections of
+canonical trace/reflection evidence. They preserve unknown usage values and
+only compare efficiency when a project-local reference scenario exists. The
+existing diagnostic and reflection model remains the authority for information
+gain, intervention effectiveness, failure signatures, and oscillation.

package/PROTOCOL_INTEGRATION.md

@@ -277,6 +277,31 @@ configuration
 trust
 ```
 
+For durable actions, trusted host authority travels **out-of-band** through the
+programmatic integration API:
+
+```js
+await executeForgeLoopCommand({
+  command: "approval-resolve",
+  projectPath,
+  input: { /* actor-controlled command input only */ },
+  authorityContext: trustedHostContext, // host-supplied, never from input
+});
+```
+
+`authorityContext` and `runtimeContext` are separate executor parameters; they
+are never merged into `input`, never accepted as tool arguments, and cannot be
+minted by CLI flags, project files, environment variables, or transport
+sessions. MCP embeddings supply an immutable provider instead:
+
+```js
+createForgeLoopMcpServer({
+  projectPath,
+  allowApprovalResolution: true,      // transport surface only
+  authorityContextProvider: async ({ command }) => trustedContextOrNull,
+});
+```
+
 The host-attested source must still resolve outside the actor-writable target. A
 project-local authority reference may identify a grant, but it does not create
 the root of trust.
@@ -396,3 +421,24 @@ hosts remain fully supported through the CLI and instruction adapters.
 requires ForgeLoop 1.4.0 or newer.
 <a id="FL-CLAIM-003"></a> **FL-CLAIM-003 — A reader without `validatedClaimProjection=true` MUST fail closed**
 and must not mutate claims.
+
+## Durable actions and authority boundary
+
+Durable action support is additive to the integration contract. Read-only
+resources may expose action, approval, metrics, evaluation, and capability
+policy projections, but an integration must not treat transport metadata,
+session IDs, project policy, or actor prose as host authority. `HOST_ATTESTED`
+is accepted only from the existing host trust boundary.
+
+`run-action` is an exact-argv surface with no shell mode. Hosts that perform an
+operation themselves must record it as `HOST_REPORTED`; external observations
+used to settle uncertainty are `EXTERNAL_OBSERVED`. A started action whose
+external outcome cannot be proven is `COMMIT_UNKNOWN`: integrations must surface
+`E_ACTION_RECONCILIATION_REQUIRED` and must not retry automatically. The only
+forward path is explicit `action-reconcile` with bounded evidence.
+
+Trajectory metrics and evaluations are read-only projections over canonical
+events and trace/reflection data. Missing token/cost/model data remains unknown,
+and efficiency is comparable only when a project-local scenario supplies a
+positive reference step count. ForgeLoop remains an evidence protocol, not an
+agent runtime or workflow engine.

package/QUALITY_SCORECARD.md

@@ -31,6 +31,8 @@ policy are all present.
 | Contextual frontend taste | Taste is routed only to applicable premium frontend work, remains advisory, respects accessibility/performance/evidence, and has attribution without runtime dependency. |
 | Multi-agent coordination | Self-contained briefs, write/write and write/read ownership checks, dependency-set validation, reviewer independence, normalized results, and inline fallback. |
 | Security boundaries | Realpath containment, bounded untrusted JSON, threat model, nested secret scanning, publication evidence, and explicit authority rules. |
+| Durable external actions | Immutable action identity, idempotency conflict rejection, capability policy, fingerprint-bound approvals, exact-argv provenance, `COMMIT_UNKNOWN` reconciliation, completion blocking, and audit evidence. |
+| Trajectory evaluation | Read-only trace/reflection metrics, unknown usage preservation, canonical comparable-step definition, and scenario-bound efficiency without an arbitrary overall score. |
 | Maintenance quality | Small modules, built-in runtime, deterministic JSON contracts, malformed/version fixtures, package gates, and backward-compatible protocol versions. |
 
 ## Score rules

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:
 
@@ -260,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
@@ -305,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).
@@ -377,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
 ```
 
@@ -387,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

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).

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` |

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`)*
@@ -571,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 -->
@@ -599,6 +614,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 +661,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 -->