@weftlet/toolkit 0.4.0 → 0.6.0

package/docs/RELEASE-1.0-PLAN.md

@@ -1,15 +1,26 @@
 # Consumer hardening and the 1.0 release plan
 
-Status: maintainer-directed work; release checkpoint on 2026-10-26 after verified 0.3.0 publication.
-**New adoption blocker: T08, deterministic physical-file kind conflicts.** This takes release
-priority over the remaining planned increments; T04 was completed first as requested.
-The report concerned `@weftlet/toolkit@0.2.0`. **T01's upstream patch shipped in 0.2.1**;
-genuine consumer acceptance remains pending. T02 and T05's focused cold-validation optimization
-shipped in 0.3.0. T03 and T04 are implemented in development source after that release. Broader T05
-follow-ups and T06 and T07 remain open. These tasks improve setup, reuse, diagnostics and document coverage
-without expanding the consumer's migration. An official 1.0
-follows this work and genuine consumer acceptance, with its exact release scope reviewed when
-the evidence is available.
+Status: maintainer-directed work; release checkpoint on 2026-10-27 after verified 0.5.0 publication.
+**T08's upstream deterministic physical-file fix has shipped; the maintainer reports the consumer
+updated and working on 2026-10-27. Detailed full hydration/repeat evidence remains pending.** T04 was completed before
+the T08 fix as requested.
+
+**T09 shipped in 0.5.0:** the configuration accepts `semantic.timeoutMs: 600000`,
+alongside T05a identity preflight and validation phase timing. The two-minute default is unchanged.
+The consumer's approved ten-minute retry has not run; that outcome remains separate acceptance.
+
+The original report concerned `@weftlet/toolkit@0.2.0`. T01's upstream document-identity patch
+shipped in 0.2.1; T02 and T05's focused cold-validation optimization shipped in 0.3.0.
+T03 operational cache reuse, T04 semantic failure diagnostics and T08's public core file factory
+shipped in 0.4.0. T09 and T05a shipped in 0.5.0. T06 documentation consistency is implemented
+for the next release. T07a prospective coverage is implemented separately from hydration;
+T07b classification and deterministic document evidence merged in PR 42 after local/hosted checks
+and independent review. T07c hydration/cache integration merged in PR 44 with local and hosted checks passed;
+T05's remaining engineering evaluation is recorded in
+[ADR 027](ADR-027-validation-closeout.md), retaining full direct validation after measurements.
+Complete source/release checks, publish a reviewed minor candidate, validate it in TradePilot,
+then review and publish official 1.0. These
+release/consumer gates are separate from the engineering count; none is already accepted.
 
 This is the near-term release task list. The [Weftlet 2.0 product plan](WEFTLET-2.0-PLAN.md)
 remains a separate future direction for generation, approvals, a companion website and hosted
@@ -36,21 +47,58 @@ integration. Consumer acceptance is reported separately from upstream determinis
 
 | ID | Task | Priority/status | Dependencies and release boundary |
 | --- | --- | --- | --- |
-| **T08** | Canonical physical-file kinds and public adapter factory | **Merged; local and hosted Ubuntu/Windows checks passed; release pending** | Neutral contract consumers conflict with test Evidence; consumer framework migration remains separately required |
+| **T10** | Correct implementation coverage for returned code relationships | **Merged after T07a; local/hosted checks passed; publication pending** | Separate evidence counts from display groups; preserve facts, authority, ranking and saved snapshots; scope gaps to returned page |
+| **T09** | Accept the approved ten-minute extraction timeout | **Shipped in 0.5.0; consumer ten-minute retry unrun** | Raise only the config ceiling to 600000; preserve defaults/cache/retry behavior; consumer retry has not run |
+| **T08** | Canonical physical-file kinds and public adapter factory | **Shipped in 0.4.0; consumer reported working; detailed acceptance pending** | Public core factory and neutral producers agree; record consumer commit, adapter tests and full hydration/repeat evidence |
 | **T01** | Coherent repository-document identity and kind | **Upstream patch shipped in 0.2.1; consumer acceptance pending** | SHACL and assertions preserved; genuine consumer re-run is still required |
 | **T02** | No-model hydration/setup preview | Shipped in 0.3.0 | Shared selection/cache inspection, human/JSON plans; extend with T07 traversal coverage |
-| **T03** | Artifact reuse across operational configuration changes | Merged; local and hosted Ubuntu/Windows checks passed; unreleased | Built-in Codex user artifacts share five operational changes; custom providers remain conservative; exact legacy recovery without model calls |
-| **T04** | Actionable, privacy-safe timeout diagnostics | Merged; local and hosted Ubuntu/Windows checks passed; unreleased | Safe source IDs, settled counts, failure classification and T02/T03 recovery; no extraction/cache identity change |
-| **T05** | Early identity checks and validation progress/profiling | **Cold-validation fix shipped in 0.3.0; consumer acceptance pending** | Full validation preserved; early checks, detailed progress and validation reuse remain open |
-| **T06** | Packaged release-documentation consistency | Open; README version pins removed in 0.2.1 | Automated archive/version consistency check remains to be implemented |
-| **T07** | Coverage-aware traversal from SOT/roadmap entry points | Planned bounded feature work | Use canonical identity from T01, preview from T02 and incremental reuse from T03; split selection/classification/extraction changes |
-
-T02 and the focused T05 fix passed local publication checks and hosted Ubuntu/Windows checks,
-then shipped in [0.3.0](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.3.0).
-Registry archives match the independently reviewed export; source commit, provenance and release
-tags are recorded in [validation](VALIDATION.md). T03, T04, T06 and T07 remain independently
-useful increments, separate from the optional platform work. A genuine consumer hydration and
-repeat against the current release remain required; upstream fixtures do not establish that result.
+| **T03** | Artifact reuse across operational configuration changes | Shipped in 0.4.0 | Built-in Codex user artifacts share five operational changes; custom providers remain conservative; exact legacy recovery without model calls |
+| **T04** | Actionable, privacy-safe timeout diagnostics | Shipped in 0.4.0 | Safe source IDs, settled counts, failure classification and T02/T03 recovery; no extraction/cache identity change |
+| **T05** | Early identity checks and validation progress/profiling | **Cold fix shipped in 0.3.0; T05a in 0.5.0; engineering closeout evaluated in ADR 027** | Cold/repeat/edits, worker, reuse, incremental and Rust evaluated; retain full direct validation; private consumer acceptance required |
+| **T06** | Packaged release-documentation consistency | **Implemented after 0.5.0; publication pending** | Generated current sections, checked actual tarballs, historical records preserved, fresh documented installation commands |
+| **T07** | Coverage-aware traversal from SOT/roadmap entry points | **T07a merged; T07b merged with local/hosted checks and review passed; T07c merged with local/hosted checks passed** | Committed closure, source roles/ownership, validation separation and draft invalidation implemented; npm publication pending |
+
+T02 and the focused T05 fix shipped in 0.3.0; T03, T04 and T08 shipped in
+[0.4.0](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.4.0), following
+local/hosted checks, independent archive review and fresh packed/public-registry installation.
+T09 timeout support and T05a identity preflight/phase timing shipped in
+[0.5.0](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.5.0).
+Source, registry integrity, provenance and release tags are recorded in [validation](VALIDATION.md).
+T05 closeout measurements and decisions are recorded in ADR 027; T06 and T07 are implemented for the next candidate.
+The consumer must migrate its framework adapter to the public core factory, then complete full
+hydration and repeat reuse; upstream fixtures do not establish that result.
+
+## T10 — Correct implementation coverage reporting
+
+The consumer reports code relationships accompanied by zero implementation coverage. Actual public
+contract-extractor and SCIP reproductions confirm that exclusive display-group counts caused the
+false gap. [ADR 024](ADR-024-implementation-coverage.md) separates coverage from presentation,
+retains evidence authority and scopes absence to the returned page. Existing snapshots can be queried
+with the fix without hydration or model work. The exact consumer package/output was requested;
+the public reproduction does not claim a completed private consumer acceptance run.
+
+The fix merged in [PR 40](https://github.com/jchewitt/weftlet/pull/40), with local publication checks
+and hosted Ubuntu/native Windows validation. Exact evidence and release status are recorded in
+[validation](VALIDATION.md). T05 performance/validation closeout
+remains separate; this reporting correction does not activate document traversal in hydration.
+
+## T09 — Accept the approved ten-minute extraction timeout
+
+Shipped in 0.5.0: `semantic.timeoutMs` accepts integers from 1 through 600000.
+The default remains 120000; retry policy, cancellation,
+authentication/discovery bounds and compatible artifact identities are unchanged. This is a
+per-attempt Codex limit or whole-module-execution limit, not an overall hydration or CI timeout.
+
+For recovery, upgrade both `@weftlet/core` and `@weftlet/toolkit` to 0.5.0,
+set `semantic.timeoutMs: 600000`, and run `hydrate --plan` with the same committed ref and scope
+as the interrupted run. Then rerun ordinary hydration, preserving compatible artifacts and
+avoiding forced re-extraction. Follow [provider limits and reuse](PROVIDERS.md#limits-and-reuse).
+
+Boundary, provider propagation, cancellation, cache reuse and packed/public-registry consumer checks passed;
+release evidence is in [validation](VALIDATION.md). The consumer's approved ten-minute retry
+has **not run**. No ten-minute wall-clock execution, paid/model call or private acceptance is
+claimed by these deterministic upstream checks. T06/T07 are now implemented with publication
+pending; T05 engineering evaluation is recorded separately in ADR 027.
 
 ## T08 — Resolve deterministic physical-file kind conflicts
 
@@ -64,12 +112,12 @@ routes physical-file producers through one policy, preserves strict SHACL/proven
 and distinguishes historical graph versions from current validation. Public tests include real
 SCIP and actual extractor composition, plus negative overlay validation without routing.
 
-Release requires local publication checks, hosted Ubuntu/Windows checks, reviewed archives and
-fresh installed-package verification. Consumer acceptance then requires the published packages
-plus its own framework adapter migration and composed Prisma/DI/decorator spec/test regressions,
-followed by full hydration and repeat reuse. Neither an upstream-only release nor a local-only
-adapter patch closes both ownership boundaries. Do not rewrite semantic caches or force model
-work to work around the proven deterministic defect.
+The 0.4.0 release passed local publication checks, hosted Ubuntu/Windows checks, independent archive
+review and fresh packed/public-registry installation. Consumer acceptance still requires the
+published packages plus its own framework adapter migration and composed Prisma/DI/decorator
+spec/test regressions, followed by full hydration and repeat reuse.
+Neither an upstream-only release nor a local-only adapter patch closes both ownership boundaries.
+Do not rewrite semantic caches or force model work to work around the proven deterministic defect.
 
 ## T01 — Resolve repository-document identity conflicts
 
@@ -110,7 +158,9 @@ Upstream completion evidence:
   [validation record](VALIDATION.md) for commits, checks and result boundaries.
 
 The private consumer has not yet supplied a successful full hydration/repeat with the identity
-patch. Use the current 0.3.0 release, which also includes the cold-validation improvement.
+patch. Use both 0.5.0 packages and migrate the framework adapter
+to the public core factory; this release retains the cold-validation/T08 fixes and adds T09
+timeout support and T05a identity preflight/phase timing.
 Upstream publication and regression success do not close that acceptance gate or diagnose the
 separate full-graph validation latency observation.
 
@@ -126,9 +176,9 @@ Missing or unsupported-only selectors and bounded agent omissions remain visible
 incomplete plans need review and exit 1. They do not introduce new hydration gates that would
 break deletion of the last document. Budget, duplicate-ID and corrupt/unavailable cache errors
 block planning checks without truncating selected sources. An explicit empty source list selects
-none. Requested refs now govern agent scope; corrected snapshots use graph-v6 while valid 0.2.1
-semantic artifacts remain reusable. T03's operational cache changes and T07's traversal/default
-validation-document separation remain separate work.
+none. Requested refs govern agent scope. Release 0.3.0 introduced graph-v6; 0.4.0 advances assembly
+to graph-v7 for T08 while compatible semantic artifacts remain reusable. T03 operational cache
+reuse shipped in 0.4.0; T07 traversal/default validation-document separation remains open.
 
 Acceptance:
 
@@ -143,8 +193,8 @@ Acceptance:
 
 ## T03 — Reuse valid artifacts after operational changes
 
-Merged in [PR 22](https://github.com/jchewitt/weftlet/pull/22) after 0.3.0, with local publication
-and hosted Ubuntu/Windows checks passing. This source checkpoint does not claim npm publication.
+Shipped in 0.4.0 after merging [PR 22](https://github.com/jchewitt/weftlet/pull/22) and passing
+local publication and hosted Ubuntu/Windows checks; release evidence is in [validation](VALIDATION.md).
 [ADR 018](ADR-018-operational-semantic-cache.md) separates built-in Codex user artifacts from
 full snapshot profiles. Timeout, retry, concurrency and document/byte limits can change without
 hiding completed artifacts. Model/policy/authentication descriptors and unknown fields remain
@@ -179,8 +229,8 @@ Acceptance:
 
 ## T04 — Explain timeouts and recovery
 
-Merged in [PR 25](https://github.com/jchewitt/weftlet/pull/25) after 0.3.0, with local publication
-and hosted Ubuntu/Windows checks passing. This development checkpoint does not claim npm publication.
+Shipped in 0.4.0 after merging [PR 25](https://github.com/jchewitt/weftlet/pull/25) and passing
+local publication and hosted Ubuntu/Windows checks; release evidence is in [validation](VALIDATION.md).
 [ADR 019](ADR-019-semantic-failure-diagnostics.md) records opaque source IDs and explicit local
 preview mapping, final counts after active workers settle, safe typed errors and recovery.
 Concurrent sibling cancellation preserves the initiating failure. Completed writes stay counted
@@ -205,17 +255,27 @@ Acceptance:
 
 ## T05 — Detect inexpensive conflicts early and explain validation work
 
+T05a shipped [early identity attribution and phase timing](ADR-021-identity-preflight-and-validation-timing.md)
+in 0.5.0 after local and hosted Ubuntu/Windows checks and independent archive review.
+Hydration and overlays reject all conflicting subject/object kinds before RDF construction;
+opaque default reports have explicit local detail opt-in.
+Completed semantic artifacts and prior snapshots remain intact. Valid preflight results still
+require full SHACL. Timings report actual phase boundaries, not in-phase heartbeat or percentage.
+This does not close the broader evaluation/reuse/backend items below or establish the consumer's
+full-run performance.
+
 The implementation uses JavaScript on Node:
 `rdf-validate-shacl` validates an in-memory N3 dataset. Hydration constructs and validates the
 entire assembled graph, including when semantic artifacts were reused. There is no persistent
 GraphDB backend or incremental validation. Querying a saved snapshot does not rerun SHACL.
 
-The maintainer reports that validation pushes the consumer's overall generation beyond its
+The maintainer originally reported that validation pushed the consumer's overall generation beyond its
 30-minute timeout, preventing snapshot publication and making adoption unusable. That report made
 cold validation a release priority ahead of the remaining 1.0 work. Upstream has measured a specific
 named-graph lookup cost in public synthetic fixtures, but has not measured that consumer graph or
 diagnosed its complete timeout. The focused cold-validation fix shipped in 0.3.0, ahead of the
-remaining 1.0 tasks. Consumer acceptance remains pending; broader T05 items stay open.
+remaining 1.0 tasks. The consumer is now reported working after 0.4.0; exact performance and
+repeat-hydration acceptance evidence remains unrecorded. ADR 027 records the broader engineering evaluation.
 
 [ADR 017](ADR-017-shacl-validation-union.md) records the implemented cold-validation optimization:
 build a temporary union of every SPO triple for the same validator/shapes, while keeping original
@@ -226,15 +286,15 @@ took 0.467 seconds. A 10,000-fact unique-node union case used about 1.3 GiB proc
 are synthetic phase measurements, not a private consumer reproduction or end-to-end guarantee.
 
 The focused change still validates the whole graph each time. It does not add Rust, GraphDB,
-incremental validation or a validation-result cache. Early checks and broader observability/reuse
-remain follow-ups rather than reasons to delay the cold-path fix. Native code or a database does
+incremental validation or a validation-result cache. T05a now adds early checks and phase timing;
+worker progress and reuse remain unsupported, with the decision evaluated in ADR 027. Native code or a database does
 not by itself establish faster or correct incremental SHACL.
 
 Acceptance:
 
-- Early errors identify the conflicting identity/kinds and relevant evidence using the configured
-  privacy policy. Preserve all underlying assertions for diagnosis; early checks are not a
-  substitute for RDF/SHACL validation.
+- Early errors identify the conflicting identity/kinds and relevant evidence through opaque
+  defaults and explicit local detail opt-in. Preserve all underlying assertions for diagnosis;
+  early checks are not a substitute for RDF/SHACL validation.
 - Report elapsed time and honest progress for long validation. Current phase boundaries remain
   the supported progress signal: the synchronous validator blocks same-thread timers. Evaluate
   bounded worker execution before promising an in-phase heartbeat or cancellation; never display
@@ -259,12 +319,27 @@ Acceptance:
   failure must preserve the prior snapshot. Keep model-independent profiling separate from live
   extraction performance and from the reported two-fact correctness defect.
 
+The bounded closeout is recorded in [ADR 027](ADR-027-validation-closeout.md): 258 public
+direct/worker cases cover cold/repeat/rebuilt and changed inputs; all 18 paired sample groups
+match exact verdicts and data. Dense metadata and 10,000-fact memory measurements justified a
+Rudof 0.3.35 evaluation: all 29 conformance/location cases agree, two diagnostic multiplicities
+differ, and 12 native timings establish no clear overall file-transfer benefit. Retain direct full
+validation. No cache, worker, incremental or native runtime capability is delivered. Exact-key
+costs/misses and a changed-facts-only counterexample support the reuse/incremental decisions.
+Consumer performance acceptance remains required; public fixtures do not silently replace it.
+
 ## T06 — Keep packaged documentation consistent with the release
 
-The consumer installed 0.2.0 while its packaged README still named 0.1.2 and some archive examples
-used 0.1.1. Release 0.2.1 removes the README version pins; immutable 0.2.0 archives retain their
-original text. The automated release-documentation consistency check remains open. Add that
-repeatable check rather than relying on manual edits alone.
+Implemented after 0.5.0, with [ADR 022](ADR-022-release-documentation.md) defining the checked
+scope. Changesets regenerates current-version sections in both READMEs and the release guide.
+The dependency-free checker verifies source instructions and both actual tarballs before
+publication; the fresh-consumer smoke exercises the checked pinned commands and archive pair
+with an isolated npm/npx cache. Historical records and feature-introduction versions stay intact.
+Source validation is recorded in [validation](VALIDATION.md); no new npm release is claimed here.
+
+The original consumer installed 0.2.0 while its README still named 0.1.2 and some archive examples
+used 0.1.1. Release 0.2.1 removed README version pins. T06 adds automation and replaces the release
+guide's stale 0.2.1 current-install example. Immutable earlier archives retain their original text.
 
 Acceptance:
 
@@ -289,6 +364,39 @@ traversal. Classify sources/claims explicitly; flag rules without clear SOT owne
 their inferred/unreviewed state. Validation documents are excluded from product-intent extraction
 by default and retained through a separately classified validation-evidence path.
 
+Delivery increments:
+
+1. **T07a implemented:** committed Markdown-link selection and an opt-in, no-model coverage preview: canonical targets,
+   cycles/deduplication, ambiguous or unresolved links, exclusions and explicit budget status.
+   Label this as prospective coverage until it drives hydration; existing hydration-plan documents
+   and cache estimates must continue to describe actual execution inputs. The current graph linker
+   also recognizes bare/code paths and is not itself a canonical traversal policy.
+2. **T07b merged with local/hosted checks and review passed:** explicit roles/ownership and separate
+   deterministic document presence/reference evidence. Optional per-fact metadata survives RDF,
+   query and viewer projection without changing canonical Document identities. Reaching an owner
+   does not approve a child or assertion; direct-source hydration remains unchanged.
+3. **T07c merged with local/hosted checks passed:** opt-in hydration integration, incremental artifact reuse and cross-source linkage, with
+   delete/rename handling and positive/negative real-extractor fixtures. Coverage failures stop
+   new model work without discarding completed artifacts or the last valid snapshot.
+
+[ADR 023](ADR-023-document-coverage-preview.md) records the T07a public API and `documents plan`
+command. Entry points, document roots and read limits are operation arguments, with existing
+semantic budgets used only for comparison. No configuration/cache identity or hydration selection
+is changed. [PR 38](https://github.com/jchewitt/weftlet/pull/38) merged T07a with hosted Ubuntu
+and native Windows checks; exact source validation is recorded in [validation](VALIDATION.md).
+No npm publication is claimed by implementation status.
+
+[ADR 025](ADR-025-document-classification.md) records T07b's shared classification contract
+and standalone deterministic document-evidence API. `documents plan --document-policy <json-file>`
+reads an operation-time sidecar; it adds no hydration configuration. The top-level `ready` checks
+traversal/budgets, while `classification.complete` independently reports role/ownership gaps.
+A resolved owner must be available, approved and an unambiguous intent source; an approved
+validation/plan/reference or ambiguous-role owner is ineligible. Neither ownership nor links
+transfer approval. Presence and references retain validation documents even without semantic
+artifacts or outgoing links, without asserting test success. T07c now invokes these APIs from explicitly configured hydration and overlays; validation
+evidence is preserved separately from semantic source selection. [ADR 026](ADR-026-traversal-hydration.md)
+records cache compatibility, coverage gates, draft invalidation and source/assertion authority.
+
 Acceptance:
 
 - Split delivery into canonical selection/traversal, role/ownership classification and semantic
@@ -333,5 +441,26 @@ Before calling the consumer migration accepted or publishing 1.0:
 5. Review the changelog, compatibility/migration guidance and remaining known issues, then use the
    normal reviewed version PR and trusted-publishing workflow. No 1.0 publication is claimed now.
 
+For the reviewed minor candidate, retain a private consumer bundle and share only a sanitized
+summary using the [consumer trial](CONSUMER-TRIAL.md):
+
+- Record both package versions, consumer/adapter SHA, platform/provider/model, configuration and
+  source scope; verify the no-model plan's roles, ownership, exclusions and budgets match execution.
+- Complete genuine full hydration and SHACL publication with the approved timeout, then repeat
+  unchanged inputs: zero new extraction, expected reuse and unchanged snapshot identity/content.
+  Record total and phase timing; the ten-minute extraction limit does not extend an outer job deadline.
+- Retain actual MCP requests/responses and continuations for predeclared changes, including a queue
+  boundary. Review downstream consumers, contracts, implementations/tests and page-scoped coverage;
+  a display group or a missing returned fact must not be mistaken for complete repository coverage.
+- Independently inspect citations and semantic usefulness: misses, irrelevant results, conflicting
+  claims, ownership gaps and misleading authority. Structural conformance is not a semantic-quality pass.
+- Check browser interaction against the same JSON pack/snapshot using the
+  [browser checklist](ENVIRONMENT-VALIDATION.md#browser-run-through-browser-mcp); keep deferred or
+  untested environments explicit. Preserve saved queries and prior snapshots during a failed refresh.
+
+Keep raw snapshots, artifacts, configuration and transcripts with the private consumer; do not
+export credentials or private product content. Upstream fixtures and a published candidate do not
+replace these consumer results or authorize an automatic 1.0 release.
+
 The patch's upstream pass is necessary but does not replace consumer acceptance. Track follow-up
 results without auditing or refactoring the source application's business logic from this repository.

package/docs/RELEASING.md

@@ -41,14 +41,14 @@ preparation route; native Windows has focused CI coverage. See [validation](VALI
    need an npm release can omit a changeset.
 2. On main pushes, **Release version PR** opens or updates a bot PR. Core and toolkit are a fixed
    release group: a release of either advances both to the same version. The PR contains package
-   versions, dependency/lockfile updates, changelogs, a generated `.changeset/release-plan.json`,
+   versions, dependency/lockfile updates, changelogs, generated current-version documentation, a `.changeset/release-plan.json`,
    and an updated extraction inventory. Original source hashes remain unchanged.
 3. Review the version PR and its checks, then merge it. This commits the versions to `main`
    **before** npm publication. Do not manually bump manifests or edit the generated plan.
 4. The plan change triggers **Weftlet release**. It validates and prepares both archives, publishes
    core followed by toolkit using npm trusted publishing, then verifies registry integrity.
-5. After both versions are verified, a separate job creates tags such as `@weftlet/core@0.2.1`
-   and `@weftlet/toolkit@0.2.1`, plus corresponding GitHub Releases, at that exact source commit.
+5. After both versions are verified, a separate job creates package-specific version tags
+   and corresponding GitHub Releases at that exact source commit.
    Existing tags are never moved. The publication job does not commit back to main.
 
 The bot uses GitHub's built-in token, not a personal access token. GitHub may require Settings →
@@ -95,7 +95,7 @@ pnpm install --frozen-lockfile
 pnpm context-graph:publication-check
 ```
 
-It runs build, deterministic tests, architecture, inventory, licenses and a fresh packed-consumer
+It runs release-documentation checks, build, deterministic tests, architecture, inventory, licenses and a fresh packed-consumer
 smoke. The smoke exercises setup/config, automatic core installation, real TypeScript SCIP,
 RDF/SHACL, visualization and MCP. No live model or public npm upload is invoked.
 
@@ -104,6 +104,8 @@ resolves workspace ranges, dry-runs unpublished versions and records source comm
 SHA-512 integrity in `.release/manifest.json`. Review the manifest, tarball file lists and extraction
 inventory. Preparation refuses pending changesets and stale release plans. It requires a clean
 checkout. An existing npm version must match exactly; different bytes stop the release.
+Both actual archives must also pass the documentation checks before preparation completes and
+again before publication starts.
 
 Actions → **Weftlet release** → **Run workflow** remains available on main. Leave **publish**
 unchecked for preparation only, or select it for an intentional release of the committed plan.
@@ -118,6 +120,31 @@ tokens are rejected and npm configuration is isolated. `npm whoami` is skipped b
 validate trusted publishing. npm verifies the identity and creates provenance. There is no token
 fallback. JavaScript pnpm and standalone `@pnpm/exe` are supported for local tooling.
 
+## Keeping installation documentation current
+
+The manifests own versions for this checkout/archive; registry publication is a separate fact.
+Changesets versioning regenerates the sections between `weftlet:release:start` and
+`weftlet:release:end` in both package READMEs and this guide. Do not edit those sections by hand.
+To check them or regenerate after a deliberate template change:
+
+```sh
+pnpm docs:release:check
+pnpm docs:release:update
+pnpm inventory:update
+```
+
+The checker also covers active installation examples in these files, the migration guide and
+the consumer-trial guide. Keep current explicit pins in sync; unpinned setup remains supported.
+An intentionally historical installation example uses a fenced block with info
+`sh weftlet-history` and explanatory historical prose. Feature-introduction versions and
+validation/changelog history do not become current version requirements.
+
+The publication gate checks actual packed manifests and documentation, including required
+documents and the toolkit/core version relationship. Its fresh-consumer smoke installs the
+documented archive pair and runs checked setup/validation argument arrays; Markdown is never
+executed as shell code. See [ADR 022](ADR-022-release-documentation.md) for the checked scope
+and limits. This does not establish that a prepared version is already on npm.
+
 ## Delayed visibility and failed releases
 
 Publication is sequential, not atomic across packages. Registry visibility and integrity of core
@@ -157,7 +184,8 @@ record job is the normal route.
 
 ## Inspecting and consuming releases
 
-Package-specific tags identify the exact published source, for example:
+Package-specific tags identify the exact published source. This historical inspection example
+selects the earlier 0.2.1 release:
 
 ```sh
 git fetch --tags
@@ -167,13 +195,23 @@ git switch --detach '@weftlet/toolkit@0.2.1'
 Tags support inspection and reproduction, not mutation of npm history. To roll a consumer back,
 install an earlier published version; fixes to a release need a new changeset/version.
 
-Verify a new public release in a fresh disposable project, substituting its version:
+<!-- weftlet:release:start -->
+These instructions use the package versions in this checkout/archive, not a claim about npm's latest tag.
+
+Verify the matching public version in a fresh disposable project after publication:
 
 ```sh
 npm init -y
-npx --yes @weftlet/toolkit@0.2.1 init --yes
-npx --yes @weftlet/toolkit@0.2.1 config validate
+npx --yes @weftlet/toolkit@0.6.0 init --yes
+npx --yes @weftlet/toolkit@0.6.0 config validate
+```
+
+For local installation, use both prepared archives from the same reviewed release:
+
+```sh
+npm install --save-dev "/path/to/weftlet/.release/weftlet-core-0.6.0.tgz" "/path/to/weftlet/.release/weftlet-toolkit-0.6.0.tgz"
 ```
+<!-- weftlet:release:end -->
 
 Check registry hashes, transitive core resolution and provenance. Deprecating the previous
 `@launch-echo` names is a separate action after replacement verification; never unpublish them.

package/docs/ROADMAP.md

@@ -1,21 +1,47 @@
 # Delivery roadmap
 
-Release checkpoint: 2026-10-26, after verified 0.3.0 publication. Evidence is recorded in
-[validation](VALIDATION.md); this roadmap is not a live registry status.
+Release checkpoint: 2026-10-27, after verified 0.5.0 publication.
+Evidence is recorded in [validation](VALIDATION.md); this roadmap is not a live registry status.
 
 Project: `jchewitt/weftlet`. Extraction provenance is recorded in the
 [source inventory](SOURCE-INVENTORY.md).
 
+T09 shipped in 0.5.0 with T05a work, accepting the consumer's approved
+`semantic.timeoutMs: 600000`. The default remains 120000 and retry/cancellation behavior is
+unchanged. The consumer's actual ten-minute retry has not run; upstream installation and
+deterministic checks do not establish that outcome. See [provider limits and recovery](PROVIDERS.md#limits-and-reuse).
+
 Forward direction is captured in the [Weftlet 2.0 product plan](WEFTLET-2.0-PLAN.md):
 consumer hardening, cited code-derived drafts, scoped approvals and reconciliation, an optional
 review website, source publication, managed AI and guided setup. “2.0” is a planning label;
-the verified release at this checkpoint is 0.3.0. The received consumer findings are tracked in the
+the verified release at this checkpoint is 0.5.0. The received consumer findings are tracked in the
 [consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md): the document-identity patch is
 published and passes upstream checks; genuine consumer acceptance remains pending. T02's
-no-model preview and T05's cold-validation improvement shipped in 0.3.0. Operational cache reuse
-and timeout diagnostics are development increments; document coverage and other acceptance work
-remain open before official 1.0.
-The 2.0 plan distinguishes proposed work from delivered capability.
+no-model preview and T05's cold-validation improvement shipped in 0.3.0. T03 operational cache
+reuse, T04 timeout diagnostics and T08 deterministic physical-file consistency shipped in 0.4.0.
+T09 timeout support and T05a identity preflight/phase timing shipped in 0.5.0.
+T06 [release-documentation consistency](ADR-022-release-documentation.md) is implemented for the
+next release: generated current examples, actual archive checks and fresh documented installation.
+T07a [prospective document coverage](ADR-023-document-coverage-preview.md) is implemented separately
+from hydration. It follows committed Markdown links and reports coverage/budget gaps without
+model calls or graph writes. T07b [document roles and ownership](ADR-025-document-classification.md)
+and the standalone deterministic document-evidence API merged in PR 42 after local/hosted checks
+and independent review. `documents plan --document-policy` accepts an operation-time JSON sidecar;
+classification completeness is separate from traversal/budget readiness. Ownership never transfers
+approval. T07c [traversal hydration](ADR-026-traversal-hydration.md) connects these APIs through
+explicit configuration, a shared no-model plan, compatible artifact reuse and draft invalidation.
+Direct-mode configuration retains its existing behavior; validation sources are excluded from
+model work in traversal mode. T07c merged in PR 44 after local and hosted Ubuntu/Windows checks;
+exact evidence is in [validation](VALIDATION.md). npm publication remains pending.
+T10 [implementation coverage reporting](ADR-024-implementation-coverage.md) is merged for the next
+release: actual code relationships can count as both contract and implementation evidence while
+display groups remain stable. Existing snapshots benefit without hydration; gaps are page-scoped.
+T05 [performance/validation closeout](ADR-027-validation-closeout.md) records the remaining
+engineering evaluations: cold/repeat/changed inputs, worker isolation, exact-result reuse,
+incremental dependencies and a bounded Rust comparison. Retain full direct validation; no worker,
+cache, incremental or native runtime capability is claimed. Complete source/release checks, publish
+a reviewed minor candidate, validate it in TradePilot, then review official 1.0. The candidate and consumer/final release gates remain
+separate acceptance work; the 2.0 plan remains a separate future direction.
 
 The maintainer reported SHACL pushing generation past a 30-minute timeout before graph
 publication. T02 and the focused T05 optimization shipped together in 0.3.0 through
@@ -32,25 +58,30 @@ in one temporary validation graph, preserving the same shapes and canonical name
 Bounded public experiments measured substantial cold-path improvement, alongside about 1.3 GiB
 RSS in the prototype at 10,000 unique-node facts; the production harness including serialization
 peaked near 1.6 GiB. They do not reproduce the private consumer's overall timeout.
-Early checks, in-phase progress, result reuse and incremental validation remain open; no Rust
-engine, graph database or validation-result cache is introduced by this focused release.
-
-[T03 operational cache reuse](ADR-018-operational-semantic-cache.md) is merged with local and
-hosted checks passing and is not part of published 0.3.0. Built-in Codex user
-artifacts can survive changes to timeout/retry/concurrency/document/byte limits while snapshots
-retain their full configuration identity. Exact legacy reads and explicit no-model adoption
-preserve prior artifacts; custom providers remain conservative.
-[T04 diagnostics](ADR-019-semantic-failure-diagnostics.md) add safe failure reports, opaque source
-mapping and accurate settled progress without changing extraction/cache identity. T04 is merged
-with local and hosted Ubuntu/Windows checks passing; release remains pending. Broader T05 and
-T06/T07 work remain open.
-
-A subsequent 0.3.0 consumer report makes [T08 physical-file kind consistency](ADR-020-canonical-physical-file-producers.md)
-the next release priority. Its neutral contract consumer fix and public core factory are merged
-with deterministic producer adoption, version guards and passing local/hosted Ubuntu/Windows
-checks. Publication is pending; the consumer's framework adapter migration and full acceptance
-remain consumer-owned.
-This fix preserves semantic artifacts and does not reinterpret model assertions to hide conflicts.
+T05a shipped [early identity checks and phase timing](ADR-021-identity-preflight-and-validation-timing.md)
+in 0.5.0 after local/hosted checks and independent archive review. Full validation remains mandatory.
+In-phase worker progress, result reuse and incremental validation remain unsupported. ADR 027
+records 258 direct/worker cases and 29 native correctness cases, with full graph/data preservation.
+The Rust file-transfer prototype showed no clear overall performance/resource advantage and
+differed on diagnostic multiplicity in two cases. Full direct validation remains the evaluated
+choice; private consumer performance acceptance remains required. No Rust engine, graph database
+or validation-result cache is introduced into the runtime.
+
+[T03 operational cache reuse](ADR-018-operational-semantic-cache.md) shipped in 0.4.0. Built-in
+Codex user artifacts can survive changes to timeout/retry/concurrency/document/byte limits while
+snapshots retain their full configuration identity. Exact legacy reads and explicit no-model
+adoption preserve prior artifacts; custom providers remain conservative.
+[T04 diagnostics](ADR-019-semantic-failure-diagnostics.md) shipped in the same release, adding
+safe failure reports, opaque source mapping and settled progress without changing extraction/cache
+identity. T05 engineering evaluation is recorded; T06 and T07 implementation are pending candidate publication.
+
+[T08 physical-file kind consistency](ADR-020-canonical-physical-file-producers.md) also shipped in
+0.4.0 after local/hosted Ubuntu/Windows checks, independent archive review and fresh packed and
+public-registry installation. The public core factory and deterministic producers share one policy
+under strict SHACL. Historical snapshots remain queryable, with version guards for current validation.
+On 2026-10-27 the maintainer reported the consumer updated and working; exact adapter and full
+hydration/repeat evidence remain unrecorded. This fix preserves semantic artifacts and
+does not reinterpret model assertions to hide conflicts.
 
 | Milestone | Delivered and checked | Remaining limits |
 | --- | --- | --- |
@@ -138,8 +169,8 @@ preparation/publication under `@launch-echo`; the maintainer completed the 0.1.0
 source-application reintegration remain outside the authorized scope. See [release instructions](RELEASING.md).
 
 The maintainer authorized the Weftlet migration on 2026-10-21. Both `@weftlet/core` and
-`@weftlet/toolkit` are published at 0.3.0 through GitHub OIDC; the publication and verification
-record is in [validation](VALIDATION.md). Changesets prepares reviewed version PRs for the fixed package group;
+`@weftlet/toolkit` use GitHub OIDC publication; current and historical publication/verification
+records are in [validation](VALIDATION.md). Changesets prepares reviewed version PRs for the fixed package group;
 merging a release plan triggers publication and package-specific tags/GitHub Releases.
 See [ADR 009](ADR-009-release-automation.md) and [release instructions](RELEASING.md).
 Earlier Tently packages remain available and undeprecated.