@cassiomc1/forgeloop 1.9.0 → 1.10.1

package/docs/PACKAGE_CONTENTS.md

@@ -0,0 +1,83 @@
+# Core npm package contents
+
+This page describes the intentional boundary of the published
+`@cassiomc1/forgeloop` package. The [`files`](../package.json) list in
+`package.json` is the packaging source of truth, while the repository's
+`tests/package.test.js` and clean-room `scripts/package_smoke.mjs` checks keep
+the boundary executable. Those test files are repository tooling and are not
+part of the consumer tarball.
+
+## Consumer surface
+
+The package exposes the `forgeloop` executable from `src/cli.js` and the
+`@cassiomc1/forgeloop/integration` subpath from `src/integration.js`, with its
+declaration file. The package has no runtime dependencies and requires Node.js
+20 or newer.
+
+## Included files
+
+The published tarball includes the following consumer-facing groups:
+
+- **Runtime and protocol:** every maintained JavaScript module under `src/`,
+  the guide registry, protocol templates, JSON schemas, completions, and the
+  generic CI verifier. Four retired compatibility helpers remain in the
+  repository for historical context and are explicitly excluded:
+  `src/core/cli-metadata.js`, `src/core/decision-classification.js`,
+  `src/core/gates.js`, and `src/core/workflow-compatibility.js`.
+- **Initialization material:** the root protocol and integration documents,
+  legal notices, the target profile template, and every path listed by
+  `src/core/templates.js`. These files are read by `init` and `update`, so
+  they are part of the executable consumer contract even when a document is
+  marked deprecated in the documentation manifest.
+- **Benchmark inputs:** execution-profile scenario definitions and their
+  README. They make new measurements reproducible; historical measurements
+  and generated results are repository evidence and are excluded.
+- **User documentation:** the getting-started, integration, CLI, artifact,
+  troubleshooting, release, package-boundary, and related reference pages.
+  The typed diagram sources, generated HTML/SVG/receipt artifacts, and
+  source-bound review records under `docs/diagrams/` are included together so
+  the packaged documentation keeps its visual provenance.
+- **Release tooling:** the selected deterministic generators, validators,
+  benchmark helpers, and shell completions needed by maintainers who consume
+  the source kit.
+
+## Excluded files
+
+The tarball intentionally omits repository-only material:
+
+- tests, conformance fixtures, coverage output, and secret-scanning helpers;
+- local `.forgeloop` state, task ledgers, locks, transactions, and execution
+  receipts (the `.forgeloop/forgeloop.gitignore` template is the sole
+  exception);
+- raw or aggregate benchmark results, package archives, and release train
+  contracts;
+- historical release plans and retired MCP adapter sources; the MCP adapter
+  is published as its own package;
+- the repository README hero PNG, which is a GitHub-only asset. The packaged
+  README remains intentionally text-first around that relative repository
+  image reference.
+
+The package test checks both required paths and these exclusion classes. It
+also enumerates `src/**/*.js` and fails if a maintained runtime module is
+missing from the candidate tarball or if a retired helper is reintroduced.
+The repository index remains a catalog: links from `DOCS_INDEX.md` to tests,
+proof-of-concept evidence, historical plans, and source trees may intentionally
+resolve only in the full repository and are not package dependencies.
+
+## Verification and publication
+
+Run the following checks from a clean checkout before opening a release PR:
+
+```bash
+npm pack --dry-run --json
+npm run pack:check
+npm run pack:smoke
+```
+
+`pack:smoke` installs the candidate tarball into a temporary consumer and
+exercises the CLI, public Integration API, initialization, schemas, and
+packaged documentation references. The tag-triggered publication workflow
+runs the same smoke gate before `npm publish --provenance --access public`.
+Publication therefore remains owned by the trusted GitHub Actions OIDC
+workflow; local package inspection proves the candidate boundary but does not
+publish it.

package/docs/RECIPES.md

@@ -457,6 +457,86 @@ operational context only: a handoff is not delegation, authority, independent
 review evidence, or completion evidence. Use `continuity.json` for mutable
 resume notes and canonical execution artifacts for proof.
 
+### Recipe 18A — Accept an Immutable Handoff Exactly Once
+
+After inspecting the snapshot and confirming that the receiving harness is
+actually consuming it, record the operational receipt:
+
+```bash
+forgeloop handoff-accept --task task-001 \
+  --handoff <handoffId> \
+  --consumer-id agent-session-42 \
+  --harness codex \
+  --json
+```
+
+Retrying with the same consumer is idempotent. A different consumer receives
+`E_HANDOFF_ALREADY_ACCEPTED`. Acceptance is operational only: it does not
+transfer claims, create evidence, approve delegation, or grant authority.
+
+### Recipe 18B — Diagnose an Inconsistent Handoff
+
+Inspect the derived projection and ledger before attempting any repair:
+
+```bash
+forgeloop handoff-list --task task-001 --json
+forgeloop handoff-show --task task-001 --id <handoffId> --json
+forgeloop validate-protocol --task task-001 --json
+```
+
+`INCONSISTENT` is fail-closed. Check the returned reason codes for a stale
+contract/route/repository snapshot, an unbound legacy handoff, a digest mismatch,
+or invalid acceptance history. Do not edit the immutable handoff or
+`events.ndjson`; create a fresh handoff after the canonical issue is resolved.
+
+### Recipe 18C — Use an Advisory Provider from a Host Integration
+
+Register a provider in runtime context and invoke recall explicitly:
+
+```javascript
+import {
+  createForgeLoopContext,
+  recallAdvisoryContext,
+} from "@cassiomc1/forgeloop/integration";
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "host-context": {
+      id: "host-context",
+      recall: async ({ query }) => ({ items: await hostLookup(query) }),
+    },
+  },
+});
+
+const result = await recallAdvisoryContext({
+  target: ".",
+  taskId: "task-001",
+  providerName: "host-context",
+  query: "current authentication constraints",
+  runtimeContext,
+});
+```
+
+Recall is lazy, bounded, opt-in, non-persisted, non-evidence, and
+non-executable. Validate every proposed change against canonical state and
+verification instead of executing provider text.
+
+### Recipe 18D — Resume with Continuity Lint Warnings
+
+Treat lint findings as inspection hints only:
+
+```bash
+forgeloop continuity --task task-001 --json
+forgeloop reconcile-continuity --task task-001 --json
+forgeloop next --task task-001 --json
+```
+
+Findings such as `CONTINUITY_REMAINING_ALREADY_COMPLETED`,
+`CONTINUITY_FOCUS_ALREADY_COMPLETED`, `CONTINUITY_ITEM_ROLE_CONFLICT`,
+`CONTINUITY_INSPECT_PATH_MISSING`, and `CONTINUITY_EMPTY_HINT_SET` are
+non-authoritative and non-evidence. Refresh the note with
+`record-continuity` when useful, then follow the canonical next action.
+
 ---
 
 ### Recipe 19 — Apply a Responsibility Contract

package/docs/RELEASE_CHECKLIST.md

@@ -13,9 +13,29 @@ preparation and verification checklist; it does not authorize publication.
 - [ ] `npm pack --dry-run` contains the required scenario definitions but no
       raw or aggregate benchmark results, tests, local state, or repository
       metadata.
+- [ ] [`docs/PACKAGE_CONTENTS.md`](./PACKAGE_CONTENTS.md) matches the current
+      `package.json` file list and documents intentional inclusions and
+      exclusions.
+- [ ] Every maintained `src/**/*.js` module is present in the candidate
+      tarball; only the four explicitly retired compatibility helpers are
+      excluded.
 
 ## Protocol and attestation
 
+- [ ] `protocol-info` and the Integration API capability contracts agree.
+- [ ] `canonicalHandoffs` v2 is advertised consistently.
+- [ ] `advisoryContextProviders` v1 is advertised consistently.
+- [ ] Advisory context remains Integration-API-only.
+- [ ] `next`, `status`, and `task/context` invoke zero advisory providers.
+- [ ] Advisory request budgets are normalized before provider invocation.
+- [ ] Advisory results are never persisted by ForgeLoop.
+- [ ] Same-consumer handoff acceptance is idempotent.
+- [ ] Different-consumer handoff acceptance fails closed.
+- [ ] Concurrent acceptance creates one `HANDOFF_ACCEPTED` event.
+- [ ] Clean HEAD/branch drift rejects handoff acceptance.
+- [ ] Stale contract/route identity rejects handoff creation or acceptance.
+- [ ] An invalid event ledger projects `INCONSISTENT`.
+- [ ] Continuity lint remains non-authoritative and non-evidence.
 - [ ] `npm run dependency:policy` passes without adding runtime dependencies.
 - [ ] `npm run lint` passes.
 - [ ] `npm test` passes.
@@ -48,6 +68,8 @@ preparation and verification checklist; it does not authorize publication.
 ## Integration and cross-platform evidence
 
 - [ ] `npm run pack:check` and `npm run pack:smoke` pass.
+- [ ] The npm publication workflow runs `npm run pack:smoke` before its
+      provenance-backed publish step.
 - [ ] `npm run mcp:test` either runs the configured MCP tests or reports the
       single actionable setup prerequisite.
 - [ ] `npm run mcp:pack:check` passes when MCP dependencies are available.

package/docs/REVISION_PROVIDERS.md

@@ -134,3 +134,12 @@ provider semantics fail closed.
 An implementation should be tested for deterministic identity, exact bytes,
 binary and empty files, Unicode and space-containing paths, symlinks,
 Gitlinks, deletions, renames, path traversal, and stable error mapping.
+
+### Focused test selection and evidence
+
+A test-runner filter chooses what a command executes. It does not establish a
+canonical differential verification scope. Use `run-check` to bind executed
+commands to evidence, and supply a fresh canonical scope reference when the
+checker requires one. A manual observation must declare `manual-review`;
+command metadata alone does not prove that a process ran. Packed TypeScript
+consumer checks and critical lifecycle coverage complement these boundaries.

package/docs/TROUBLESHOOTING.md

@@ -761,16 +761,50 @@ explicit operation only when the task's scope permits it.
 
 ---
 
+### Symptom: Advisory Context Recall Is Unavailable or Rejected
+
+#### Error Codes: `E_ADVISORY_CONTEXT_PROVIDER_INVALID`, `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE`, `E_ADVISORY_CONTEXT_QUERY_INVALID`, `E_ADVISORY_CONTEXT_REQUEST_INVALID`, `E_ADVISORY_CONTEXT_RESULT_INVALID`, `E_ADVISORY_CONTEXT_TIMEOUT`, `E_ADVISORY_CONTEXT_OUTPUT_LIMIT`, `E_PORTABLE_CONTEXT_INVALID`
+
+#### What it means
+
+The host's optional advisory provider is missing, malformed, unavailable, too
+slow, or returned content outside the bounded portable-context contract. These
+failures never become lifecycle, evidence, completion, or next-action failures.
+
+#### Safe recovery
+
+Inspect provider registration and normalize the request before retrying through
+the Integration API. Reduce query, item, total-output, and timeout values to the
+documented budgets, remove secrets/control characters, and ensure the provider
+returns only allowlisted item fields. If advisory context is unavailable,
+continue from canonical task state; do not fabricate a provider or execute its
+text.
+
+### Symptom: Continuity Lint Reports a Contradictory Hint
+
+Continuity lint is diagnostic only. Its findings do not change reconciliation,
+state, evidence, authority, or completion:
+
+| Finding | Meaning | Safe response |
+| --- | --- | --- |
+| `CONTINUITY_REMAINING_ALREADY_COMPLETED` | A remaining-work item is already recorded as completed. | Refresh the operational note; do not change canonical completion evidence. |
+| `CONTINUITY_FOCUS_ALREADY_COMPLETED` | The current focus ID is already completed. | Choose a current inspection focus or clear the hint. |
+| `CONTINUITY_ITEM_ROLE_CONFLICT` | An item appears in both remaining work and known issues. | Remove the contradictory hint through `record-continuity`. |
+| `CONTINUITY_INSPECT_PATH_MISSING` | An `inspectFirst` path is not present in the current target. | Reconcile the checkout and update the path hint. |
+| `CONTINUITY_EMPTY_HINT_SET` | No operational hint was supplied. | Treat the result as informational and follow canonical `next`. |
+
 ### Symptom: Handoff Is Invalid or Tampered
 
-#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`
+#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`, `E_HANDOFF_STALE`, `E_HANDOFF_ALREADY_ACCEPTED`, `E_HANDOFF_ACCEPTANCE_INCONSISTENT`
 
 #### What it means
 
 The immutable handoff envelope is malformed, its state is unavailable, its
 digest no longer matches, or the requested snapshot does not exist. A handoff
 note is not delegation, authority, independent review evidence, or completion
-evidence.
+evidence. Acceptance is exactly-once operational receipt only. The current
+repository branch and HEAD are checked directly, so clean committed checkout
+drift can make a handoff stale even when changed paths are empty.
 
 #### Safe recovery
 
@@ -781,6 +815,12 @@ forgeloop continuity --task <id> --json
 forgeloop reconcile-continuity --task <id> --json
 ```
 
+If `handoff-list` or `handoff-show` reports `INCONSISTENT`, inspect the
+`reasonCodes` field. The commands validate the event ledger before projecting
+acceptance and never turn an unreadable or invalid ledger into an empty ledger.
+Repair the named ledger through the canonical protocol workflow; do not edit
+`events.ndjson` by hand.
+
 Use the last valid handoff or continuity only to focus inspection, then trust
 the canonical task state and checkout. Never repair a handoff by editing or
 deleting its JSON file.
@@ -1002,6 +1042,13 @@ current-cycle validation.
 | `E_ACTION_STATE_MISMATCH` | Requested durable action transition is not part of the canonical state machine. | Inspect current action state with forgeloop action-show and use a legal transition; never edit action artifacts by hand. |
 | `E_ACTION_VERIFICATION_INVALID` | Verification evidence does not resolve to a canonical passed ForgeLoop artifact bound to this task and action. | Supply a canonical execution or check reference produced by run-check for this task; arbitrary strings fail closed. |
 | `E_ACTION_VERIFICATION_REQUIRED` | The action cannot reach VERIFIED through this surface; canonical independent postcondition evidence is required. | Run an independent verification check, then record it with forgeloop action-verify; exit code 0 alone is not verification. |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | Advisory context output exceeded the configured character or item limit. | Reduce query scope, limit items, or truncate oversized summaries at the provider. |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` | Advisory context provider configuration or interface implementation is invalid. | Use a provider implementing id, recall(input) with bounded query parameters; advisory context is optional. |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | Requested advisory context provider is not registered in runtime context. | Register the provider in runtime context before recall, or proceed without advisory context; provider failure never blocks canonical lifecycle. |
+| `E_ADVISORY_CONTEXT_QUERY_INVALID` | Advisory context query failed portable-context validation or exceeded budget. | Provide a bounded query free of control characters and secret-like values. |
+| `E_ADVISORY_CONTEXT_REQUEST_INVALID` | Advisory context recall budgets are not finite integer values within the supported request contract. | Provide finite integer limit, maxItemChars, maxTotalChars, and timeoutMs values; oversized valid values are clamped to documented maxima. |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | Advisory context provider returned an invalid result structure. | Ensure provider returns items with string summary and optional title, sourceRef, observedAt, confidence. |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Advisory context recall exceeded its execution timeout. | Use a responsive provider or increase timeout within limits; advisory context is optional. |
 | `E_APPROVAL_ALREADY_RESOLVED` | Approval is one-time resolvable and has already been approved or rejected. | Request a new approval if another decision is required. |
 | `E_APPROVAL_INVALID` | Approval artifact is malformed or does not bind the required fingerprint tuple. | Request a new approval with forgeloop approval-request; never hand-edit approval artifacts. |
 | `E_APPROVAL_STALE` | Approval no longer matches the current action fingerprint, contract fingerprint, task revision, or capability. | Request and resolve a fresh approval against the current action revision. |
@@ -1090,8 +1137,12 @@ current-cycle validation.
 | `E_GATE_REQUIRED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_GATE_STALE` | Referenced gate artifact changed after approval. | Update artifact SHA-256 in gate file. |
 | `E_GATE_UNVERIFIED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_HANDOFF_ACCEPTANCE_INCONSISTENT` | Handoff acceptance disagrees with task event ledger history. | Verify ledger integrity and require a preceding valid HANDOFF_CREATED event. |
+| `E_HANDOFF_ACCEPTANCE_UNBOUND` | Handoff snapshot lacks required workStateFingerprint binding. | Create a fresh handoff from the current ForgeLoop version before accepting it. |
+| `E_HANDOFF_ALREADY_ACCEPTED` | Handoff was already accepted by a different consumer. | Create a new handoff for the new consumer; do not manually edit acceptance events. |
 | `E_HANDOFF_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_HANDOFF_NOT_FOUND` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_HANDOFF_STALE` | Handoff snapshot has drifted from the current canonical task state or repository. | Create a new fresh handoff from the current task state instead of accepting a stale snapshot. |
 | `E_HANDOFF_STATE_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_HANDOFF_TAMPERED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID` | Hypothesis disposition evidence references do not resolve to checks of the active cycle. | Reference at least one check ID recorded in the active verification cycle. |
@@ -1124,6 +1175,7 @@ current-cycle validation.
 | `E_POLICY_PROOF_STALE` | Mutation verification proof is stale due to checker or fixture modifications. | Re-run forgeloop rule-verify to refresh mutation proof. |
 | `E_POLICY_SNAPSHOT_WRITE_FAILED` | Failed to persist task policy snapshot during preflight. | Ensure the target task directory is writable and repair filesystem permissions. |
 | `E_POLICY_WEAKENING` | Policy rules were weakened during task execution without explicit authority. | Restore the original policy configuration. |
+| `E_PORTABLE_CONTEXT_INVALID` | Text or object failed portable-context safety, character, or secret limits. | Ensure text is bounded, contains no control characters, and contains no secret-like values. |
 | `E_PREFLIGHT_EVENT_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PREFLIGHT_GATES_STALE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PREFLIGHT_GATE_EVENT_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -1247,3 +1299,15 @@ current-cycle validation.
 | `E_WORKSPACE_IDENTITY_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 
 <!-- END FORGELOOP GENERATED: public-error-codes -->
+
+## Revised contract after a blocked preflight
+
+Before execution starts, a revised contract and route can leave the old
+checkpoint stale. Run `forgeloop next --task <id> --json`. When the validated
+history ends in a blocked preflight and the new route binds the revised
+contract, it offers `clear-state` followed by `preflight`. Execute those in
+that order, satisfy any remaining gates, and require `READY` again.
+
+This recovery guidance is unavailable after execution has started, for an
+invalid ledger, or when the new route does not match the contract. Preserve
+those barriers and follow the task's canonical recovery guidance.

package/docs/UNIVERSAL_INTEGRATION.md

@@ -93,6 +93,66 @@ commands in [`EXECUTION_PROFILE_BENCHMARKS.md`](./EXECUTION_PROFILE_BENCHMARKS.m
 The benchmark source policy accepts provider or host observations only and
 keeps unavailable or non-comparable measurements out of efficiency claims.
 
+### Advisory Context & Handoff Acceptance
+
+Capability negotiation is feature-first: `canonicalHandoffs` is v2 and
+`advisoryContextProviders` is v1. These capability-family versions are
+independent of Protocol v1, schema v1, and Integration API v1. The programmatic
+integration API exposes lazy advisory context querying and exactly-once handoff
+acceptance:
+
+```javascript
+import {
+  createForgeLoopContext,
+  recallAdvisoryContext,
+  acceptCanonicalHandoff,
+  resolveHandoffAcceptance,
+} from "@cassiomc1/forgeloop/integration";
+
+// 1. Register host-provided advisory context
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "host-memory": {
+      id: "host-memory",
+      recall: async ({ query }) => ({ items: [...] }),
+    },
+  },
+});
+
+// 2. Explicitly query advisory context (strictly non-evidence, non-executable)
+const advisoryResult = await recallAdvisoryContext({
+  target: ".",
+  taskId: "task-1",
+  providerName: "host-memory",
+  query: "authentication tokens",
+  runtimeContext,
+});
+
+// 3. Exactly-once handoff acceptance
+const acceptance = await acceptCanonicalHandoff(".", {
+  taskId: "task-1",
+  handoffId: "handoff-001",
+  consumerId: "agent-session-42",
+  harness: "cursor",
+});
+```
+
+See [`ADVISORY_CONTEXT.md`](./ADVISORY_CONTEXT.md) for full trust boundary specifications, portable text sanitization rules, and budget enforcement.
+
+Advisory recall budgets are normalized before provider dispatch: valid oversized
+integer requests are clamped, while invalid finite/integer/minimum types fail
+with `E_ADVISORY_CONTEXT_REQUEST_INVALID` before provider lookup. The registry
+key and resolved provider `id` must match. Handoff acceptance independently
+checks canonical state and the current repository branch/HEAD, and remains an
+exactly-once operational receipt with no evidence, claim transfer, or authority.
+
+Advisory context is not a canonical resource unless a future explicitly
+versioned resource introduces one. `protocol-info` advertises the optional
+provider capability, but the stock CLI never recalls it automatically and
+there is no stock `context-recall` command. A consumer that only understands
+`canonicalHandoffs` v1 may disable only the handoff-specific UI while retaining
+the rest of Protocol v1 functionality.
+
 ## Consumers
 
 | Surface | Entry |

package/docs/assets/diagrams/forgeloop-code-attestation-flow.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en" data-theme="dark" data-preset="signal-flow" data-present="true">
 <head>
-      <meta name="forgeloop-diagram-source-sha256" content="669966fba9e69df0525a3581baa4e90075923dbe3069f81f706761a40abf9073">
+      <meta name="forgeloop-diagram-source-sha256" content="33bb9c3c4f3fb4a793febeab34b2d07ca7bf2c058d4f5e7575dba3a6065eedeb">
     <meta name="forgeloop-diagram-renderer" content="archify@2.15.0 (e1ac748f19cf805e44bf74fb93c796662152e273)">
 <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -40,6 +40,15 @@
   <style>
       /* Keep boundary labels clear of the first node in each group. */
       [data-composition-frame-kind="group"] + text { transform: translateY(-18px); }
+      @media (max-width: 720px) {
+        html:not([data-present="true"]) .toolbar {
+          top: 0;
+          right: 0;
+          width: 100%;
+          flex-wrap: wrap;
+          justify-content: flex-start;
+        }
+      }
 
     /* ==========================================================
        THEME VARIABLES — switch by toggling [data-theme] on <html>
@@ -4868,7 +4877,7 @@
       <p class="subtitle">Exact content binding from valid completion to read-only trust results</p>
     </div>
 
-    <script id="archify-guided-views-data" type="application/json">[{"id":"completion-to-manifest","label":"Completion to manifest","focus":["complete","receipt","manifest","captured"],"note":"Follow the transactional binding between valid completion evidence and exact source content."},{"id":"manifest-to-statement","label":"Manifest to statement","focus":["manifest","captured","statement","signing","bundle"],"note":"See how the deterministic code manifest becomes an in-toto Statement v1 and optional signature bundle."},{"id":"revision-range-coverage","label":"Revision-range coverage","focus":["base","provider","changed","attestations","union","range"],"note":"Inspect the separate changed-path coverage question and its gap or conflict result."}]</script>
+    <script id="archify-guided-views-data" type="application/json">[{"id":"completion-to-manifest","label":"Completion to manifest","focus":["complete","receipt","manifest","captured"],"note":"Completion and exact-content evidence bind to the project and task. No supplied CI receipt means NOT_VERIFIED."},{"id":"manifest-to-statement","label":"Manifest to statement","focus":["manifest","captured","statement","signing","bundle"],"note":"See how the deterministic code manifest becomes an in-toto Statement v1 and optional signature bundle."},{"id":"revision-range-coverage","label":"Revision-range coverage","focus":["base","provider","changed","attestations","union","range"],"note":"Inspect the separate changed-path coverage question and its gap or conflict result."}]</script>
 
     <div class="guided-views no-print" id="guided-views" hidden aria-label="Guided diagram views">
       <button id="guided-view-prev" type="button" aria-label="Previous guided view" title="Previous guided view ([)">&#8592;</button>
@@ -5426,6 +5435,7 @@
           <li>&bull; PROCESSED means artifacts exist and parse</li>
           <li>&bull; VERIFIED means completion, evidence, manifest, and content bindings validate</li>
           <li>&bull; ATTESTED additionally requires a valid external signature policy</li>
+          <li>&bull; No supplied CI receipt means NOT_VERIFIED, not a trust level</li>
         </ul>
       </div>
 
@@ -5438,6 +5448,7 @@
           <li>&bull; The manifest records one SHA-256 digest per changed source entry</li>
           <li>&bull; The in-toto statement binds the manifest to completion evidence</li>
           <li>&bull; Read-only verification never rewrites task state or ledger events</li>
+          <li>&bull; Compaction preserves transaction manifests and event history</li>
         </ul>
       </div>
 

package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json

@@ -15,17 +15,17 @@
     "license": "MIT"
   },
   "input": {
-    "sha256": "669966fba9e69df0525a3581baa4e90075923dbe3069f81f706761a40abf9073",
-    "bytes": 7744
+    "sha256": "33bb9c3c4f3fb4a793febeab34b2d07ca7bf2c058d4f5e7575dba3a6065eedeb",
+    "bytes": 9857
   },
   "artifacts": {
     "html": {
-      "sha256": "62666342ec4efbc295ed65f4450008ca5a39072d8a11ff7b8b675ab258711286",
-      "bytes": 652836
+      "sha256": "85bb7abf910d3f6dd12037cfcd90c4b67f0aad4dca2b4cb21be1b0112cbdd92e",
+      "bytes": 653258
     },
     "svg": {
-      "sha256": "0af63dd51683d07981fc681042c437377a78ae8a7e6a7175c18a1def02e6280a",
-      "bytes": 216313
+      "sha256": "3a768148886ffdfcce75221c11e51ee77a3702510e90917bf6e8ba0581ebdb44",
+      "bytes": 216543
     }
   },
   "staticSvg": {

package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg

@@ -1,8 +1,17 @@
-<svg data-archify-version="2.15.0" data-forgeloop-source-sha256="669966fba9e69df0525a3581baa4e90075923dbe3069f81f706761a40abf9073" data-theme="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 1024" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
+<svg data-archify-version="2.15.0" data-forgeloop-source-sha256="33bb9c3c4f3fb4a793febeab34b2d07ca7bf2c058d4f5e7575dba3a6065eedeb" data-theme="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 1024" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
     <style>
       .c-bg-rect { fill: var(--bg); }
 /* Keep boundary labels clear of the first node in each group. */
       [data-composition-frame-kind="group"] + text { transform: translateY(-18px); }
+      @media (max-width: 720px) {
+        html:not([data-present="true"]) .toolbar {
+          top: 0;
+          right: 0;
+          width: 100%;
+          flex-wrap: wrap;
+          justify-content: flex-start;
+        }
+      }
 
     /* ==========================================================
        THEME VARIABLES — switch by toggling [data-theme] on &lt;html>

package/docs/assets/diagrams/forgeloop-engineering-flow.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en" data-theme="dark" data-preset="signal-flow" data-present="true">
 <head>
-      <meta name="forgeloop-diagram-source-sha256" content="a83128a8639db5db497ac552cfdbc318839e6451c718581fbfcd064e3e869981">
+      <meta name="forgeloop-diagram-source-sha256" content="0bfd5bbf8d6bbeaec23db543deb1e99844321c77b3c7feb21ee0cc877bbba9a9">
     <meta name="forgeloop-diagram-renderer" content="archify@2.15.0 (e1ac748f19cf805e44bf74fb93c796662152e273)">
 <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -40,6 +40,15 @@
   <style>
       /* Keep boundary labels clear of the first node in each group. */
       [data-composition-frame-kind="group"] + text { transform: translateY(-18px); }
+      @media (max-width: 720px) {
+        html:not([data-present="true"]) .toolbar {
+          top: 0;
+          right: 0;
+          width: 100%;
+          flex-wrap: wrap;
+          justify-content: flex-start;
+        }
+      }
 
     /* ==========================================================
        THEME VARIABLES — switch by toggling [data-theme] on <html>
@@ -4865,10 +4874,10 @@
         <div class="pulse-dot"></div>
         <h1>ForgeLoop Evidence-First Engineering Flow</h1>
       </div>
-      <p class="subtitle">Typed intent → scoped work → observed evidence → validator-backed closure</p>
+      <p class="subtitle">Structured intent → project-bound work → observed evidence → valid closure</p>
     </div>
 
-    <script id="archify-guided-views-data" type="application/json">[{"id":"contract-to-work","label":"Contract to work","focus":["request","profile","contract","route","gates","preflight","work"],"note":"Follow how a request becomes scoped, routed, and safe to execute."},{"id":"evidence-to-close","label":"Evidence to close","focus":["work","evidence","review","valid"],"note":"See the evidence and review boundary that makes completion trustworthy."},{"id":"recovery-loop","label":"Recovery loop","focus":["evidence","diagnose","correct","preflight","blocked"],"note":"Failures return to diagnosis and correction before another claim is made."}]</script>
+    <script id="archify-guided-views-data" type="application/json">[{"id":"contract-to-work","label":"Contract to work","focus":["request","profile","contract","route","gates","preflight","work"],"note":"Structured obligations and explicit risks set the profile; exclusions do not create required actions."},{"id":"evidence-to-close","label":"Evidence to close","focus":["work","evidence","review","valid"],"note":"See the evidence and review boundary that makes completion trustworthy."},{"id":"recovery-loop","label":"Recovery loop","focus":["evidence","diagnose","correct","preflight","blocked"],"note":"Before execution, blocked refresh needs a valid ledger and revised route. Later failures use diagnosis and correction."}]</script>
 
     <div class="guided-views no-print" id="guided-views" hidden aria-label="Guided diagram views">
       <button id="guided-view-prev" type="button" aria-label="Previous guided view" title="Previous guided view ([)">&#8592;</button>
@@ -4911,9 +4920,9 @@
 
     <!-- Main Diagram -->
     <div class="diagram-container" data-detail-level="read">
-      <svg viewBox="0 0 720 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
+      <svg viewBox="0 0 850 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
         <title id="archify-diagram-title">ForgeLoop Evidence-First Engineering Flow</title>
-        <desc id="archify-diagram-description">Typed intent → scoped work → observed evidence → validator-backed closure</desc>
+        <desc id="archify-diagram-description">Structured intent → project-bound work → observed evidence → valid closure</desc>
         <!-- Definitions -->
         <defs>
           <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
@@ -5065,19 +5074,19 @@
         <text data-detail="fine" x="500" y="265" class="t-security" font-size="7" text-anchor="middle">Preflight</text>
         </g>
 
-        <g id="node-work" data-node-id="work" data-node-label="Execution" tabindex="0" role="button" aria-label="Focus Execution, checkpoint, Resumable Execution › Route + authorize" aria-pressed="false" data-node-kind="backend" data-node-sublabel="checkpoint" data-node-context="Resumable Execution › Route + authorize">
-          <title>Execution · checkpoint · Resumable Execution › Route + authorize</title>
+        <g id="node-work" data-node-id="work" data-node-label="Execution" tabindex="0" role="button" aria-label="Focus Execution, root + task, Resumable Execution › Route + authorize" aria-pressed="false" data-node-kind="backend" data-node-sublabel="root + task" data-node-context="Resumable Execution › Route + authorize">
+          <title>Execution · root + task · Resumable Execution › Route + authorize</title>
           <rect x="469" y="341" width="62" height="52" rx="6" class="c-mask"/>
           <rect x="469" y="341" width="62" height="52" rx="6" class="c-backend" data-animate="node" style="--step:6" stroke-width="1.5"/>
           <g aria-hidden="true" data-semantic-sigil="backend" class="semantic-sigil s-backend" transform="translate(475 347) scale(0.6875)">
             <path d="M6 3 3 8l3 5M10 3l3 5-3 5"/>
           </g>
           <text data-detail-anchor x="500" y="362" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">Execution</text>
-          <text data-detail="context" x="500" y="379" class="t-muted" font-size="8" text-anchor="middle">checkpoint</text>
+          <text data-detail="context" x="500" y="379" class="t-muted" font-size="8" text-anchor="middle">root + task</text>
         </g>
 
-        <g id="node-evidence" data-node-id="evidence" data-node-label="Evidence" tabindex="0" role="button" aria-label="Focus Evidence, scope + checks, Evidence Ledger › Evidence boundary › Route + authorize" aria-pressed="false" data-node-kind="database" data-node-sublabel="scope + checks" data-node-tag="observed" data-node-context="Evidence Ledger › Evidence boundary › Route + authorize">
-          <title>Evidence · scope + checks · Evidence Ledger › Evidence boundary › Route + authorize · observed</title>
+        <g id="node-evidence" data-node-id="evidence" data-node-label="Evidence" tabindex="0" role="button" aria-label="Focus Evidence, run-check, Evidence Ledger › Evidence boundary › Route + authorize" aria-pressed="false" data-node-kind="database" data-node-sublabel="run-check" data-node-tag="observed" data-node-context="Evidence Ledger › Evidence boundary › Route + authorize">
+          <title>Evidence · run-check · Evidence Ledger › Evidence boundary › Route + authorize · observed</title>
           <rect x="465" y="457" width="70" height="68" rx="6" class="c-mask"/>
           <rect x="465" y="457" width="70" height="68" rx="6" class="c-database" data-animate="node" style="--step:7" stroke-width="1.5"/>
           <g aria-hidden="true" data-semantic-sigil="database" class="semantic-sigil s-database" transform="translate(471 463) scale(0.6875)">
@@ -5085,7 +5094,7 @@
             <path d="M3 4v8c0 1.1 2.2 2 5 2s5-.9 5-2V4M3 8c0 1.1 2.2 2 5 2s5-.9 5-2"/>
           </g>
           <text data-detail-anchor x="500" y="478" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Evidence</text>
-          <text data-detail="context" x="500" y="495" class="t-muted" font-size="7.3" text-anchor="middle">scope + checks</text>
+          <text data-detail="context" x="500" y="495" class="t-muted" font-size="8" text-anchor="middle">run-check</text>
         <text data-detail="fine" x="500" y="513" class="t-database" font-size="7" text-anchor="middle">observed</text>
         </g>
 
@@ -5383,6 +5392,7 @@
           <li>&bull; Workspace binding is optional but blocks mismatched execution</li>
           <li>&bull; Failures return to diagnosis before another claim</li>
           <li>&bull; Completion is validator-backed, not inferred from a screenshot</li>
+          <li>&bull; Blocked pre-execution refresh requires a valid ledger and revised route</li>
         </ul>
       </div>
 
@@ -5396,6 +5406,7 @@
           <li>&bull; run-check binds exact commands to an execution reference</li>
           <li>&bull; record-check covers manual observations</li>
           <li>&bull; Drift reopens verification instead of being hidden</li>
+          <li>&bull; Matching task IDs never authorize cross-project transaction reuse</li>
         </ul>
       </div>
 

package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json

@@ -15,17 +15,17 @@
     "license": "MIT"
   },
   "input": {
-    "sha256": "a83128a8639db5db497ac552cfdbc318839e6451c718581fbfcd064e3e869981",
-    "bytes": 7610
+    "sha256": "0bfd5bbf8d6bbeaec23db543deb1e99844321c77b3c7feb21ee0cc877bbba9a9",
+    "bytes": 9779
   },
   "artifacts": {
     "html": {
-      "sha256": "55d71098d15a46778454d53690110195e0e923d37f34cb6c57fcc5e6601ab7ec",
-      "bytes": 647796
+      "sha256": "251e09f3cc36d54c4b8567dd3e6dd8a890a2621cdd12667fb80cc61e7dbf4b7c",
+      "bytes": 648281
     },
     "svg": {
-      "sha256": "37244a07cc862e3fe4a7188f5236a509a4adf565d5b785ba3c0932057ac6f3a8",
-      "bytes": 211160
+      "sha256": "ef3effe7e756494c7dffef9ee315e970bbbdb9fddc0ee0a1e4bfccfbb0c05534",
+      "bytes": 211373
     }
   },
   "staticSvg": {