@cassiomc1/forgeloop 1.5.0 → 1.6.1

package/docs/DIAGNOSTIC_MODEL.md

@@ -0,0 +1,181 @@
+# ForgeLoop Diagnostic Model
+
+Canonical reference for structured diagnostic cases, interventions, and hypothesis dispositions (ForgeLoop 1.6.0+, Protocol v1 additive).
+
+## Principles
+
+1. **Observation is not hypothesis.** Observations are bounded statements grounded in recorded evidence. Hypotheses are falsifiable claims that may explain observations.
+2. **Hypothesis is not proof.** Statuses are `OPEN`, `SUPPORTED`, `WEAKENED`, `FALSIFIED`, `SUPERSEDED`, `UNRESOLVED`. ForgeLoop never emits `ROOT_CAUSE_CONFIRMED` or similar.
+3. **Append-only truth.** Diagnostic revisions are never rewritten; the ledger records evolving understanding.
+4. **Diagnostic prose is metadata.** Statements, settlement predicates, and next-safe-action text are never executed by ForgeLoop.
+
+## Structured diagnostic case
+
+One diagnostic revision for one verification cycle, recorded with:
+
+```bash
+forgeloop record-diagnosis --task <id> --file diagnostic-case.json --json
+```
+
+Legacy flag-based `record-diagnosis` syntax remains valid; both forms cannot be combined.
+
+Schema: `schemas/diagnostic-case.schema.json`. Bounded limits: 64 observations, 64 contributors, 32 hypotheses per case; statements up to 4096 characters; IDs match `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`.
+
+### Semantic fingerprint
+
+`diagnosticFingerprint` hashes the canonicalized semantic content (cycle, failure class, observations/contributors/hypotheses semantics, next-safe action). Whitespace, key ordering, unordered reference arrays, and object IDs are excluded. Re-recording a semantically identical case is idempotent.
+
+### Revisions
+
+`diagnosticRevision` starts at 1 and increases monotonically per cycle. Each revision binds `previousDiagnosticFingerprint` to the prior active revision.
+
+## Interventions
+
+Recorded in `CORRECTING` phase:
+
+```bash
+forgeloop record-intervention --task <id> --file intervention.json --json
+```
+
+Interventions bind to at least one recorded hypothesis and carry a semantic fingerprint used to detect repetition without information gain.
+
+## Hypothesis dispositions
+
+```bash
+forgeloop record-hypothesis-disposition --task <id> \
+  --hypothesis h-timeout-latency --status SUPPORTED \
+  --evidence-ref checkout-tests --reason "..." --json
+```
+
+Allowed transitions: `OPEN → {SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, UNRESOLVED}`, `SUPPORTED → {WEAKENED, FALSIFIED, SUPERSEDED}`, `WEAKENED → {SUPPORTED, FALSIFIED, SUPERSEDED}`.
+
+## Diagnostic precedence
+
+One canonical resolver backs every lifecycle gate, `next`, `progress`, and reflection:
+
+1. latest valid structured diagnostic case (`DIAGNOSTIC_CASE_RECORDED`) for the active task/cycle;
+2. latest valid legacy diagnosis (`DIAGNOSIS_RECORDED`) for the active task/cycle;
+3. none.
+
+Structured diagnosis is therefore a first-class protocol-native diagnostic source: a task using only `record-diagnosis --file` can traverse `DIAGNOSING -> CORRECTING -> VERIFYING` without any legacy event, and no duplicate legacy event is synthesized. Legacy diagnosis remains fully valid as a compatibility input.
+
+## Hypothesis state projection
+
+Hypothesis status is projected forward from append-only chronology (case creation in `OPEN`, then each disposition validated against the last effective projected state) — never re-read from the source case. Terminal states (`FALSIFIED`, `SUPERSEDED`, `UNRESOLVED`) do not transition unless a future protocol revision explicitly allows reopening. Invalid transitions fail closed with `E_HYPOTHESIS_DISPOSITION_INVALID`. `trace`, `reflect`, and continuity `openHypotheses` all consume this same projection.
+
+## Evidence binding
+
+Structured cases require at least one hypothesis; `CHECK_RESULT` observations must resolve to a real check from the active verification cycle; a `VERIFICATION_FAILURE` case must bind at least one hypothesis or observation to failed/blocked evidence from the active cycle. Revision chains are revalidated at read time (`revision N.previousDiagnosticFingerprint == revision N-1.diagnosticFingerprint`).
+
+## Effective gain definition
+
+Effective Information Gain exists when a diagnostic cycle changes a meaningful
+semantic dimension of the verified engineering state:
+
+```text
+new observation        new contributor       new hypothesis
+new evidence           hypothesis disposition hypothesis elimination
+failure signature      failure surface        intervention semantics
+strategy
+```
+
+All of these participate in `effectiveGain`. Semantic noise — new IDs,
+timestamps, property order, whitespace-equivalent paraphrases — never does.
+
+## Classification vs effective gain
+
+The compatibility classification (`FIRST_DIAGNOSIS`, `NEW_HYPOTHESIS`,
+`NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`, `NONE`) intentionally does not
+encode every v2 dimension. A cycle can therefore report:
+
+```text
+classification = NONE
+failureSurfaceChanged = true
+effectiveGain = true
+```
+
+`effectiveGain` is computed once from the final dimensions by the authoritative
+cycle analysis projection; consumers (progress, reflect, next, inspect,
+continuity) must not recompute or post-mutate it.
+
+## Stall policy (fail-fast)
+
+A structured diagnostic state is **stalled** when its latest comparable
+diagnostic state has no effective information gain. There is no two-cycle
+threshold: one no-gain comparison blocks another blind correction retry with
+`E_DIAGNOSIS_NO_NEW_INFORMATION`, and progress/reflect/next/inspect expose the
+same condition. The first diagnosis is never stalled. High correction-cycle
+count alone remains advisory (`WATCH`), never `STALLED`.
+
+Stall is not terminal: recording a diagnostic with meaningful new information
+(a new observation, contributor, evidence, hypothesis change, and so on)
+clears it immediately. Strategy oscillation (`A -> B -> A`) keeps the more
+specific `INTRODUCE_NEW_OBSERVATION` guidance over generic no-gain guidance.
+Historical repetition metrics remain available as reflective explanation
+(`stallAnalysis`) but do not change the stall decision. Semantic noise — new IDs,
+timestamps, property order, whitespace-equivalent paraphrases — never counts as
+gain or as hypothesis elimination.
+
+## Failure surface evolution
+
+Every canonically verified cycle appears in failure surfaces, including
+successful ones:
+
+```text
+cycle 2 ["lint"]
+cycle 3 []        <- explicit empty successful cycle, direction REDUCED
+```
+
+A full reduction to `[]` classifies the preceding intervention as `IMPROVED`.
+
+## Intervention repetition
+
+```text
+repeatedSemanticIntervention
+  = the same intervention semantic fingerprint was recorded before
+
+NON_INFORMATIVE
+  = later verification produced no meaningful semantic change
+```
+
+Recording an intervention returns `repeatedSemanticIntervention` plus
+`effectiveness: "PENDING"`. Only a subsequent completed verification cycle can
+classify `IMPROVED | REGRESSED | INFORMATIVE | NON_INFORMATIVE`.
+
+## Continuity diagnostic context
+
+```json
+{
+  "activeFailureSignatures": ["<sha256-like canonical fingerprint>"],
+  "activeFailedRequirements": ["auth-tests"],
+  "openHypotheses": [],
+  "latestIntervention": null,
+  "nextExperiment": null,
+  "doNotRepeat": []
+}
+```
+
+`activeFailureSignatures` contains canonical `computeFailureSignature` hashes
+scoped to the active verification cycle; requirement names are exposed
+separately in `activeFailedRequirements`.
+
+## Structured case hypothesis invariant
+
+At least one hypothesis is mandatory: `hypotheses.minItems = 1` is enforced
+identically by the JSON schema, the runtime validator, ledger validation, and
+the record-diagnosis command path.
+
+## Information gain
+
+Compatibility values (`FIRST_DIAGNOSIS`, `NEW_HYPOTHESIS`, `NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`, `NONE`) remain valid. Structured dimensions add observation/contributor/hypothesis novelty, disposition changes, failure-signature change, failure-surface change, and intervention change. New IDs, timestamps, whitespace, paraphrases, and identical reruns never constitute gain.
+
+## Stall and oscillation
+
+- High correction-cycle count alone is advisory (`WATCH`), never `STALLED`.
+- Strong stall requires identical failure signature, strategy, contributors, hypotheses, surface, and no new evidence across consecutive cycles. Two consecutive correction cycles without effective gain under the same strategy reach `STALLED` (`REQUIRE_NEW_DIAGNOSTIC_INFORMATION`).
+- Repetition of an intervention is not automatically non-informative: effectiveness (`PENDING | IMPROVED | REGRESSED | INFORMATIVE | NON_INFORMATIVE`) is classified only after subsequent verification. Continuity `doNotRepeat` requires semantic repetition AND at least two completed post-intervention verification cycles AND unchanged failure surface.
+- Oscillation (`A→B→A`) surfaces as `OSCILLATING_STRATEGY`; `next` recommends `INTRODUCE_NEW_OBSERVATION`.
+
+## Capability discovery
+
+`forgeloop protocol-info --json` advertises `features.diagnostics`, `executionHistory`, `structuredTrace`, `taskInspection`, and `reflection`.

package/docs/DOCUMENTATION_GUIDE.md

@@ -14,7 +14,7 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
 | **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`) | Tutorials, command reference, handoff workflows, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
 | **Domain Engineering** | `ENG/` (`clean-code-eng.md`, `design-code-eng.md`, `test-code-eng.md`, etc.) | Domain-specific implementation and quality standards | Frontmatter must adhere to `validate_loop_system.py` standards. |
 | **Consumer Documentation Quality** | [`ENG/documentation-quality-eng.md`](../ENG/documentation-quality-eng.md) | Quality standards for documentation work in projects using ForgeLoop | Governs client/consumer project documentation tasks via guide routing. |
-| **Visual Architecture** | `docs/forgeloop-flow.mmd` | Canonical architecture diagram source | Rendered SVG committed at `docs/assets/forgeloop-flow.svg`. |
+| **Visual Architecture** | `docs/diagrams/manifest.json` + `docs/diagrams/forgeloop-engineering-flow.workflow.json` | Governance metadata and canonical typed Archify workflow source | Animated HTML explorer, animated SVG fallback, deterministic receipt, and source-bound human review are committed under `docs/assets/diagrams/` and `docs/diagrams/reviews/`. |
 | **Documentation Index** | `DOCS_INDEX.md` | Single repository index and ownership map | Updated whenever documentation structure changes. |
 
 ---
@@ -84,7 +84,7 @@ cross-platform CI (.github/workflows/docs-quality.yml)
 | **CLI Command Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
 | **Work-State Transitions** | `WORK_PHASES` / `WORK_TRANSITIONS` (`src/core/protocol.js`) | `ORCHESTRATOR_INTEGRATION.md` | `<!-- BEGIN FORGELOOP GENERATED: work-transitions -->` |
 | **Public Error Codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `docs/TROUBLESHOOTING.md` | `<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->` |
-| **Architecture Flow** | `docs/forgeloop-flow.mmd` | `docs/assets/forgeloop-flow.svg` | Verified via embedded SHA-256 fingerprint |
+| **Architecture Flow** | `docs/diagrams/manifest.json` + `docs/diagrams/forgeloop-engineering-flow.workflow.json` | `docs/assets/diagrams/forgeloop-engineering-flow.{html,svg,receipt.json}` + `docs/diagrams/reviews/forgeloop-engineering-flow.review.json` | Verified via pinned Archify renderer, trace-animation markers, source/SVG fingerprints, artifact hashes, persistent review, and composition checks |
 
 ### Maintenance Workflow
 
@@ -122,7 +122,7 @@ conformance checks detect omissions.
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
 | **Task-layout path freshness** | `TASK_LAYOUT_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Package-shipped docs** | `package.json` (`files`) | `tests/package.test.js` |
-| **Architecture diagram** | `docs/forgeloop-flow.mmd` | `scripts/check-generated-diagram.mjs` |
+| **Architecture diagram** | `docs/diagrams/forgeloop-engineering-flow.workflow.json` | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
 
 ---
 
@@ -177,21 +177,29 @@ migration, or security-sensitive require `npm run docs:check` before merge.
 
 ---
 
-## 7. Mermaid Diagrams and SVG Generation
+## 7. Archify Diagrams and Animated SVG Generation
 
-1. **Source is Canonical**: Diagram source files live in `.mmd` files (e.g. `docs/forgeloop-flow.mmd`). Never modify SVG files directly.
-2. **Local Committed SVGs**: Generated SVGs are committed locally in `docs/assets/`. Never hotlink externally rendered diagram images.
-3. **Self-Contained & GitHub-Safe**: Generated SVGs must not import external stylesheets (e.g. `@import url(...)`), must not embed `<script>` or `<foreignObject>`, and must be visible via standard Markdown image syntax (`![alt](./path.svg)`).
-4. **Fingerprint Verification**: Generated SVGs embed a `data-forgeloop-source-sha256` attribute verified by `npm run docs:check`.
+1. **Typed source is canonical**: The architecture flow is authored in Archify workflow IR at `docs/diagrams/forgeloop-engineering-flow.workflow.json`. Never modify generated HTML or SVG files directly.
+2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
+3. **Animated committed outputs**: The source uses `meta.animation: "trace"`. The interactive HTML is the primary animated explorer, and the self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. The deterministic receipt is committed under `docs/assets/diagrams/`.
+4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
+5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The human-owned review at `docs/diagrams/reviews/` binds the current source and SVG hashes and is never generated or overwritten. Run `npm run docs:diagrams:check` before review.
+6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
+
+ForgeLoop governs five documentation-diagram categories: workflow,
+architecture, sequence, dataflow, and lifecycle. The current repository has
+one canonical workflow diagram. Governance support does not imply renderer
+support: a type requires an explicit renderer mapping before it can be added as
+an active diagram.
 
 ---
 
 ## 8. README Hero and Package Boundary
 
 README hero assets are branding/conceptual illustrations. They are not the
-canonical protocol diagram. `docs/forgeloop-flow.mmd` remains the canonical
-architecture flow source and `docs/assets/forgeloop-flow.svg` remains its
-generated render.
+canonical protocol diagram. The typed Archify workflow under `docs/diagrams/`
+remains the canonical architecture flow source, with generated outputs under
+`docs/assets/diagrams/`.
 
 The README hero is intentionally GitHub-repository-only:
 
@@ -206,8 +214,9 @@ The README hero is intentionally GitHub-repository-only:
   packaged Markdown must be present in the package and covered by
   `tests/package.test.js`.
 
-Never delete `docs/assets/forgeloop-flow.svg`; it is generator-owned output of
-the diagram workflow.
+Never edit or delete a generated diagram output independently of its source;
+regenerate `docs/assets/diagrams/` from the typed workflow and keep the receipt
+in sync.
 
 ---
 

package/docs/EXECUTION_TRACE.md

@@ -0,0 +1,76 @@
+# ForgeLoop Execution Trace
+
+Reference for `history`, `trace`, `reflect`, and task-level `inspect` observability projections (ForgeLoop 1.6.0+).
+
+All views are deterministic read-only projections of canonical artifacts (event ledger + work state). There is no second truth store.
+
+## history
+
+```bash
+forgeloop history --task <id> [--json] [--compact] [--verbose]
+                  [--type <types>] [--phase <phases>] [--failures] [--checks]
+                  [--since <ts>] [--until <ts>] [--limit <n>]
+```
+
+Human output shows chronological events with timestamps from the ledger. JSON output includes:
+
+- `snapshot`: consistency anchors (`stateRevision`, `ledgerTailSequence`)
+- `summary`: event/check/diagnostic counts
+- `historyQuality`: `COMPLETE | PARTIAL | MINIMAL` with reasons
+- `integrity`: ledger validation result
+- `events`: normalized events (category, phase, provenance, references)
+
+Filters are presentation-only; they never weaken integrity validation. Truncation via `--limit` is explicit (`truncated: true`).
+
+## trace
+
+```bash
+forgeloop trace --task <id> --json
+```
+
+Machine-readable reconstruction containing events, lifecycle transitions (including `VERIFICATION_STARTED`), check attempts, diagnostics (legacy diagnoses, structured cases, interventions, dispositions), failure signatures/surfaces, executions, evidence, continuity, recovery, completion, integrity, and snapshot anchors.
+
+Failure surfaces include every canonically verified cycle; a successful
+verification appears explicitly as `surface: []`, enabling deterministic
+`REDUCED -> empty` and intervention `IMPROVED` classification.
+
+Attempt cardinality comes primarily from ledger chronology: one ledger attempt plus its state checkpoint counts once; two distinct ledger events count twice; a state-only check appears as one fallback attempt (`source: "state-fallback"`). Phases are reconstructed forward from milestone events (`TASK_RECEIVED -> RECEIVED` ... `COMPLETION_VALIDATED -> COMPLETE`); events between milestones carry derived phases (for example failed verification -> `DIAGNOSING`, recorded intervention -> `CORRECTING`) with `phaseQuality: "authoritative" | "derived" | "unknown"`. Determinism: identical canonical artifacts produce identical traces except `snapshot.capturedAt`.
+
+## reflect
+
+```bash
+forgeloop reflect --task <id> [--json]
+```
+
+Whole-task retrospective (gain truth comes from the canonical cycle analysis;
+`stallAnalysis` explains historical repetition without changing the fail-fast
+stall decision): verification cycles, failure surfaces, hypothesis summary, intervention effectiveness (`PENDING | INFORMATIVE | NON_INFORMATIVE | IMPROVED | REGRESSED`), strategy fingerprints, oscillation patterns, signals, and a recommended protocol action. Deterministic — ForgeLoop does not call an LLM.
+
+## inspect --task
+
+`forgeloop inspect --task <id>` extends target health with an additive `taskInspection` section: snapshot, lifecycle transitions, history quality, verification attempts per requirement, diagnostic summary, progress evaluation, integrity issues, deterministic explanation reason codes, and the safe next command. Existing top-level inspect fields are unchanged.
+
+## Read-only invariant
+
+`history`, `trace`, `reflect`, `inspect`, `progress` never mutate protocol state, acquire ownership, or append events. Test suites enforce this by hashing the complete `.forgeloop` tree before/after invocation.
+
+## Durable actions in the trace
+
+`trace --json` adds an `actions` projection with totals, state and capability
+counts, required/verified/failed/ambiguous counts, repeated idempotency-key
+attempts, reconciliation count, and action-event count. The projection reads
+the task action artifacts and the same ledger already used by history; it is
+not a second source of lifecycle truth.
+
+An action recorded as `COMMIT_UNKNOWN` is an external-state uncertainty, not a
+diagnostic failure. Reflection surfaces `EXTERNAL_ACTION_RECONCILIATION_REQUIRED`
+and recommends `RECONCILE_EXTERNAL_ACTION` before ordinary retry guidance.
+`FORGELOOP_EXECUTED`, `HOST_REPORTED`, and `EXTERNAL_OBSERVED` remain distinct
+provenance values.
+
+`forgeloop metrics --task <id> --json` projects trajectory counts, action
+outcomes, observed executions, and first/last authoritative ledger timestamps.
+Usage fields remain `null` with `source: "UNKNOWN"` when the host did not
+report them. `forgeloop eval --task <id> --scenario <path> --json` evaluates a
+validated current trace against a project-local reference scenario; an
+efficiency ratio is omitted when no positive comparable-step reference exists.

package/docs/MCP.md

@@ -46,6 +46,39 @@ Capability flags (process-scoped, immutable after launch):
 - `forgeloop://task/{taskId}/ownership` — canonical validated ownership
 - `forgeloop://task/{taskId}/contract`
 - `forgeloop://task/{taskId}/continuity`
+- `forgeloop://task/{taskId}/actions`
+- `forgeloop://task/{taskId}/action/{actionId}`
+- `forgeloop://task/{taskId}/approvals`
+- `forgeloop://task/{taskId}/metrics`
+- `forgeloop://task/{taskId}/evaluations`
+- `forgeloop://project/capability-policy`
+
+The durable-action resources are read-only projections. The first release does
+not expose `run-action` or host-attestation minting over MCP. An action that is
+`COMMIT_UNKNOWN` is surfaced as an external reconciliation requirement; MCP
+transport/session metadata cannot authorize a retry or manufacture
+`HOST_ATTESTED` authority. Capability policy remains policy, not authority.
+
+### Approval resolution and reconciliation settlement capabilities
+
+Two launch flags expose transport surfaces; neither creates host authority:
+
+- `--allow-approval-resolution` exposes the `approval-resolve` tool.
+  Resolving an approval as `HOST_ATTESTED` still requires a trusted
+  out-of-band authority context supplied by the embedding host through
+  `createForgeLoopMcpServer({ authorityContextProvider })`. Without a
+  provider, `HOST_ATTESTED` resolutions fail closed with
+  `E_ACTION_AUTHORITY_REQUIRED`. Tool arguments can never carry the context:
+  any actor-supplied `authorityContext` property is stripped before dispatch.
+- `--allow-reconciliation-settlement` exposes settlement-class
+  `action-reconcile` invocations (`--outcome COMMITTED|NOT_COMMITTED`).
+  Recording an `UNKNOWN` observation needs no special capability, but settling
+  external commit state is independently gated and still requires trusted
+  host attestation plus evidence at the core layer.
+
+Capability introspection reports whether these surfaces are enabled
+(`hostAttestationAvailable: false` by default) but never exposes grant
+content.
 
 Raw recovery artifacts, transaction journals, lock files, and unbounded event
 ledgers are intentionally not exposed.
@@ -72,7 +105,7 @@ forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
 
 | Component | Current contract |
 | --- | --- |
-| ForgeLoop core package | `1.5.x` repository generation |
+| ForgeLoop core package | `>=1.5.0 <2` dependency range; current repository generation `1.6.x` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |

package/docs/RECIPES.md

@@ -21,6 +21,7 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 13. [Record Decision Settlement Criteria](#recipe-13--record-decision-settlement-criteria)
 14. [Executable Policy, Baseline Ratchet, and Recovery](#recipe-14--executable-policy-baseline-ratchet-and-recovery)
 15. [Release and Reacquire Claims for an Abandoned Task](#recipe-15--release-and-reacquire-claims-for-an-abandoned-task)
+16. [Execute a Durable External Action Safely](#recipe-16--execute-a-durable-external-action-safely)
 
 ---
 
@@ -346,6 +347,72 @@ artifact against the complete ledger history. If `next` returns
 `RESOLVE_RECOVERY_INCONSISTENCY`, run `validate-protocol`; do not create, edit,
 or delete `recovery.json` manually.
 
+---
+
+### Recipe 16 — Execute a Durable External Action Safely
+
+Record the intended external effect before execution, satisfy the capability
+policy and fingerprint-bound approval, and execute with an exact argument list:
+
+```bash
+forgeloop action-propose --task release --id action-publish --capability external.publish --effect-class EXTERNAL_PUBLICATION --target registry/release --operation "publish release" --idempotency-key release:publish:v1 --required-for-completion
+forgeloop approval-request --task release --approval approval-publish --action action-publish --reason "reviewed release"
+forgeloop approval-resolve --task release --approval approval-publish --decision APPROVED --authority CALLER_ACKNOWLEDGED
+forgeloop run-action --task release --action action-publish --capability external.publish --effect-class EXTERNAL_PUBLICATION --target registry/release --idempotency-key release:publish:v1 --required-for-completion -- npm publish
+# If the external outcome cannot be proven after start, do not retry:
+forgeloop action-reconcile --task release --action action-publish --outcome UNKNOWN
+```
+
+Provenance and authority truths for this recipe:
+
+- `CALLER_ACKNOWLEDGED` approval resolution records an acknowledgement; if the
+  capability policy requires `REQUIRE_APPROVAL`, only a fresh `HOST_ATTESTED`
+  approval resolved through a trusted embedding-host boundary authorizes the
+  action. The standalone CLI can never mint it.
+- `forgeloop next` evaluates the current capability policy before inspecting
+  approval state, but only after validating that the capability artifact is
+  bound to the active policy lock and task snapshot. Historical or stale
+  approvals never override `ALLOW`, `DENY`, or `REQUIRE_AUTHORITY`; only a
+  currently applicable `REQUIRE_APPROVAL` decision can make a pending approval
+  the active resolver target.
+- `commands` in next-action guidance are safe standalone CLI commands. A
+  host-only authorization is returned with `commands: []` and structured
+  `hostActionRequired`/`authorityRequired` data so an embedding host can invoke
+  `action-authorize` while preserving its trusted authority context.
+- `approval-request` is policy-aware: it creates a pending approval only for
+  `REQUIRE_APPROVAL`; `ALLOW`, `DENY`, and `REQUIRE_AUTHORITY` reject the request
+  without creating an approval artifact. A changed `capabilities.json` alone is
+  not a valid policy update: restore the recorded epoch or refresh the lock and
+  task snapshot through the supported policy lifecycle first.
+- `COMMIT_UNKNOWN` is an explicit reconciliation boundary, not a failed retry.
+  Recording `UNKNOWN` keeps the action ambiguous. Settling `COMMITTED` or
+  `NOT_COMMITTED` requires trusted host attestation plus evidence through a
+  trusted integration boundary. A trusted `NOT_COMMITTED` returns the action
+  to `PROPOSED` so authorization is re-evaluated before any retry.
+
+After commit ambiguity is settled as `COMMITTED`, verify the independent
+postcondition before completion:
+
+```bash
+forgeloop run-check --task release --id check-release-live --requirement publication -- npm view your-package-name@1.0.0 version
+forgeloop action-verify --task release --action action-publish --evidence <execution-ref>
+```
+
+`COMMITTED != VERIFIED`: exit code 0 from the action command proves local
+completion only. Verification requires canonical evidence from an independent
+check execution.
+
+Inspect the observed trajectory without inventing usage data:
+
+```bash
+forgeloop metrics --task release --json
+forgeloop eval --task release --scenario scenarios/release.json --json
+```
+
+The efficiency comparison is present only when the scenario declares a
+positive `reference.comparableSteps`; absent host token/cost/model data stays
+unknown.
+
 ## Run ForgeLoop through MCP (safe mode)
 
 Start the local MCP adapter and inspect what it exposes:

package/docs/RELEASE_CHECKLIST_1_6_1.md

@@ -0,0 +1,121 @@
+# ForgeLoop 1.6.1 release checklist
+
+Preparation checklist for the `@cassiomc1/forgeloop` 1.6.1 release. It does not
+authorize publication. Historical checklists:
+[`RELEASE_CHECKLIST_1_5_MCP.md`](./RELEASE_CHECKLIST_1_5_MCP.md),
+[`RELEASE_CHECKLIST_1_4.md`](./RELEASE_CHECKLIST_1_4.md).
+
+## Version and contract identity
+
+- [ ] Core package version is `1.6.1` in `package.json` and the lockfile root.
+- [ ] ForgeLoop protocol version is `1`.
+- [ ] Integration API version is `1`
+      (`FORGELOOP_INTEGRATION_API_VERSION`).
+- [ ] Candidate version is absent from npm and the `v1.6.1` tag is absent from
+      origin before release preparation starts.
+- [ ] `CHANGELOG.md` has a versioned `1.6.1` section with the actual release
+      date and an empty `Unreleased` section above it.
+
+## Verification execution adapter contract (new in 1.6.x line)
+
+- [ ] `src/core/verification-execution.js` defines the adapter boundary,
+      `VERIFICATION_ISOLATION_MODES`, and the two public error codes.
+- [ ] `runtimeContext.verificationExecutionAdapter` and
+      `runtimeContext.verificationExecutionPolicy` are validated at context
+      creation and never accepted as CLI flags or command input.
+- [ ] `createForgeLoopContext`, the isolation modes, and both error codes are
+      exported from `@cassiomc1/forgeloop/integration`.
+- [ ] `protocol-info --json` advertises
+      `features.verificationExecutionIsolation` (version 1, adapter-backed,
+      modes enumerated, `protocolProjectRootSeparateFromExecutionCwd: true`).
+
+## Isolation metadata invariants
+
+- [ ] `NATIVE_PROJECT` requires `isolated: false` and
+      `liveProjectWritable: true`; it is never described as isolated.
+- [ ] `PROJECT_ISOLATED` and `SYSTEM_ISOLATED` require `isolated: true` and
+      `liveProjectWritable: false`; `SYSTEM_ISOLATED` additionally requires
+      `networkPolicy: DENIED`.
+- [ ] Contradictory isolation metadata is rejected with
+      `E_VERIFICATION_EXECUTION_INVALID` before evidence persistence.
+- [ ] Isolated execution must use a cwd separate from the protocol project
+      root; violation fails closed with `E_VERIFICATION_EXECUTION_INVALID`.
+- [ ] Unsatisfiable isolation policy fails closed with
+      `E_VERIFICATION_ISOLATION_UNAVAILABLE` and never falls back to the live
+      project.
+- [ ] Execution records persist `executionKind`, `protocolProjectRoot`,
+      `executionIsolation`, and the `isolation` object per
+      `schemas/execution.schema.json`.
+
+## Durable-action invariants
+
+- [ ] Trusted `COMMITTED` reconciliation replays exactly once; reconciled
+      mirrors are corroborations, never second transitions.
+- [ ] Action verification requires an independent passed execution covering the
+      action's exact immutable requirement.
+- [ ] `REQUIRE_APPROVAL` authorizations bind approval fingerprints validated by
+      readiness and audit.
+- [ ] Public provenance metadata matches behavior
+      (`CALLER_REPORTED` / `EXTERNAL_OBSERVED`).
+
+## PoC evidence validation
+
+- [ ] `npm run poc:evidence:verify` passes against committed evidence bundles.
+- [ ] `npm run poc:evidence:test` passes.
+- [ ] PoC docs (`poc/README.md`,
+      `poc/FORGELOOP_REAL_EXECUTION_POC.md`) match committed evidence paths,
+      manifests, and hashes.
+
+## Documentation freshness
+
+- [ ] `npm run docs:generate` leaves no diff (generated regions current).
+- [ ] `npm run docs:generated:check` passes.
+- [ ] `npm run docs:conformance` passes.
+- [ ] `npm run docs:diagrams:check` passes (typed Archify source unchanged or
+      regenerated with receipt).
+- [ ] `npm run docs:check` passes.
+- [ ] Normative docs represent the post-`v1.6.0` verification execution
+      boundary without making a harness-specific backend normative.
+- [ ] `DOCS_INDEX.md` points release maintainers to this checklist as current.
+
+## Local validation gates
+
+- [ ] `npm run dependency:policy` passes (runtime dependencies remain zero).
+- [ ] `npm run lint` passes.
+- [ ] `npm test` passes.
+- [ ] `npm run coverage` passes.
+- [ ] `npm run pack:check` passes.
+- [ ] Python validators pass: `python3 -m unittest discover -s tests`,
+      `validate_markdown.py` (+ self-test), `validate_loop_system.py`
+      (+ self-test).
+- [ ] `python3 scripts/scan_secrets.py` passes.
+- [ ] `npm pack` tarball inspected: correct name/version, intended docs, no
+      secrets, no `.git`, no `.forgeloop` execution state.
+
+## Protected-branch and PR gates
+
+- [ ] Changes reach `main` only through a reviewed PR; `main-protection`
+      ruleset never bypassed.
+- [ ] Required checks green: `audit`, `CodeQL`, `Verify generated Archify
+      diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`,
+      `dependency-review`; every other relevant check green.
+- [ ] No unresolved review threads; PR merged without admin bypass.
+
+## Publication boundary
+
+- [ ] Post-merge `main` workflows green before tagging.
+- [ ] npm candidate version and tag re-checked for collision immediately before
+      tagging.
+- [ ] Annotated tag `v1.6.1` created on the exact validated `main` commit and
+      pushed once; never moved after publication.
+- [ ] `npm-publish.yml` retains `contents: read` + `id-token: write`; no
+      `NPM_TOKEN`/`NODE_AUTH_TOKEN` is added anywhere.
+- [ ] `Publish npm package` workflow succeeds (trusted OIDC publishing).
+- [ ] `Release notes` workflow succeeds; GitHub Release is not draft or
+      prerelease and carries the checksum asset.
+- [ ] npm registry reports the exact version with `gitHead` equal to the
+      release commit.
+- [ ] `npm run release:identity` returns `RELEASE_IDENTITY_VALID` with every
+      individual check `ok`.
+- [ ] Optional clean-install smoke test installs `@cassiomc1/forgeloop@1.6.1`
+      and `forgeloop --version` reports `1.6.1`.