@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/docs/DOCUMENTATION_GUIDE.md

@@ -54,11 +54,30 @@ Documentation-impact questions for integration/MCP changes:
 - Did an adapter error code change?
 - Did an integration limit or resource list change?
 
-Anti-drift invariant: every `documentation-manifest.json` entry marked
-`packaged: true` is mechanically checked against the core npm tarball
-contents (`tests/package.test.js`).
-
-Canonical phase and transition inventories must be derived from `WORK_PHASES`
+Anti-drift invariant: every packaged Markdown or harness-adapter document in
+`package.json.files` is registered in `documentation-manifest.json`, and every
+`packaged: true` manifest entry is mechanically checked against the core npm
+tarball contents (`tests/package.test.js`). The review matrix records generated
+or handwritten origin, current or historical status, package inclusion, action,
+and canonical sources for every registered document.
+
+### Documentation retention and repository hygiene
+
+Use one canonical owner for each maintained concept. Generated documentation
+must name its source, generator, freshness check, and reason for being tracked.
+Historical audits, release evidence, and completed validation records belong
+under `docs/history/`; current operating instructions must not leave those
+records loose in the repository root. One-off plans and validation reports are
+either consolidated into a canonical document and deleted or moved to the
+history index with their current owner links.
+
+Repository and npm decisions are separate. GitHub may retain reproducible
+benchmarks, PoC evidence, source-bound diagram artifacts, vendored renderer
+sources, and historical records that consumers do not need. The npm package
+ships only intentional runtime, integration, legal, harness, and canonical user
+documentation surfaces. `npm run repository:hygiene` enforces explicit root,
+tracked-state, visual-ownership, benchmark-run-set, and scratch-output policy;
+it does not guess whether an arbitrary document is useful.
 and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
 enums when a generated or mechanically validated representation is available.
 
@@ -79,7 +98,8 @@ generated Markdown regions (<!-- BEGIN FORGELOOP GENERATED: ... -->)
     ↓
 semantic conformance checks (scripts/validate_documentation_conformance.mjs)
     ↓
-cross-platform CI (.github/workflows/docs-quality.yml)
+documentation validation (.github/workflows/docs.yml) and the PR aggregator
+(.github/workflows/pr-core.yml)
 ```
 
 ### Provenance Mapping Table
@@ -194,7 +214,7 @@ migration, or security-sensitive require `npm run docs:check` before merge.
 2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
 3. **Animated committed outputs**: Every active source uses `meta.animation: "trace"`. Each interactive HTML is the primary animated explorer, and each self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. Deterministic receipts are committed under `docs/assets/diagrams/`.
 4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
-5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The human-owned review at `docs/diagrams/reviews/` binds the current source and SVG hashes and is never generated or overwritten. Run `npm run docs:diagrams:check` before review.
+5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The review at `docs/diagrams/reviews/` binds the current source and SVG hashes as a review assertion and is never generated or overwritten; the checker does not independently authenticate the reviewer. Run `npm run docs:diagrams:check` before review.
 6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
 
 ForgeLoop governs five documentation-diagram categories: workflow,
@@ -212,14 +232,16 @@ README hero assets are branding/conceptual architecture illustrations. They are
 not the canonical protocol diagram. The typed Archify workflow under
 `docs/diagrams/` remains the canonical lifecycle architecture source, with
 generated outputs under `docs/assets/diagrams/`; the CLI-only persistent search
-transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`.
+transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`. The current
+repository-only assets are `docs/assets/forgeloop-architecture.svg` and
+`docs/assets/forgeloop-lifecycle-animated.svg`; neither is a package file.
 
 The README hero is intentionally GitHub-repository-only:
 
-- `README.md` may reference `docs/assets/eng_readme_forgeloop.png`; GitHub
-  renders it from the repository.
-- The hero PNG is excluded from the npm package (`package.json` `files`), and
-  `tests/package.test.js` asserts that exclusion so it cannot be silently
+- `README.md` references `docs/assets/forgeloop-architecture.svg` for the hero
+  and `docs/assets/forgeloop-lifecycle-animated.svg` for the looping overview;
+  both are repository-only and excluded from the npm package.
+- `tests/package.test.js` asserts those exclusions so they cannot be silently
   re-included.
 - The packaged README is therefore not self-contained for that relative hero
   path; do not claim otherwise.

package/docs/GETTING_STARTED.md

@@ -49,11 +49,61 @@ forgeloop next --task task-contact-form-001 --compact --json
 forgeloop task-show --task task-contact-form-001 --compact --json
 ```
 
+When the task shape is known but a full contract has not been written yet,
+use a bounded preset preview. Preview is read-only and records unresolved
+decisions instead of guessing project facts:
+
+```bash
+forgeloop task-create --task task-contact-form-001 \
+  --claim src/components --claim tests \
+  --preset feature --preview --json
+```
+
+After reviewing the proposed contract, repeat the command without
+`--preview` to create the namespace and persist the same validated contract.
+The supported presets are `documentation`, `bug`, `feature`, and `release`.
+The release preset retains an independently verified publication requirement;
+it does not publish or deploy anything.
+
+For a bounded explanation of a blocked or recovery-sensitive next action, opt
+in with `--explain`. The explanation is read-only and derived from canonical
+reason codes and artifact references:
+
+```bash
+forgeloop next --task task-contact-form-001 --explain --json
+```
+
 These commands do not bypass contracts, gates, verification, provenance,
 lifecycle phases, or validator-backed completion. Usage telemetry is optional,
 never estimated, and never verification evidence; `efficiency --task` compares
 only against a metadata-compatible local baseline.
 
+### Project-aware guide routing
+
+ForgeLoop selects specialist context from bounded structural evidence in the
+affected project scope. A parsed `pubspec.yaml` with
+`dependencies.flutter.sdk: flutter` selects `flutter`. A parsed SDK-style
+`*.csproj`, `*.fsproj`, or `*.vbproj` using the supported .NET SDK allowlist
+selects the single `dotnet` guide. Web/Razor/Blazor or
+`Microsoft.AspNetCore.App` evidence adds an ASP.NET Core routing reason, and a
+`Volo.Abp.*` package reference adds an ABP routing reason; neither overlay is a
+standalone guide ID, and each requires `dotnet` in project evidence.
+
+Bounded structural inspectors also recognize Go modules/workspaces, valid
+TypeScript configs, Composer/PHP projects, Java Maven/Gradle/Bazel roots,
+SwiftPM/Xcode/native Swift roots, and explicit C/C++ build/source evidence.
+Meaningful SQL migrations and schemas are scoped overlays. Build, compiler,
+package-manager, database, lockfile, generated, and vendor artifacts are not
+executed or promoted beyond their documented evidence contract.
+
+Mentions in prose, source snippets, Dockerfiles, lockfiles, package names,
+malformed manifests, and unrelated monorepo roots are insufficient. Mixed
+Flutter/.NET roots stay isolated. Shared MSBuild/NuGet files apply only to
+descendant confirmed .NET projects, and `.sln`/`.slnx` claims use exact
+membership. Discovery skips symlinks and is bounded; see
+[`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) for the exact allowlist, reason codes,
+and numeric limits.
+
 ---
 
 ## 2. Prerequisites
@@ -395,8 +445,17 @@ forgeloop complete --task auth-feature --json
 
 # Inspect active tasks
 forgeloop task-list --json
+
+# Filter and page the deterministic projection
+forgeloop task-list --phase EXECUTING --limit 20 --offset 0 --json
+forgeloop task-list --active --limit 20 --offset 20 --json
 ```
 
+Task discovery is exhaustive for ownership and conflict correctness. The
+`--phase` and `--active` options filter the presentation after validation;
+`--limit` and `--offset` page the sorted result and JSON includes `total` and
+`hasMore`. Listing is read-only and never removes ledger or recovery evidence.
+
 ---
 
 ## 6. What ForgeLoop Creates

package/docs/JEV_BENCHMARKS.md

@@ -0,0 +1,31 @@
+# Jev benchmark and calibration
+
+`npm run benchmark:jev` emits an offline deterministic baseline for model-route
+scenarios. It records the pinned engine/model, safety-floor projection, fallback
+status, Jev/cache/latency fields, context and tool dimensions, and unknown host
+telemetry. Zero counts mean that no provider request was made; `null` and
+`NOT_MEASURED` remain explicit when the host did not observe a value. It does
+not fabricate provider usage and does not authorize lifecycle, execution,
+pruning, or completion.
+
+Provider-backed calibration requires a live TypeSafe organization with credits;
+an unavailable provider is reported as unavailable rather than treated as a
+successful benchmark.
+
+`npm run benchmark:jev:live` runs bounded intake, route, and context requests
+through the pinned Jev provider and reports provider usage/latency only when the
+provider supplies it. It requires `TYPESAFE_API_KEY`, never prints that key,
+and is intentionally separate from the offline benchmark.
+
+An optional maintainer release check is available through
+`npm run jev:smoke` and `npm run benchmark:jev:live`. The current repository does
+not enforce either live command in CI or the release workflow, and the CLI does
+not bind either command to an exact candidate commit. Offline output, a missing
+credential, or a provider-unavailable result is never a substitute for live
+interoperability evidence.
+
+Dependency audit attribution for the current base and PR head is unchanged:
+one high-severity `js-yaml` advisory (`GHSA-2883-xcg3-v3hh`, CVSS 7.5, CWE-400
+and CWE-407) arrives transitively through `eslint` → `@eslint/eslintrc` →
+`js-yaml` 4.3.1. It is not introduced by the Jev dependency; the audit reports
+an available upgrade outside this correction's runtime dependency policy.

package/docs/MODEL_ROUTING.md

@@ -0,0 +1,37 @@
+# Model routing
+
+ForgeLoop exposes model routing as a bounded semantic-decision projection. It
+has `SEMANTIC_DECISION` authority only within the declared decision contract;
+it has no lifecycle, completion, evidence, ownership, installation, command, or
+publication authority. The deterministic policy establishes the safety floor:
+
+- `NONE` when no generation is required;
+- `STANDARD` for ordinary executable generation;
+- `PRIMARY` for security, architecture, migration, ambiguity, and other
+  high-risk signals.
+
+The deterministic floor currently emits `NONE`, `STANDARD`, or `PRIMARY`. The
+public vocabulary also includes `FAST`, which is available only as an advisory
+escalation and cannot lower the deterministic floor.
+
+The pinned Jev model (`jev-1.13.0`) may recommend an escalation or request an
+escalation when confidence is low. It can never lower the deterministic floor,
+select a vendor-specific model, execute a command, change lifecycle state,
+authorize ownership, or weaken verification requirements. ForgeLoop remains the
+authority for all lifecycle, evidence, safety, and completion decisions.
+
+For route execution, the same boundary applies to guide relevance: Jev can
+reorder or remove a selected non-mandatory guide only with sufficient
+confidence. Mandatory safety protection is derived from the canonical
+deterministic route reasons the router already produced (auth surface and the
+trust-boundary risks untrusted-input, personal-data, secrets, external-service,
+publication), so a `security` guide selected by `external-service` risk cannot be
+removed. Mandatory safety guides are retained and low-confidence removal
+recommendations are retained rather than treated as authority. The resulting
+guide set and profile are persisted in the route artifact, so the semantic
+recommendation materially affects routing without becoming lifecycle authority.
+
+The live Jev provider is not an authority substitute. Semantic-required
+model-routing operations consume a fresh persisted `MODEL_ROUTE` decision and
+fail closed when it is unavailable or stale; offline inspection may still
+project deterministic policy without making a network request.

package/docs/OPENSRC_ADAPTER.md

@@ -0,0 +1,241 @@
+# OpenSrc Advisory Context Adapter
+
+## Status
+
+Optional, host-injected, advisory-only. OpenSrc is an external
+host-provisioned executable ([vercel-labs/opensrc](https://github.com/vercel-labs/opensrc),
+Apache-2.0); ForgeLoop never installs, discovers, or invokes it automatically.
+
+## Purpose
+
+Give a trusted host a bounded way to recall external package/repository
+source-code snippets (npm, PyPI, crates.io, GitHub, GitLab, Bitbucket) as
+ForgeLoop advisory context through the existing `advisoryContextProviders`
+Integration API boundary.
+
+## Architecture
+
+```text
+host / coding harness
+        ↓
+createOpenSrcAdvisoryContextProvider(...)
+        ↓
+createForgeLoopContext({ advisoryContextProviders: { opensrc } })
+        ↓
+recallAdvisoryContext(...)
+        ↓
+<absolute-opensrc> --version (qualified every recall)
+        ↓
+<absolute-opensrc> path <source> --cwd <projectRoot> (one source per call)
+        ↓
+canonical realpath containment inside OPENSRC_HOME
+        ↓
+bounded deterministic Node.js search (ForgeLoop-owned)
+        ↓
+normalized advisory items
+        ↓
+NON_EVIDENCE_ADVISORY_CONTEXT
+```
+
+OpenSrc owns source acquisition, version-aware resolution, and its own cache.
+ForgeLoop owns snippet selection, normalization, and the advisory trust
+boundary. No `rg`, `grep`, embeddings, or network search are used by ForgeLoop.
+
+## Prerequisites
+
+- An OpenSrc executable provisioned by the host (ForgeLoop does not install it).
+- A host-qualified exact expected version (for example `0.7.3`).
+- A dedicated absolute cache root outside the project, passed as `OPENSRC_HOME`.
+- An explicit allowlist of source specs (at most 8).
+
+## Host Configuration
+
+```javascript
+import {
+  createForgeLoopContext,
+  createOpenSrcAdvisoryContextProvider,
+  recallAdvisoryContext,
+} from "@cassiomc1/forgeloop/integration";
+
+const opensrc = createOpenSrcAdvisoryContextProvider({
+  executablePath: "/absolute/path/to/opensrc",
+  expectedVersion: "<host-qualified-version>",
+  cacheRoot: "/absolute/path/to/opensrc-cache",
+  sources: ["zod", "vercel/next.js"],
+});
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    opensrc,
+  },
+});
+
+const context = await recallAdvisoryContext({
+  target: "/absolute/project",
+  taskId: "task-001",
+  providerName: "opensrc",
+  query: "parse error handling",
+  runtimeContext,
+});
+```
+
+Construction is inert: it validates configuration only and never spawns,
+reads source, touches the network, populates the cache, or mutates ForgeLoop
+state.
+
+## Executable Qualification
+
+Before source resolution on every recall, the adapter runs
+`<absolute-opensrc> --version` with `shell: false`, bounded output, and a
+shared deadline, then requires `actualVersion === expectedVersion` exactly.
+No semver ranges and no newer-version tolerance. Mismatch fails closed.
+
+## Source Allowlist
+
+Only configured `sources` entries are resolved, one per `opensrc path`
+invocation. Specs must be non-empty, bounded (256 chars), free of control or
+whitespace characters, must not begin with `-`, and must not contain shell
+metacharacters. Documented forms include bare npm names (with `@scope/` and
+`@version` pins), `pypi:`, `crates:` (plus `pip:`, `python:`, `cargo:`,
+`rust:` aliases), `owner/repo`, URLs, and `gitlab:` / `bitbucket:` specs.
+Automatic dependency enumeration is out of scope.
+
+## Cache Behavior
+
+`OPENSRC_HOME` is set to the configured `cacheRoot` for every OpenSrc child
+process. The cache root and the project root must be fully disjoint: neither
+may equal or contain the other, and the cache must not sit inside
+`.forgeloop`. Each relationship is checked both lexically and canonically
+(realpath), so symlinked prefixes cannot hide an overlap.
+Each printed path must canonicalize inside the cache root, exist, be a
+directory, and survive symlink-escape checks before any search runs.
+
+## Network Behavior
+
+`opensrc path` may contact registries or remotes and shallow-clone source on
+cache miss; later recalls may reuse the OpenSrc cache. This recall path is
+protocol-state side-effect-free: ForgeLoop persists no advisory result,
+writes no lifecycle state, and never auto-recalls. OpenSrc itself persists
+cache data under `OPENSRC_HOME`; that is upstream behavior, not ForgeLoop
+state.
+
+## Recall Example
+
+See Host Configuration. Only `--version` and `path` are ever invoked; `fetch`,
+`clean`, `remove`, and `rm` are never called by this adapter.
+
+## Result Shape
+
+```javascript
+{
+  title: "zod — src/types.ts",
+  summary: "L120-L126 | <bounded single-line snippet>",
+  sourceRef: "opensrc:zod:src/types.ts#L120-L126"
+}
+```
+
+Summaries are flattened to one portable line because the core advisory
+contract rejects control characters. Absolute cache paths, home directories,
+stderr, environment, credentials, and cache metadata are never emitted. The
+core service then applies `authority: ADVISORY`, `evidenceAuthority: NONE`,
+`actionability: NON_EXECUTABLE`, `trustRole: NON_EVIDENCE_ADVISORY_CONTEXT`,
+and `persisted: false`, plus item fingerprints and deep freezing.
+
+## Trust Boundary
+
+Snippets are inert source text. They satisfy no verification requirement,
+terminal requirement, gate, receipt, attestation, or run-check provenance.
+Source content is never executed, even when it contains instruction-like
+text. Provider output never advances phases, selects next actions, releases
+claims, or authorizes durable actions.
+
+## Security
+
+Threats and mitigations are tracked in `THREAT_MODEL.md` (OpenSrc rows):
+binary substitution and version drift (exact lazy qualification), malicious
+stdout paths and cache/symlink escapes (realpath containment), prompt
+injection in source (inert bounded text, non-executable trust role),
+credential leakage (no raw stderr/env/absolute-path emission), unbounded
+trees and binary ingestion (sorted traversal, size/count/byte budgets, binary
+skip), network/cache side effects (explicit host-owned `OPENSRC_HOME`,
+documented fetch-on-miss), private-repository credentials (host-owned env,
+never persisted or logged), timeouts and output overflow (shared deadline,
+64 KiB ceilings, SIGTERM/SIGKILL escalation).
+
+## Limits
+
+- Sources: at most 8 configured; one `path` call each.
+- Files read per source: 2,000; examined entries per source: 5,000
+  (skipped, oversized, and binary entries count toward traversal, never
+  bypass it).
+- Per-file: 256 KiB; total reads: 8 MiB per advisory recall across all
+  configured sources through one shared budget.
+- Matches per source: 32; snippet window: 7 lines.
+- Process stdout/stderr: 64 KiB each; kill grace: 250 ms.
+- One shared recall deadline spans version qualification, path resolution,
+  traversal, reads, matching, and normalization.
+- Ranking: exact full-query match, then token overlap, then source order,
+  relative path, and line number. Repeated runs over unchanged fixtures are
+  byte-identical, including identical stopping points under budget pressure.
+
+## Private Repositories
+
+Private sources work only through host-owned configuration (environment,
+authenticated OpenSrc cache). ForgeLoop never discovers, persists, logs, or
+returns credentials; errors never echo secret-bearing values.
+
+## Credentials Ownership
+
+Credentials belong to the host. They travel only through host-supplied process
+configuration, never through ForgeLoop artifacts, and never into advisory
+output.
+
+## No Auto-Install
+
+ForgeLoop never runs package installs, `npx`, `curl | sh`, or equivalents for
+OpenSrc. An unavailable binary maps to the standard advisory-provider
+unavailable semantics; the host provisions OpenSrc explicitly.
+
+## No PATH Discovery
+
+The executable must be absolute. `which`, `where`, `command -v`, and PATH
+resolution are never used.
+
+## No Evidence Authority
+
+See Trust Boundary. Behavioral claims still require canonical ForgeLoop
+verification with ForgeLoop-owned provenance.
+
+## No Lifecycle Authority
+
+See Trust Boundary. Advisory recall is never triggered by `next`,
+`preflight`, verification, `complete`, task creation, task discovery, or
+Agent Skill loading.
+
+## Troubleshooting
+
+| Symptom | Meaning | Action |
+| --- | --- | --- |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` on recall | Bad config, version mismatch, cache inside project, or malformed version output | Check absolute paths, exact version, `OPENSRC_HOME` placement |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | Missing binary or spawn failure | Provision the host executable; ForgeLoop will not install it |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | Empty/multi-line/relative/outside-cache path, non-directory, or bad exit | Inspect host cache and source spec |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Shared deadline expired | Retry with a larger recall `timeoutMs` within core ceilings |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | 64 KiB process ceiling or item budget exceeded | Narrow sources or query |
+
+## Package Behavior
+
+`src/adapters/opensrc/**`, this guide, and the integration declarations ship
+in the core npm tarball. No OpenSrc binary, cache, fixture, credential, or
+source snapshot ships. No new runtime dependency and no new package subpath
+are added; `providerExtensions.publicRegistryApi` and
+`providerExtensions.packageSubpathExported` remain false.
+
+## Compatibility
+
+- Protocol v1, schema v1, Integration API v1 unchanged.
+- `advisoryContextProviders` v1 and `providerExtensions` v1 unchanged; the
+  `ADVISORY_CONTEXT` provider kind covers this adapter.
+- Requires Node.js 20+.
+- Upstream behaviors referenced: `opensrc path <source> [--cwd]`,
+  `OPENSRC_HOME` override, fetch-on-miss, `opensrc 0.7.3` observed at
+  authoring time (never hardcoded into behavior).

package/docs/PACKAGE_CONTENTS.md

@@ -11,11 +11,27 @@ part of the consumer tarball.
 
 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.
+declaration file. The package has the approved exact `@typesafe-ai/sdk`
+dependency for the pinned semantic decision plane and `smol-toml` for bounded
+Cargo manifest parsing. It requires Node.js 20 or newer.
 
 ## Included files
 
+The public package includes the Jev decision-plane documentation and bounded
+diagnostic scripts:
+
+- `docs/JEV_BENCHMARKS.md`
+- `docs/MODEL_ROUTING.md`
+- `docs/SEMANTIC_DECISION_PLANE.md`
+- `docs/TEST_INTELLIGENCE.md`
+- `docs/TEST_PRUNING.md`
+- `scripts/jev-smoke.mjs`
+- `scripts/benchmark-jev.mjs`
+- `scripts/benchmark-test-intelligence.mjs`
+- `schemas/context-plan.schema.json`
+- `schemas/semantic-decision.schema.json`
+- `schemas/test-utility.schema.json`
+
 The published tarball includes the following consumer-facing groups:
 
 - **Runtime and protocol:** every maintained JavaScript module under `src/`,
@@ -28,10 +44,16 @@ The published tarball includes the following consumer-facing groups:
   `src/repository-index/tgrep-manifest.json`; native engine binaries are
   provisioned outside the npm tarball.
 - **Specialist guidance:** every registered consumer guide under `ENG/`,
-  including `ENG/flutter-development-eng.md`, ships with the guide registry
-  and is resolved from a package-local path. The Flutter specialist is
-  selected only for an affected root with the structural SDK dependency
-  signal; the package does not install or invoke Flutter tooling.
+  including `ENG/flutter-development-eng.md`,
+  `ENG/dotnet-aspnetcore-development-eng.md`,
+  `ENG/nodejs-backend-development-eng.md`,
+  `ENG/rust-development-eng.md`, and the C, C++, Java, SQL, Go, TypeScript,
+  PHP, and Swift specialists, ships with the guide registry and is resolved
+  from package-local paths. Specialists are selected only from their bounded
+  structural primary evidence; SQL remains a scoped host-project overlay.
+  ASP.NET Core and ABP are conditional routing overlays on the `dotnet` guide,
+  not additional package guides. The package does not install or invoke
+  framework, compiler, build, package-manager, or database tooling.
 - **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
@@ -44,9 +66,19 @@ The published tarball includes the following consumer-facing groups:
   generated local repositories and measurements are not.
 - **User documentation:** the getting-started, integration, CLI, artifact,
   Repository Index, Persistent Search Transport, troubleshooting, release,
-  package-boundary, and related reference pages.
-  The advisory-context and Ripwire adapter guides ship with the corresponding
-  public integration surface.
+  package-boundary, and related reference pages, together with the
+  machine-readable documentation and protocol indexes and `CONTRIBUTING.md`.
+   The advisory-context, Ripwire, OpenSrc, Agent Browser, and Audit UX guides ship with
+   the corresponding public integration surface.
+   Provider architecture, provider reference, and Security Review provider
+   documentation are also packaged.
+   The generated portable ForgeLoop Agent Skill and `docs/AGENT_SKILL.md` are
+   packaged as instruction/documentation content, not runtime authority.
+  Provider implementation modules ship under `src/`, but packaged source file
+  does not mean a supported public import path; the generic `./providers`
+  subpath remains unexported.
+  The lifecycle recovery surface includes the explicit `task-abandon` command;
+  it releases validated claims without asserting completion or publication.
   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.
@@ -59,6 +91,8 @@ The published tarball includes the following consumer-facing groups:
 The tarball intentionally omits repository-only material:
 
 - tests, conformance fixtures, coverage output, and secret-scanning helpers;
+  Harness-specific Agent Skill installation directories and Skill caches are
+  not packaged.
 - local `.forgeloop` state, task ledgers, locks, transactions, and execution
   receipts (the `.forgeloop/forgeloop.gitignore` template is the sole
   exception);
@@ -69,16 +103,21 @@ The tarball intentionally omits repository-only material:
   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 repository-only README hero assets
+  `docs/assets/forgeloop-architecture.svg` and
+  `docs/assets/forgeloop-lifecycle-animated.svg`. They are referenced by the
+  repository README and are intentionally outside the core tarball.
+- the execution PoC, its audit, and its evidence package. Packaged README and
+  index links to this repository-only material use GitHub URLs so they remain
+  truthful for npm consumers.
 
-The package test checks both required paths and these exclusion classes. It
+The package test checks all registered guide 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.
+historical plans, and source trees may intentionally resolve only in the full
+repository and are not package dependencies. The canonical documentation and
+protocol indexes are included in the tarball.
 
 ## Verification and publication
 
@@ -91,10 +130,12 @@ 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 package-boundary tests also assert
-that every registered guide path, including the Flutter specialist, is
-present in the candidate. The tag-triggered publication workflow
+exercises the CLI, public Integration API, initialization, schemas, and the
+Structural Quality documentation's packaged diagram references. The
+package-boundary tests also assert
+that every registered guide path, including all language specialists, is
+present in the candidate. 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