@cassiomc1/forgeloop 1.10.0 → 1.10.2

package/DOCS_INDEX.md

@@ -32,12 +32,14 @@ integration and guide context. Use this map before editing documentation.
 | Platform adapters | [`docs/PLATFORM_ADAPTERS.md`](./docs/PLATFORM_ADAPTERS.md) | Generic CI boundary and platform mapping guidance |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
 | Advisory context providers | [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) | Optional external host context, non-evidence trust boundary, allowlist normalization, and safety rules |
+| Ripwire advisory adapter | [`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md) | Ripwire-specific registration, process contract, JSON mapping, limits, and verification |
 | Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
 | Adaptive execution-profile benchmarks | [`docs/EXECUTION_PROFILE_BENCHMARKS.md`](./docs/EXECUTION_PROFILE_BENCHMARKS.md) | Measured provider/host runs, robust statistics, paired/distribution deltas, tail status, outliers, and profile-aware host context |
 | Knowledge integration gap analysis | [`docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md`](./docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md) | Repository-only research audit of candidate coverage, proven gaps, canonical homes, context cost, and intentional skip/defer decisions |
 | Knowledge sources and provenance | [`docs/KNOWLEDGE_SOURCES.md`](./docs/KNOWLEDGE_SOURCES.md) | Snapshot, licensing observations, source roles, accepted/skipped concepts, and reuse boundaries |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | Current release checklist | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) | Package, protocol, attestation, integration, and publication gates |
+| Core npm package contents | [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md) | Published consumer surface, intentional inclusions, exclusions, and clean-room verification |
 | ForgeLoop 1.6.1 release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) | Verification adapter boundary, isolation invariants, and publication gates |
 | ForgeLoop 1.5/MCP release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) | Integration API v1, MCP package, and publication gates |
 | ForgeLoop 1.4 release checklist | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) | Claim-recovery, compatibility, package, and publication gates |
@@ -57,6 +59,13 @@ integration and guide context. Use this map before editing documentation.
 | Code Attestation Chain | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#completion-flow) | Completion, exact-content manifest, in-toto statement, optional signing, and range coverage |
 | Real Execution Proof of Concept (PoC) | [`poc/README.md`](./poc/README.md) | Non-normative, reproducible public engineering workload, audit evidence, and technical audit. Normative behavior remains owned by [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md). |
 
+## Recent implementation review
+
+The repository-local [Astra implementation record](./docs/ASTRA_IMPLEMENTATION.md)
+maps the completed findings to code, tests, measurements, and remaining limits.
+Use the canonical guides below for operational instructions; the audit record
+is historical evidence and is not part of the published core package.
+
 ## Audience map
 
 | I am a... | Start here |
@@ -72,6 +81,7 @@ integration and guide context. Use this map before editing documentation.
 | **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
 | **Configuring structural quality feedback** | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) |
+| **Configuring Ripwire advisory context** | [`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md) |
 | **Understanding verification trust** | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) |
 | **Understanding attestation trust** | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#trust-levels) |
 | **Maintaining generated diagrams** | [`docs/diagrams/README.md`](./docs/diagrams/README.md) |
@@ -98,6 +108,7 @@ integration and guide context. Use this map before editing documentation.
 - **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
 - **Map ForgeLoop state into an external runtime/orchestrator**: [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md)
 - **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
+- **Audit the npm package boundary**: [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md)
 - **Verify source-content attestations**: [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
 - **Understand narrow verification and checker binding**: [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
 - **Inspect the governed diagrams**: [`docs/diagrams/README.md`](./docs/diagrams/README.md)
@@ -131,7 +142,7 @@ scope, exact commands, and migration boundary are recorded in
 [`scripts/CI_VALIDATORS.md`](./scripts/CI_VALIDATORS.md).
 
 The package has no runtime dependencies. Development dependencies are limited
-to ESLint and c8 and are checked by
+to c8, ESLint, TypeScript, and YAML and are checked by
 `npm run dependency:policy`. GitHub Actions use `npm ci`, pinned action SHAs,
 CodeQL, dependency review, and generated-release notes; npm publication still
 uses trusted OIDC publishing and is not implied by local verification.

package/LOOP_ENGINEERING.md

@@ -393,8 +393,8 @@ DESTRUCTIVE_ACTION_REQUIRED
 ```
 
 Multiple reasonable aesthetic or positioning choices do not justify a question.
-The deterministic support helper in `src/core/decision-classification.js`
-validates this boundary; it does not use an LLM or parse natural language.
+The executable test example in `tests/helpers/decision-classification.js`
+illustrates this boundary; runtime authority remains with this protocol and the task contract. The example does not use an LLM or parse natural language.
 
 ### Contract-before-clarification sequence
 
@@ -508,8 +508,8 @@ The compatibility distinction is explicit:
 "Installed" and "compatible" are different claims. A harness can have an
 external workflow installed and still be `INCOMPATIBLE WITH AUTONOMOUS MODE`.
 Use that wording instead of calling the workflow broken. The deterministic
-support helper in `src/core/workflow-compatibility.js` evaluates this boundary;
-it does not modify `src/core/decision-classification.js`, invoke an LLM, or
+test example in `tests/helpers/workflow-compatibility.js` exercises this boundary;
+it does not modify `tests/helpers/decision-classification.js`, invoke an LLM, or
 redesign a runtime, arbiter, supervisor, or approval broker.
 
 For the sixth blind conformance run, exclude mandatory-approval workflows at

package/LOOP_SYSTEM_DESIGN.md

@@ -561,3 +561,26 @@ canonical trace/reflection evidence. They preserve unknown usage values and
 only compare efficiency when a project-local reference scenario exists. The
 existing diagnostic and reflection model remains the authority for information
 gain, intervention effectiveness, failure signatures, and oscillation.
+
+## Transaction identity and diagnostic retention
+
+The transaction context binds the physical project root and task ID. Nested
+operations reject cross-project reuse, even when task IDs match. Filesystem
+aliases of the same physical project remain compatible. Reads and writes of
+transaction-aware artifacts enforce the same project boundary.
+
+Committed transactions, successful rollbacks, and failures aborted before
+publication are terminal. `doctor --fix` recovers eligible committing
+transactions under their task locks, then recomputes incomplete findings.
+This does not imply that an ambiguous external action was reconciled.
+
+Repository maintenance can preview or compact old terminal stage/backup
+payloads with `npm run transactions:compact`. Manifests and event ledgers
+remain intact; recent, ambiguous, invalid, locked, and unsafe records are
+preserved. See [maintenance usage](CONTRIBUTING.md#focused-verification-and-maintenance).
+
+Lifecycle selection keeps common identity, freshness, gates, and chronology
+checks ahead of phase-specific resolvers. Planning, verification, review,
+recovery, and pending-action modules organize decisions without changing that
+precedence. Executable protocol examples under `tests/helpers` are test
+fixtures, not runtime policy authorities.

package/QUALITY_SCORECARD.md

@@ -106,8 +106,8 @@ are both present:
 | Protocol activation resumability | `src/core/resumability.js`, READY consistency checks, event matrix, and `next` repair semantics | `tests/resumable-protocol.test.js` |
 | Hidden kit layout | `src/core/target-layout.js`, safe init/update migration, manifest layout version, native shims, and profile resolver | `tests/hidden-layout.test.js`, package and compatibility tests |
 | Contextual frontend taste | `ENG/taste-frontend-eng.md`, router metadata, attribution, and design/accessibility precedence | `tests/taste-guide.test.js`, route fixtures |
-| Pre-contract autonomy — structural | `LOOP_ENGINEERING.md`, `src/core/decision-classification.js`, `src/core/workflow-compatibility.js`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc` | `tests/decision-classification.test.js`, `tests/workflow-compatibility.test.js`, `tests/autonomy-policy.test.js`, `tests/preflight.test.js` |
-| External workflow compatibility — structural | `LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `src/core/workflow-compatibility.js`, and sixth-run harness metadata rule | `tests/workflow-compatibility.test.js`, `conformance/README.md` |
+| Pre-contract autonomy — structural | `LOOP_ENGINEERING.md`, `tests/helpers/decision-classification.js`, `tests/helpers/workflow-compatibility.js`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc` | `tests/decision-classification.test.js`, `tests/workflow-compatibility.test.js`, `tests/autonomy-policy.test.js`, `tests/preflight.test.js` |
+| External workflow compatibility — structural | `LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `tests/helpers/workflow-compatibility.js`, and sixth-run harness metadata rule | `tests/workflow-compatibility.test.js`, `conformance/README.md` |
 | Instruction-conflict handling — structural | Canonical source-attribution and `WORKFLOW_CONFLICT` policy in `LOOP_ENGINEERING.md` plus adapter references | `tests/autonomy-policy.test.js`, `tests/workflow-compatibility.test.js` |
 | Autonomous-mode precedence — structural | Autonomous/interactive mode contract and harness exclusion metadata | `tests/workflow-compatibility.test.js`, `tests/conformance-scenarios.test.js` |
 | Pre-contract autonomy — cross-agent live robustness | Prior third blind-run result, `conformance/runs/2026-08-13-codex-fourth-live.md`, preserved fifth-run report `conformance/runs/2026-08-13-codex-fifth-live.md`, and the exact blind request | `tests/conformance-scenarios.test.js`; sixth run is not started until mandatory approval is excluded |

package/README.md

@@ -142,7 +142,9 @@ ForgeLoop can consume host-provided advisory context through the Integration
 API. Providers are lazy and opt-in, and ForgeLoop does not persist their
 results. Provider output is never lifecycle state, evidence, authority,
 completion truth, or next-action authority, and it is never executable as a
-protocol command. See [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md).
+protocol command. The optional Ripwire adapter follows the same boundary; see
+[`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) and
+[`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md).
 
 ### Optional task boundaries and differential verification
 
@@ -462,6 +464,19 @@ validator-backed completion. Drift reopens verification, and migration keeps
 modified or unmanaged files for review. The terminal result is one of
 `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or `INVALID`.
 
+Before execution, profile selection reads structured obligations and explicit
+risks; exclusion constraints are not required actions. After a blocked
+preflight and contract revision, `next` may guide a checkpoint refresh through
+`clear-state` and a fresh preflight. This path requires a valid pre-execution
+ledger and routing bound to the revised contract. Execution transactions bind
+the physical project and task; a matching task ID in another project cannot
+reuse them. See [recovery guidance](./docs/TROUBLESHOOTING.md#revised-contract-after-a-blocked-preflight).
+
+CI audits each supplied task receipt explicitly. With no receipt it reports
+`NOT_VERIFIED`; green repository tests alone do not establish lifecycle
+completion or attestation. For contributor checks and safe payload retention,
+see [CONTRIBUTING.md](./CONTRIBUTING.md#focused-verification-and-maintenance).
+
 ## Protocol compatibility
 
 The npm package version is independent of protocol version. The current
@@ -492,11 +507,10 @@ JSON is size/depth limited; manifests, schemas, receipts, and secret-like
 values are checked; and install-capable verification requires trusted host
 authority. See [`THREAT_MODEL.md`](./THREAT_MODEL.md) for the full inventory.
 
-Development tooling is intentionally separate from runtime dependencies. The
-repository policy allows only ESLint and c8 as development dependencies;
-`npm run dependency:policy` fails if runtime or unapproved dependencies
-appear. The documentation renderer is vendored and pinned under
-`vendor/archify/v2.15.0/` rather than installed as a package dependency.
+Development tooling stays separate from runtime dependencies. The policy allows
+c8, ESLint, TypeScript, and YAML as development dependencies;
+`npm run dependency:policy` rejects runtime or unapproved dependencies. Archify
+is vendored at `vendor/archify/v2.15.0/` rather than installed as a package.
 
 To report vulnerabilities or contribute changes, see
 [`SECURITY.md`](./SECURITY.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md).
@@ -542,8 +556,8 @@ through `init`, `update`, or `doctor`.
 ## Release and maintenance
 
 The release workflow uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers)
-through GitHub Actions OIDC. A `vX.Y.Z` tag must match `package.json`; after
-publishing, verify the immutable release identity:
+through GitHub Actions OIDC. A merged `vX.Y.Z` tag must match `package.json`;
+after publishing, verify the immutable release identity:
 
 ```bash
 RELEASE_COMMIT="$(git rev-list -n1 vX.Y.Z)"

package/docs/ADVISORY_CONTEXT.md

@@ -172,3 +172,27 @@ The public boundary reports these stable codes:
 
 The host owns whether and when to display or use advisory context. ForgeLoop
 owns only the bounded normalization and trust-role projection.
+
+## Ripwire adapter
+
+ForgeLoop includes an optional host-injected adapter for the [Ripwire](https://github.com/redhat-et/ripwire)
+ranked source map. The adapter is deliberately outside the default runtime:
+the host must provide an absolute executable path and an exact expected
+version, register the returned provider under the `ripwire` key, and invoke
+`recallAdvisoryContext` explicitly. Creating the provider performs no discovery,
+network access, process start, or lifecycle write.
+
+The adapter runs Ripwire's qualified `--for=<query> --signatures-only --json
+--no-cache --exclude=.forgeloop` form with `shell: false`, closes standard
+input, bounds stdout to 1 MiB and stderr to 64 KiB, and applies the caller's
+existing advisory deadline. It validates the version immediately before the
+query, rejects malformed JSON and unsafe paths, and never copies raw stderr
+into an error message. Ripwire's graph is approximate, so the first returned
+item is a bounded status card that preserves cap, omission, ambiguity,
+unindexed-content, and unknown-completeness warnings after core normalization.
+
+See [RIPWIRE_ADAPTER.md](RIPWIRE_ADAPTER.md) for registration, tests, the
+opt-in real-binary smoke test, and the retrieval benchmark. A real binary and
+its exact version must be qualified by the host; ForgeLoop does not install or
+discover Ripwire and does not treat an unavailable smoke test as proof of
+interoperability.

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 1.10.0
+Package version: 1.10.2
 
 ## Canonical loop
 

package/docs/ARTIFACT_REFERENCE.md

@@ -1217,3 +1217,18 @@ For `BASELINE` artifacts and `PASS`/`FAIL` evaluations, `sourceMaterialFingerpri
 and stable `sourceObservation` are conditionally required; their before and after
 fingerprints must equal the bound source fingerprint. `BLOCKED` and
 `NOT_OBSERVED` artifacts may omit these observed-source fields.
+
+## Transaction diagnostics and retention
+
+`.forgeloop/.txn/<transactionId>/manifest.json` records transaction identity,
+status, staged writes, and recovery diagnostics. `COMMITTED`, `ROLLED_BACK`,
+and `ABORTED` are terminal; an aborted staging callback did not publish its
+staged writes. A successful recovery is not reported as incomplete on the next
+doctor inspection. The transaction lock still protects recovery from live
+writers.
+
+The repository maintenance command described in
+[CONTRIBUTING.md](../CONTRIBUTING.md#focused-verification-and-maintenance)
+compacts eligible stage/backup payloads only. It retains manifests and ledgers,
+so historical manifest enumeration remains linear. These diagnostics are not
+substitutes for a valid execution receipt or external-action reconciliation.

package/docs/CODE_ATTESTATION.md

@@ -139,3 +139,12 @@ distinguished from invalid attestations by the stable exit-code contract:
 
 See [`REVISION_PROVIDERS.md`](./REVISION_PROVIDERS.md) and
 [`SIGNING_PROVIDERS.md`](./SIGNING_PROVIDERS.md) for extension boundaries.
+
+## Receipt availability in repository CI
+
+The repository audit workflow checks supplied task receipts individually with
+an explicit task ID. A checkout without a receipt reports `NOT_VERIFIED`.
+That is absence of lifecycle evidence, not an attestation trust level; it does
+not mean `PROCESSED`, `VERIFIED`, or `ATTESTED`. CI does not fabricate a receipt
+from successful repository tests. Transaction payload compaction preserves
+the manifests and ledgers needed to inspect the original history.

package/docs/DOCUMENTATION_GUIDE.md

@@ -24,12 +24,12 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
 When updating documentation, always derive content from its authoritative source:
 
 ```text
-CLI syntax truth        -> CLI registry / parser (src/cli.js, src/core/cli-command-definitions.js, src/core/cli-metadata.js)
+CLI syntax truth        -> CLI registry / parser (src/cli.js, src/core/cli-command-definitions.js)
 Artifact shape truth    -> JSON schemas (schemas/*.schema.json, src/core/artifact-registry.js)
 Lifecycle truth         -> protocol / state machine (src/core/protocol.js)
 Reason-code truth       -> exported protocol constants (src/core/error-codes.js, src/core/protocol.js)
 Guide registry truth    -> canonical guide registry (src/config/guides.json)
-Package contents truth  -> package.json + package tests (tests/package.test.js)
+Package contents truth  -> package.json + docs/PACKAGE_CONTENTS.md + 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
@@ -119,7 +119,7 @@ conformance checks detect omissions.
 
 | Documentation Area | Canonical Machine Source | Conformance Validator |
 | --- | --- | --- |
-| **CLI commands & flags** | `CLI_COMMAND_METADATA` (`src/core/cli-metadata.js`) & `src/cli.js` | `scripts/validate_documentation_conformance.mjs` |
+| **CLI commands & flags** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) & `src/cli.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Artifact paths** | `ARTIFACT_REGISTRY` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Artifact fields & types** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
 | **Enums & consts** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
@@ -128,7 +128,7 @@ conformance checks detect omissions.
 | **Stable error codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `scripts/validate_documentation_conformance.mjs` |
 | **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` |
+| **Package-shipped docs and runtime** | `package.json` (`files`) + `docs/PACKAGE_CONTENTS.md` | `tests/package.test.js` + `scripts/package_smoke.mjs` |
 | **Architecture and trust diagrams** | `docs/diagrams/manifest.json` plus each typed workflow source | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
 
 ---

package/docs/EXECUTION_PROFILE_BENCHMARKS.md

@@ -421,3 +421,13 @@ The source policy is intentionally narrow: provider or host observations are
 accepted for benchmark claims, while actor-reported or absent telemetry stays
 non-comparable. This is an efficiency observation boundary, not verification
 evidence and not an external publication result.
+
+## Contract signals and exclusions
+
+Profile selection reads string and structured success/verification
+requirements, including nested requirements and explicit publication or
+production-readiness types. Constraints and stop conditions describe
+boundaries and are excluded from obligation scanning. For example, a
+constraint saying “No publication” does not create a publication requirement.
+An explicit route risk remains authoritative and can still raise the safety
+floor. Profiles classify work; they do not grant execution authority.

package/docs/MCP.md

@@ -135,7 +135,7 @@ forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
 
 | Component | Current contract |
 | --- | --- |
-| ForgeLoop core package | `>=1.5.0 <2` dependency range; current release `1.10.0` |
+| ForgeLoop core package | `>=1.5.0 <2` dependency range; current release `1.10.2` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |
@@ -187,3 +187,15 @@ list in [TROUBLESHOOTING](./TROUBLESHOOTING.md):
 
 Canonical ForgeLoop errors (e.g. `E_TASK_SCOPE_CONFLICT`,
 `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`) are always preserved verbatim.
+
+## Reproducible adapter verification
+
+The adapter commits its own lockfile and declares both server and test-client
+SDK versions. `npm run mcp:setup` installs that lock with lifecycle scripts
+disabled, then substitutes the locally packed core offline. Packed smoke uses
+the same dependency graph and substitutes both local tarballs using the system
+`tar` command. This replacement does not resolve registry metadata or require a
+warm npm cache; `npm ci` still retrieves the locked dependencies. Both paths
+verify resolved dependency versions and print lock/tarball SHA-256 identities.
+The adapter remains a separate package; these dependencies are not added to
+the ForgeLoop core runtime.

package/docs/PACKAGE_CONTENTS.md

@@ -0,0 +1,88 @@
+# 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 advisory-context and Ripwire adapter guides ship with the corresponding
+  public integration surface.
+  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;
+- the Ripwire retrieval benchmark runner, cases, and fixture corpus; those
+  maintainer-only files require a clean repository checkout and are not part of
+  the consumer adapter surface;
+- 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/RELEASE_CHECKLIST.md

@@ -11,8 +11,14 @@ preparation and verification checklist; it does not authorize publication.
 - [ ] `npm run release:identity` passes for the candidate version.
 - [ ] No release tag or registry version collision exists.
 - [ ] `npm pack --dry-run` contains the required scenario definitions but no
-      raw or aggregate benchmark results, tests, local state, or repository
-      metadata.
+      raw or aggregate benchmark results, Ripwire benchmark runner/cases/
+      fixtures, 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
 
@@ -62,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/RIPWIRE_ADAPTER.md

@@ -0,0 +1,189 @@
+# Ripwire advisory adapter
+
+This document explains the optional Ripwire integration shipped with
+ForgeLoop. It is an advisory context provider. It can help a host choose
+which source files to inspect, but it never controls ForgeLoop state, checks,
+receipts, commands, approvals, or completion.
+
+## When to use it
+
+Use the adapter when a host already has a qualified Ripwire executable and
+wants ranked source signatures for an explicit task query. Do not use it as a
+replacement for tests, code review, lifecycle evidence, or a sound call graph.
+Ripwire's resolver is approximate: same-file and same-directory edges are
+useful hints, while ambiguous or unresolved edges can be missing or wrong.
+
+ForgeLoop does not install Ripwire, search `PATH`, contact a server, create a
+cache, or persist a recall. The host owns executable selection and version
+qualification.
+
+## Registration
+
+Import the factory from the public integration entry point and register the
+returned provider under the exact `ripwire` key:
+
+```js
+import {
+  createForgeLoopContext,
+  createRipwireAdvisoryContextProvider,
+  recallAdvisoryContext,
+} from "@cassiomc1/forgeloop/integration";
+
+const ripwire = createRipwireAdvisoryContextProvider({
+  executablePath: "/absolute/path/to/ripwire",
+  expectedVersion: "0.3.8",
+});
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: { ripwire },
+});
+
+const context = await recallAdvisoryContext({
+  target: "/absolute/path/to/project",
+  taskId: "task-123",
+  providerName: "ripwire",
+  query: "stale handoff acceptance and repository fingerprint",
+  limit: 6,
+  runtimeContext,
+});
+```
+
+`executablePath` must be absolute. `expectedVersion` is an exact version token,
+not a range. Provider construction is inert. On every recall the adapter first
+runs `ripwire --version`; a mismatch fails with
+`E_ADVISORY_CONTEXT_PROVIDER_INVALID` before the query is attempted.
+
+## Process contract
+
+The adapter invokes one command with an argv array:
+
+```text
+<ripwire-path> <absolute-project-path> \
+  --for=<entire-query-string> --signatures-only --json --no-cache \
+  --exclude=.forgeloop
+```
+
+The query is one argument, so shell metacharacters cannot add arguments or
+commands. The child is started with `shell: false`, standard input is closed,
+and stdout/stderr are read concurrently. A single deadline covers the version
+probe and query. The default transport ceilings are 1 MiB for stdout and 64
+KiB for stderr. On timeout or overflow the child is terminated and the error
+uses a stable ForgeLoop code; raw output is not copied into the message.
+
+The `.forgeloop` exclusion keeps lifecycle files out of the advisory source
+surface. The adapter does not add other exclusion flags because every flag
+must be qualified against the selected Ripwire version.
+
+## JSON mapping
+
+Ripwire's `--for --json` response is expected to be an object containing a
+flat `sigs` array. Each known row is mapped as follows:
+
+| Ripwire field | ForgeLoop field | Rule |
+| --- | --- | --- |
+| `n` | `title` | Candidate symbol name. |
+| `sig` | `summary` | Signature text, bounded before core normalization. |
+| `p` + `l` | `sourceRef` | Repository-relative path and one-based line. |
+| `r`, `k` | summary annotation | Rank and ranking score remain descriptive text. |
+| numeric `confidence` in `[0, 1]` | `confidence` | Copied only when the upstream field is explicitly numeric and bounded. |
+| `at` | omitted | A run timestamp or revision is not needed for deterministic item identity. |
+
+PageRank, BM25, margin, and other ranking values are never converted into a
+probability. Unknown fields are discarded by the core allowlist. Candidate
+order is preserved, duplicates are removed by stable first occurrence, and
+items stop when the requested item or total-character budget is reached.
+
+The first item is always `Ripwire advisory status`. It states that the result
+is approximate and carries bounded disclosures such as `capped`, `sigs_total`,
+`sigs_shown`, `lens`, `ambiguous`, `unresolved`, `unindexed`, parse health, and
+`index_completeness=unknown`. If no symbol fits, the status item says so; an
+empty result never proves that the project has no impact.
+
+Source references are rejected when they are absolute outside the project,
+contain traversal segments, use an in-project symlink, or report an invalid
+line. The host must still inspect the referenced file and independently verify
+the proposed change.
+
+The status item is budget-aware. When candidates or diagnostic notices do not
+fit, it preserves a truthful completeness warning and says which candidate
+rows or text were omitted. The final item total is checked against the same
+character budget used by the core advisory normalizer.
+
+## Failure codes
+
+| Situation | Code |
+| --- | --- |
+| Missing or unqualified executable or unsafe target | `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` |
+| Nonzero process exit without a qualified meaning | `E_ADVISORY_CONTEXT_RESULT_INVALID` |
+| Expected version differs from `--version` output | `E_ADVISORY_CONTEXT_PROVIDER_INVALID` |
+| Invalid JSON or unsupported response shape | `E_ADVISORY_CONTEXT_RESULT_INVALID` |
+| Timeout | `E_ADVISORY_CONTEXT_TIMEOUT` |
+| Stdout/stderr or candidate ceiling exceeded | `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` |
+| Unsafe content or control character in selected context | `E_PORTABLE_CONTEXT_INVALID` |
+
+These failures affect the explicit recall operation only. They do not change a
+ForgeLoop task phase and do not write `.forgeloop` state.
+
+## Verification
+
+The deterministic fixture tests run without a Ripwire installation:
+
+```bash
+node --test \
+  tests/ripwire-advisory-process.test.js \
+  tests/ripwire-advisory-normalize.test.js \
+  tests/ripwire-advisory-provider.test.js
+```
+
+The real-binary smoke test is opt-in. Set both variables to a host-qualified
+binary and version, then run:
+
+```bash
+FORGELOOP_TEST_RIPWIRE_PATH=/absolute/path/to/ripwire \
+FORGELOOP_TEST_RIPWIRE_VERSION=0.3.8 \
+node --test tests/real-ripwire-advisory.test.js
+```
+
+Without those variables the test is skipped and interoperability remains
+`NOT_VERIFIED`. When it runs, it requires a candidate reference to the known
+fixture source and compares the complete fixture tree before and after recall,
+so a binary that mutates the project fails the test. The test does not install
+software or discover a binary.
+
+## Retrieval benchmark
+
+The retrieval benchmark is a repository-maintainer check. Its runner, cases,
+and fixture corpus are intentionally excluded from the core npm tarball; the
+published consumer surface is the adapter, its declarations, and this guide.
+Run it from a clean ForgeLoop checkout when a host-qualified Ripwire binary is
+available.
+
+`benchmarks/ripwire-context/cases.json` freezes six task-shaped queries,
+expected files, lexical baseline terms, and the ForgeLoop commit used for the
+comparison. Run the benchmark only against a clean checkout and an explicitly
+qualified binary:
+
+```bash
+node scripts/benchmark-ripwire-context.mjs \
+  --project /absolute/path/to/forgeloop \
+  --ripwire-path /absolute/path/to/ripwire \
+  --version 0.3.8 \
+  --cases benchmarks/ripwire-context/cases.json \
+  --runs 5 \
+  --json
+```
+
+The report includes per-case and per-run expected-file coverage, misses,
+irrelevant references, baseline bytes, normalized adapter bytes, transport
+bytes when observed, and median/min/max durations. A file seen in only one
+repetition is reported as observed across runs but does not count as a
+consistently found file. A missing binary, version, dirty checkout, or commit
+mismatch produces `NOT_VERIFIED`; it is never reported as a performance win.
+
+## Scope boundary
+
+The adapter is intentionally limited to source-map retrieval. It does not
+implement Ripwire's body packing, impact commands, cache management, server
+mode, automatic file reads, lifecycle transitions, evidence production, or
+publication. Those features require a separate contract and separate
+qualification work.