@cassiomc1/forgeloop 1.10.1 → 1.10.2

package/DOCS_INDEX.md

@@ -32,6 +32,7 @@ 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 |
@@ -80,6 +81,7 @@ is historical evidence and is not part of the published core package.
 | **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) |
@@ -140,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/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
 
@@ -505,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).
@@ -555,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.1
+Package version: 1.10.2
 
 ## Canonical loop
 

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.1` |
+| 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 |

package/docs/PACKAGE_CONTENTS.md

@@ -34,6 +34,8 @@ The published tarball includes the following consumer-facing groups:
   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.
@@ -51,6 +53,9 @@ The tarball intentionally omits repository-only material:
   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

package/docs/RELEASE_CHECKLIST.md

@@ -11,8 +11,8 @@ 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.

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.

package/docs/diagrams/README.md

@@ -39,6 +39,15 @@ dark presentation so it remains legible in repository previews; the adjacent tex
 [`README.md`](../../README.md#architecture-flow) carries the same lifecycle
 semantics for text-only readers.
 
+Advisory context, including the optional Ripwire adapter, is intentionally not
+drawn as a lifecycle node or transition. It is a host-injected, explicit,
+non-evidence input that can guide inspection while remaining outside state,
+authority, verification, completion, and next-action decisions. Its boundary
+is documented in [`ADVISORY_CONTEXT.md`](../ADVISORY_CONTEXT.md) and
+[`RIPWIRE_ADAPTER.md`](../RIPWIRE_ADAPTER.md); keeping it out of these P0
+visuals prevents an optional side channel from being mistaken for protocol
+control flow.
+
 Archify is vendored at `vendor/archify/v2.15.0/archify` under its MIT license.
 The exact source commit and cryptographic vendor-tree hash are recorded in
 `vendor/archify/v2.15.0/PIN.json`; generated-file hashes are recorded in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.10.1",
+  "version": "1.10.2",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -52,6 +52,7 @@
     "docs/GETTING_STARTED.md",
     "docs/CROSS_HARNESS_CONTINUITY.md",
     "docs/ADVISORY_CONTEXT.md",
+    "docs/RIPWIRE_ADAPTER.md",
     "docs/CLI_REFERENCE.md",
     "docs/ARTIFACT_REFERENCE.md",
     "docs/TROUBLESHOOTING.md",