@cassiomc1/forgeloop 1.3.0 → 1.6.0

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. |
 
 ---
@@ -31,10 +31,24 @@ Reason-code truth       -> exported protocol constants (src/core/error-codes.js,
 Guide registry truth    -> canonical guide registry (src/config/guides.json)
 Package contents truth  -> package.json + package tests (tests/package.test.js)
 Documentation routing   -> DOCS_INDEX.md
+Integration API truth   -> src/integration.js (exports, envelope, limits, risk classes, resources)
+MCP behavior truth      -> integrations/mcp/src/* and integrations/mcp/package.json
+MCP package boundary    -> MCP package tests + scripts/mcp-package-smoke.mjs
 ```
 
 Operational documentation must explain canonical behavior, not redefine it.
 
+Documentation-impact questions for integration/MCP changes:
+
+- Did a server mode or capability gate change?
+- Did an MCP transport change?
+- Did an adapter error code change?
+- Did an integration limit or resource list change?
+
+Anti-drift invariant: every `documentation-manifest.json` entry marked
+`packaged: true` is mechanically checked against the core npm tarball
+contents (`tests/package.test.js`).
+
 Canonical phase and transition inventories must be derived from `WORK_PHASES`
 and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
 enums when a generated or mechanically validated representation is available.
@@ -70,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
 
@@ -108,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` |
 
 ---
 
@@ -163,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. **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/`.
 
-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`.
+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:
 
@@ -192,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/GETTING_STARTED.md

@@ -382,6 +382,7 @@ forgeloop task-migrate --json
 ## 8. Next Steps
 
 - Continue a task across different AI harnesses: [`docs/CROSS_HARNESS_CONTINUITY.md`](./CROSS_HARNESS_CONTINUITY.md)
+- Optional: use ForgeLoop through MCP or the Integration API — [`docs/MCP.md`](./MCP.md) and [`docs/UNIVERSAL_INTEGRATION.md`](./UNIVERSAL_INTEGRATION.md). MCP is not required; CLI and MCP share the same canonical project/task state.
 - Complete command reference: [`docs/CLI_REFERENCE.md`](./CLI_REFERENCE.md)
 - Artifact and schema reference: [`docs/ARTIFACT_REFERENCE.md`](./ARTIFACT_REFERENCE.md)
 - Common symptoms and recovery: [`docs/TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)

package/docs/MCP.md

@@ -0,0 +1,159 @@
+# ForgeLoop MCP
+
+The `@cassiomc1/forgeloop-mcp` package is a **local-first MCP adapter** over
+the canonical ForgeLoop integration API (`@cassiomc1/forgeloop/integration`).
+It is an **adapter, never a second implementation**: every tool call executes
+a canonical ForgeLoop command and every ownership value comes from the
+canonical claim resolver.
+
+Two transports ship in one package:
+
+- `forgeloop-mcp` — **stdio**, the default/recommended transport;
+- `forgeloop-mcp-http` — **optional** strict-modern MCP 2026 HTTP,
+  loopback-only (remote access is unsupported).
+
+## Core principles
+
+- **No duplicated protocol logic.** The server contains no lifecycle,
+  ownership, recovery, lock, or transaction code.
+- **No direct protocol-state access.** The adapter never reads or writes
+  `.forgeloop` files; all mutation flows through ForgeLoop's own guards
+  (locks, transactions, revision checks, ledger append serialization).
+- **`COMPLETE` is not enough.** Claim release is presented exactly as the
+  canonical resolver reports it; forged COMPLETE stays INCONSISTENT with
+  historical claims retained.
+- **Recovery acknowledgement is not authorization.** `acknowledgeRecovery`
+  in tool input only satisfies ForgeLoop's caller acknowledgement after the
+  server was started with recovery capability.
+
+## Modes
+
+| Mode | Read | Loop mutations | task-resume | External | Maintenance | Recovery | Legacy repair | Force |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| `readonly` | yes | no | no | no | no | no | no | no |
+| `safe` (default) | yes | yes | yes | no | no | no | no | no |
+| `full` | yes | yes | yes | opt-in | opt-in | opt-in | opt-in | opt-in |
+
+Capability flags (process-scoped, immutable after launch):
+`--allow-external-execution`, `--allow-maintenance`, `--allow-recovery`,
+`--allow-legacy-repair`, `--allow-force-recovery`.
+
+## Resources
+
+- `forgeloop://protocol/info`
+- `forgeloop://project/tasks`
+- `forgeloop://task/{taskId}/status`
+- `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.
+
+## Optional stateless HTTP transport
+
+`forgeloop-mcp-http` serves the same deterministic catalog over the **strict
+modern** stateless MCP 2026 model (legacy-era traffic rejected):
+
+```bash
+forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
+```
+
+- **Loopback only**: non-loopback binds fail closed with
+  `E_MCP_REMOTE_NOT_SUPPORTED`. Authenticated remote access is not designed
+  yet; Host validation is DNS-rebinding defense, not authentication.
+- Strict modern: legacy-era handshakes are rejected, never silently served.
+- Stateless: no session identity is issued, so transport metadata is never
+  ForgeLoop authority.
+- Resource bounds: 4 MiB body cap, POST-only, header/request/keepalive
+  timeouts, in-flight ceiling (503 `E_MCP_HTTP_BUSY`).
+
+## Version matrix
+
+| Component | Current contract |
+| --- | --- |
+| ForgeLoop core package | `1.5.x` repository generation |
+| ForgeLoop protocol | `1` |
+| Integration API | `1` |
+| MCP package | `0.1.x` initial package |
+| MCP protocol target | `2026-07-28` |
+
+Repository implementation is separate from npm publication; nothing here
+claims a published release.
+
+## Risk classes and gating examples
+
+Invocations are classified at the adapter boundary:
+
+```text
+READ_ONLY · LOOP_MUTATION · CLAIM_REACQUISITION · EXTERNAL_EXECUTION
+MAINTENANCE · CLAIM_RELEASE_RECOVERY · LEGACY_MIGRATION · FORCE_DESTRUCTIVE
+```
+
+Examples: `bundle` → MAINTENANCE (hidden in readonly/safe);
+`task-resume` → CLAIM_REACQUISITION (available in safe — canonical claim
+reacquisition); `task-recover` → CLAIM_RELEASE_RECOVERY (full +
+`--allow-recovery`, plus the canonical acknowledgement); legacy repair →
+separately gated/hidden; force unlock → separately gated. Tool input can
+never elevate launch policy.
+
+## Bounds and timeouts
+
+- Structured MCP input is byte-bounded (`E_MCP_INPUT_TOO_LARGE`).
+- External execution cannot exceed the server launch timeout maximum:
+  omitted/null timeout receives the maximum; `0`, negative, non-integer, or
+  above-maximum values are refused.
+- Tool, capabilities and resource output is bounded using the exact UTF-8
+  serialization actually transmitted. Oversized output fails closed with
+  `E_MCP_RESULT_TOO_LARGE` and is never silently truncated.
+
+## Adapter errors
+
+Adapter-level errors are separate from the generated ForgeLoop core error
+list in [TROUBLESHOOTING](./TROUBLESHOOTING.md):
+
+| Code | Meaning |
+| --- | --- |
+| `E_MCP_INPUT_TOO_LARGE` | structured tool input exceeds the byte bound |
+| `E_MCP_RESULT_TOO_LARGE` | serialized output exceeds the output bound |
+| `E_MCP_HTTP_BUSY` | in-flight HTTP ceiling reached (503, Retry-After) |
+| `E_MCP_REMOTE_NOT_SUPPORTED` | non-loopback bind attempted |
+| `E_MCP_EXECUTION_TIMEOUT_INVALID` | timeout not a positive integer |
+| `E_MCP_EXECUTION_TIMEOUT_EXCEEDS_LIMIT` | timeout above server maximum |
+| `E_MCP_FORGELOOP_INTEGRATION_UNSUPPORTED` | installed core integration API mismatch |
+
+Canonical ForgeLoop errors (e.g. `E_TASK_SCOPE_CONFLICT`,
+`E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`) are always preserved verbatim.

package/docs/RECIPES.md

@@ -20,6 +20,8 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 12. [Migrate Legacy 1.0 Single-Task Layout](#recipe-12--migrate-legacy-10-single-task-layout)
 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)
 
 ---
 
@@ -311,3 +313,150 @@ forgeloop next --task task-001 --json
 # Intentional operator-authorized baseline reset (not normal recovery)
 forgeloop baseline --record --policy-reset-authorized --json
 ```
+
+---
+
+### Recipe 15 — Release and Reacquire Claims for an Abandoned Task
+
+```bash
+# 1. Inspect deterministic classification and structured next action
+forgeloop next --task task-001 --json
+
+# 2. RECOVERABLE must use reconcile-closure; do not use task-recover
+forgeloop reconcile-closure --task task-001 --id <verification-id> \
+  --requirement "<exact verification text>" -- <verification-command>
+
+# 3. Only STALE or ABANDONED may release effective claims
+forgeloop task-recover --task task-001 --acknowledge-recovery --json
+
+# 4. Other tasks may now adopt the released paths
+forgeloop task-create --task replacement-task --claim src --json
+
+# 5. Reacquisition fails while replacement-task owns src
+forgeloop task-resume --task task-001 --json
+
+# 6. After the conflicting owner completes, reacquire claims explicitly
+forgeloop task-resume --task task-001 --claim src --json
+```
+
+`--acknowledge-recovery` records caller acknowledgement only. It does not grant
+host authority or mark the task complete. Recovery preserves work state,
+receipts, failures, policy snapshots, and continuity until normal lifecycle
+work resumes. Claims are released only after ForgeLoop validates the recovery
+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 -- node scripts/check-release-live.js
+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:
+
+```bash
+forgeloop-mcp --project . --mode safe
+```
+
+`safe` mode permits reads, normal loop mutations, and canonical `task-resume`.
+Call the `forgeloop_capabilities` tool first: it reports versions, features,
+launch policy, and the resource list. Task ownership is available from the
+`forgeloop://task/{taskId}/ownership` resource — always the canonical claim
+resolver projection.
+
+## Resume a recovered task through MCP
+
+Recovered tasks stay mutation-disabled until claims are reacquired:
+
+```json
+{ "tool": "forgeloop_task_resume", "arguments": { "taskId": "my-task" } }
+```
+
+Conflicting claims fail with `E_TASK_SCOPE_CONFLICT` and keep recovery intact.
+Ordinary mutations against a recovered task are refused by core regardless of
+transport.
+
+## Deliberately opt into external execution
+
+`run-check`/`reconcile-closure` require a full-mode launch flag; tool input
+cannot grant it:
+
+```bash
+forgeloop-mcp --mode full --allow-external-execution
+```
+
+Execution uses exact argv arrays only — there is no generic shell tool — and
+the server `--max-execution-time-ms` ceiling always applies. Output is bounded
+on the exact UTF-8 serialization transmitted (`E_MCP_RESULT_TOO_LARGE`);
+oversized structured input fails with `E_MCP_INPUT_TOO_LARGE`.
+
+## Diagnose loopback-only HTTP errors
+
+`forgeloop-mcp-http` binds loopback only. A non-loopback bind fails closed
+with `E_MCP_REMOTE_NOT_SUPPORTED`; remote/authenticated HTTP is unsupported.
+Host/Origin validation is DNS-rebinding defense, not authentication. Under
+load, requests beyond the in-flight ceiling receive 503 `E_MCP_HTTP_BUSY`
+with `Retry-After`.

package/docs/RELEASE_CHECKLIST_1_4.md

@@ -0,0 +1,38 @@
+# ForgeLoop 1.4.0 release checklist
+
+This checklist prepares the validated claim-recovery capability for release. It does not authorize publication, tagging, or deployment.
+
+## Ownership and recovery gates
+
+- [ ] Fake, deleted, corrupt, schema-invalid, and mismatched `recovery.json` cases resolve to `INCONSISTENT`.
+- [ ] `INCONSISTENT` preserves historical claims, disables mutation, blocks overlapping acquisition, and is visible in list/show/status/audit/inspect/next.
+- [ ] Only a fully matched recovery artifact and append-only recovery history releases claims.
+- [ ] `task-recover` remains restricted to `STALE` and `ABANDONED`; `RECOVERABLE` keeps its canonical reconciliation path.
+- [ ] `task-resume` validates ownership, settles only an unchanged stale task lock, and reacquires claims under the project claims lock.
+- [ ] Project claim locks classify `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`, with CAS-safe stale settlement.
+- [ ] Manually forged COMPLETE state cannot release claims.
+- [ ] Canonically completed task does release claims.
+- [ ] Corrupt/missing completion lifecycle proof retains historical claims.
+- [ ] Task locks with incomplete identity classify UNKNOWN.
+- [ ] Single COMPLETE/RECOVERED task can be inspected implicitly by READ commands.
+- [ ] Single COMPLETE/RECOVERED task cannot be selected implicitly for mutation.
+- [ ] Ownership ledger validation is not redundantly repeated inside one immutable snapshot.
+- [ ] Legacy recovery repair CAS-settles only unchanged stale task locks.
+- [ ] Legacy recovery repair refuses UNKNOWN/CORRUPT task locks.
+- [ ] alreadyRepaired requires a fully valid canonical recovery relationship.
+- [ ] No exported claim helper releases claims from COMPLETE phase alone.
+- [ ] Legacy recovery migration v1 accepts only CALLER_ACKNOWLEDGED authority.
+
+## Compatibility and package gates
+
+- [ ] `package.json` and `package-lock.json` agree on `1.4.0`.
+- [ ] `protocol-info --json` advertises `features.taskClaimRecovery.validatedClaimProjection=true` and task-recovery schema v1.
+- [ ] Documentation states that active task-recovery schema v1 requires a recovery-aware ForgeLoop reader (`>=1.4.0`).
+- [ ] The packed package contains the recovery schema, claim-state core, recovery-history core, and this checklist.
+- [ ] `npm test && npm run lint && npm run coverage && npm run docs:check && npm run pack:check && npm run pack:smoke && npm run dependency:policy` passes once on the release candidate.
+- [ ] `git diff --check` and the repository ForgeLoop audit pass.
+
+## Publication boundary
+
+- [ ] A separately authorized release workflow verifies the final commit, `v1.4.0` tag, npm metadata, tarball digests, and GitHub release identity.
+- [ ] No actor treats caller acknowledgement as `HOST_ATTESTED` authority.

package/docs/RELEASE_CHECKLIST_1_5_MCP.md

@@ -0,0 +1,78 @@
+# ForgeLoop 1.5.0 + MCP release checklist
+
+Preparation checklist for the `@cassiomc1/forgeloop` 1.5.0 and
+`@cassiomc1/forgeloop-mcp` releases. It does not authorize publication.
+
+## Core integration gates
+
+- [ ] Core package version is `1.5.0`; integration API version is `1`.
+- [ ] `exports` map exposes only `.` and `./integration`.
+- [ ] Executor registry is in parity with canonical command definitions.
+- [ ] `bundle` is MAINTENANCE-gated; hidden in readonly/safe.
+- [ ] `resolveForgeLoopProjectRoot` applies CLI target semantics (symlinks rejected).
+- [ ] Integration limits bound strings, arrays, argv, and structured inputs.
+
+## MCP package gates
+
+- [ ] Official SDK v2; target protocol generation `2026-07-28`.
+- [ ] stdio works with clean stdout (protocol-only) and JSON stderr diagnostics.
+- [ ] HTTP is strict modern (`legacy: "reject"`) and loopback-only
+      (`E_MCP_REMOTE_NOT_SUPPORTED` for any other bind).
+- [ ] Transport bounds active: header/request/keepalive timeouts, 4 MiB body cap,
+      POST-only, in-flight ceiling (503 `E_MCP_HTTP_BUSY`).
+- [ ] Tool/resource catalogs are deterministic and identical across transports.
+- [ ] Task-aware mutation tools require explicit `taskId`.
+- [ ] Capability gates re-checked per invocation; tool input cannot elevate policy.
+- [ ] `task-recover`, legacy repair, and force unlock are separately gated;
+      legacy repair hidden by default; `operatorAuthorized` absent from schemas.
+- [ ] No generic shell/exec tool exists.
+
+## Ownership/recovery parity
+
+- [ ] `task/ownership` derives exclusively from the canonical claim resolver.
+- [ ] Forged COMPLETE stays INCONSISTENT with retained claims on every surface.
+- [ ] RECOVERED tasks block ordinary mutation; `task-resume` reacquires canonically.
+- [ ] Concurrent resume yields exactly one winner.
+
+## Safety
+
+- [ ] `maxExecutionTimeMs` enforced: missing→max, zero/negative/float rejected,
+      over-max rejected.
+- [ ] Error payloads preserve canonical codes; secrets redacted; stacks stripped;
+      messages bounded.
+- [ ] Oversized tool/resource output refused with `E_MCP_RESULT_TOO_LARGE`.
+
+## Packaging/docs
+
+- [ ] Core tarball contains integration modules and both integration docs.
+- [ ] MCP tarball contains both bins, src, README; core tarball never ships
+      `integrations/`.
+- [ ] Server `serverInfo.version` equals MCP package.json version.
+- [ ] MCP README documents stdio-default + optional loopback-only HTTP.
+- [ ] THIRD_PARTY_NOTICES covers the Model Context Protocol SDK.
+- [ ] CHANGELOG entries present.
+
+## Exact output-bound gates (post-PR #80)
+
+- [ ] Output bounds measure the exact UTF-8 serialization transmitted
+      (pretty-printed included), not compact JSON.
+- [ ] Compact-below/pretty-above regression covered by tests.
+- [ ] UTF-8 byte-count regression covered by tests.
+- [ ] `forgeloop_capabilities` complete result is bounded like command tools.
+- [ ] Non-size serialization errors are rethrown, not mislabeled as overflow.
+- [ ] Structured tool input is byte-bounded (`E_MCP_INPUT_TOO_LARGE`).
+
+## Documentation gates
+
+- [ ] Repository-wide documentation audit complete.
+- [ ] Documentation manifest/index current.
+- [ ] Generated references current (`docs:generate` leaves no diff).
+- [ ] README / CHANGELOG current.
+- [ ] MCP / Universal Integration docs current.
+- [ ] Security docs current.
+
+## Publication boundary
+
+- [ ] Release identity verification passes.
+- [ ] Publication of either package is separately authorized; this checklist
+      does not itself authorize npm publishing.