@weftlet/toolkit 0.2.0 → 0.2.1

package/README.md

@@ -9,11 +9,12 @@ boundaries. See the [roadmap](docs/ROADMAP.md) and [validation](docs/VALIDATION.
 supported capabilities and limitations.
 For a first real-project evaluation, use the [private consumer trial](docs/CONSUMER-TRIAL.md)
 to retain reproducible queries, logs and human-reviewed findings.
+Proposed future capabilities are recorded in the [Weftlet 2.0 product plan](docs/WEFTLET-2.0-PLAN.md).
 
 ## Set up a project
 
 Weftlet uses `@weftlet/toolkit`; its neutral `@weftlet/core` dependency is installed
-automatically. Both packages are available on npm at `0.1.2`.
+automatically. Both packages are available on npm.
 See [release status](docs/RELEASING.md). Existing Tently users should follow
 the [migration guide](docs/MIGRATING-TO-WEFTLET.md).
 
@@ -123,10 +124,10 @@ Each committed JSON record names a scoped binding and exact producer/consumer fi
 are cited candidate dependencies; they do not assert an approved policy or observed delivery.
 
 Install the locally packed core and toolkit tarballs together. The installed commands are
-`weftlet`, `weftlet-mcp`, and the compatible `context-graph` / `context-graph-mcp` aliases. For example, after preparing a release:
+`weftlet`, `weftlet-mcp`, and the compatible `context-graph` / `context-graph-mcp` aliases. For example, after preparing a release, replace `<version>` with the version in `.release/manifest.json`:
 
 ```sh
-npm install --save-dev /path/to/weftlet/.release/weftlet-core-0.1.1.tgz /path/to/weftlet/.release/weftlet-toolkit-0.1.1.tgz
+npm install --save-dev "/path/to/weftlet/.release/weftlet-core-<version>.tgz" "/path/to/weftlet/.release/weftlet-toolkit-<version>.tgz"
 npx weftlet init
 ```
 

package/dist/application/hydrator.js

@@ -3,6 +3,7 @@ import { contractPatternRoots } from "../repository/glob.js";
 import { repositoryFileExtractorIdentity } from '../extraction/static.js';
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { documentLinkerIdentity, linkSemanticDocuments } from "../extraction/document.js";
+import { repositoryNodeIdentityVersion } from '../extraction/repository-nodes.js';
 import { runtimeEvidenceFacts } from "../extraction/runtime-evidence.js";
 import { matchesRepositoryGlob } from "../repository/glob.js";
 import { RdfEvidenceGraph } from "../graph/rdf.js";
@@ -92,7 +93,7 @@ export class ContextGraphHydrator {
             : undefined;
         const configurationDigest = sha256(stableJson(config));
         const scopeDigest = sha256(stableJson(selectedSemanticSources)).slice(0, 12);
-        const effectiveSuffix = ['graph-v4', `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
+        const effectiveSuffix = ['graph-v5', `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
             ...(config.routingSources?.length ? [`routes-${routingExtractorIdentity.version}`] : []),
             configurationDigest.slice(0, 16), scopeDigest, baseSuffix, runtimeSuffix].filter(Boolean).join('-');
         const snapshotId = effectiveSuffix ? `${commitSha}-${effectiveSuffix}` : commitSha;
@@ -176,7 +177,7 @@ export class ContextGraphHydrator {
         const tracked = new Set(trackedPaths);
         for (const fact of semanticFacts) {
             for (const node of [fact.subject, fact.object]) {
-                const path = node.id.startsWith('component:file:') ? node.id.slice('component:file:'.length) : undefined;
+                const path = /^(?:component:file:|document:)(.+)$/.exec(node.id)?.[1];
                 if (path && !tracked.has(path))
                     diagnostics.push({
                         id: sha256(stableJson({ fact: fact.id, missing: path })),
@@ -235,7 +236,8 @@ export class ContextGraphHydrator {
                 scope: selectedSemanticSources,
                 ontologyVersion: config.semantic.ontologyVersion,
                 extractorVersions: {
-                    assembly: 'standalone-graph-v4',
+                    assembly: 'standalone-graph-v5',
+                    'repository-node-identity': String(repositoryNodeIdentityVersion),
                     [documentLinkerIdentity.id]: documentLinkerIdentity.version,
                     ...(config.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),
                     semantic: config.semantic.extractorVersion,

package/dist/extraction/document.js

@@ -1,12 +1,7 @@
 import { sha256, stableJson } from '../infrastructure/util.js';
 import { documentReferences, resolveDocumentReference } from './document-references.js';
+import { repositoryFileNode as fileNode } from './repository-nodes.js';
 export const documentLinkerIdentity = { id: 'document-linker', version: '2.0.0' };
-function fileNode(path) {
-    if (/\.(?:md|mdx|txt)$/i.test(path))
-        return { id: `document:${path}`, kind: 'Document', label: path };
-    return { id: `component:file:${path}`, label: path,
-        kind: /\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component' };
-}
 export function linkSemanticDocuments(context, hydrated, trackedPaths, approvedSourcePaths = []) {
     const facts = new Map();
     const diagnostics = new Map();

package/dist/extraction/repository-nodes.d.ts

@@ -0,0 +1,7 @@
+import type { GraphNode } from '@weftlet/core';
+/** Internal cache contract: changing this policy must also change snapshot assembly identity. */
+export declare const repositoryNodeIdentityVersion = 1;
+/** Physical file identity; this does not establish existence, intent, ownership or approval. */
+export declare function repositoryFileNode(path: string): GraphNode;
+/** Normalize only reserved document/file identities, never inferred business concept IDs. */
+export declare function canonicalizeRepositoryDocumentNode(node: GraphNode): GraphNode;

package/dist/extraction/repository-nodes.js

@@ -0,0 +1,20 @@
+/** Internal cache contract: changing this policy must also change snapshot assembly identity. */
+export const repositoryNodeIdentityVersion = 1;
+function isDocumentPath(path) {
+    return /\.(?:md|mdx|txt)$/i.test(path);
+}
+/** Physical file identity; this does not establish existence, intent, ownership or approval. */
+export function repositoryFileNode(path) {
+    if (isDocumentPath(path))
+        return { id: `document:${path}`, kind: 'Document', label: path };
+    return { id: `component:file:${path}`, label: path,
+        kind: /\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component' };
+}
+/** Normalize only reserved document/file identities, never inferred business concept IDs. */
+export function canonicalizeRepositoryDocumentNode(node) {
+    const match = /^(?:component:file:|document:)(.+)$/.exec(node.id);
+    if (!match || !isDocumentPath(match[1]))
+        return node;
+    const canonical = repositoryFileNode(match[1]);
+    return { ...node, id: canonical.id, kind: canonical.kind };
+}

package/dist/extraction/semantic.js

@@ -8,7 +8,22 @@ import { resolveCodexInvocation } from './codex-command.js';
 import { runSemanticProcess, SemanticProviderError } from "./semantic-process.js";
 export { SemanticProviderError } from "./semantic-process.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
+import { canonicalizeRepositoryDocumentNode, repositoryNodeIdentityVersion } from './repository-nodes.js';
 import { assertSemanticCitation, numberedSemanticSource, semanticCitationSchema, } from "./semantic-citations.js";
+function canonicalizeRepositoryDocuments(output) {
+    const ids = new Map();
+    const assertions = output.assertions.map((assertion) => {
+        const subject = canonicalizeRepositoryDocumentNode(assertion.subject);
+        const object = canonicalizeRepositoryDocumentNode(assertion.object);
+        ids.set(assertion.subject.id, subject.id);
+        ids.set(assertion.object.id, object.id);
+        return { ...assertion, subject, object };
+    });
+    return { ...output, assertions, diagnostics: output.diagnostics?.map((diagnostic) => ({
+            ...diagnostic,
+            relatedNodeIds: diagnostic.relatedNodeIds.map((id) => ids.get(id) ?? id),
+        })) };
+}
 function omlEscape(value) {
     return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n');
 }
@@ -213,7 +228,7 @@ export class CodexCliSemanticExtractor {
         this.config = config;
         this.runner = runner;
         this.loginProbe = loginProbe;
-        this.identity = `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v2`;
+        this.identity = `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v3`;
     }
     async extract(source, context, options = {}) {
         options.signal?.throwIfAborted();
@@ -235,7 +250,7 @@ export class CodexCliSemanticExtractor {
             'Use neutral graph kinds and the allowed precise predicates. Never guess a missing mapping.',
             'Use product-wide canonical IDs derived from durable concepts, not IDs scoped to this file.',
             'Reuse capability, policy, workflow, contract, and component IDs that another source would use for the same concept.',
-            'When the source names a repository path, use component:file:<path> so semantic and static facts join deterministically.',
+            'For a repository document path ending in .md, .mdx or .txt, use document:<path> with kind Document. For other repository files use component:file:<path>; test/spec files have kind Evidence, other files Component. Use exact repository-relative paths; keep business concepts in their own IDs instead of assigning their kind to a file.',
             'Capture why a rule exists, its decision authority, and cross-domain dependencies when the source explicitly states them.',
             'Every assertion must cite inclusive 1-based source line numbers and carry calibrated confidence.',
             `Source lines are explicitly prefixed N| below. Cite those original-source numbers, not prompt lines or visual wraps; valid lines are 1-${lineCount}.`,
@@ -330,6 +345,7 @@ export class SemanticHydrator {
             failOnUnresolved: this.config.failOnUnresolved,
             forceRevision,
             diagnosticContractVersion: 3,
+            repositoryNodeIdentityVersion,
         };
         const key = sha256(stableJson(keyInput));
         const existing = await this.store.read(key);
@@ -340,7 +356,7 @@ export class SemanticHydrator {
         if (typeof extraction.rawModelOutput !== 'string' || Buffer.byteLength(extraction.rawModelOutput) > 2 * 1024 * 1024) {
             throw new SemanticProviderError('invalid-output', 'Invalid or oversized raw semantic output');
         }
-        const output = extraction.parsed;
+        const output = canonicalizeRepositoryDocuments(extraction.parsed);
         const lineCount = source.content.split('\n').length;
         const facts = output.assertions.map((assertion, index) => {
             assertSemanticCitation(assertion.citation, source.path, lineCount, `assertion[${index}]`);

package/docs/ADR-015-repository-document-identity.md

@@ -0,0 +1,57 @@
+# ADR-015: Canonical repository document identities
+
+Status: accepted for the document identity patch.
+
+## Problem
+
+The 0.2.0 semantic prompt requested `component:file:<path>` for every repository path,
+while deterministic Markdown linking used `document:<path>` for document files.
+Independently valid model assertions could assign Component and Document to the same
+file ID. Combining those facts correctly failed the single-kind SHACL constraint.
+This is an extraction identity defect, not evidence of contradictory product intent.
+
+## Decision
+
+Physical repository documents ending in `.md`, `.mdx` or `.txt` use
+`document:<repository-relative-path>` with kind Document. The semantic hydration
+boundary canonicalizes both reserved prefixes (`component:file:` and `document:`)
+for those extensions, using the same file-node policy as deterministic document links.
+This applies to Codex and module providers, before fact IDs, OML and artifact hashes
+are computed. Diagnostic references are remapped with the assertions.
+
+Paths retain their exact spelling and case; no basename matching, existence guess,
+ownership inference or concept merging is performed. Distinct business concepts such
+as `contract:retention` remain separate from the document that describes them.
+Every assertion, predicate, citation, confidence and label is retained. Raw provider
+output remains unchanged for inspection. Normalizing physical identity never approves
+an assertion or establishes that a referenced file exists. Snapshot assembly continues
+to mark semantic assertions inferred/unreviewed, independently of source approval.
+
+The RDF identity and SHACL shape stay unchanged. Other conflicting kinds still fail
+validation; this policy does not hide genuine conflicts or remove assertions.
+
+## Artifact and snapshot migration
+
+An implementation-owned `repositoryNodeIdentityVersion: 1` participates in every
+semantic artifact key, including custom providers with unchanged user configuration.
+Codex's prompt contract advances to v3. Assembly advances to `graph-v5`, records the
+policy version in the manifest and uses a different immutable snapshot ID even for
+the same commit/configuration. Historical snapshots and artifacts remain untouched
+and queryable; they are not relabeled as newly validated evidence.
+
+The first semantic refresh after upgrading requires extraction under the new contract.
+Unchanged subsequent refreshes reuse the new artifacts. Do not delete the old cache or
+force a revision as an upgrade workaround. Provider cost for that first refresh remains
+subject to the consumer's configured budgets and authorization.
+
+## Validation and limits
+
+The public regression uses two committed documents referencing the same implementation
+document, a deterministic module provider returning the conflicting legacy identities,
+real TypeScript indexing, deterministic links and RDF/SHACL. It checks preserved facts,
+citations and review authority, old-cache isolation and repeat reuse. An unnormalized
+negative control retains the SHACL failure. This is provider-independent deterministic
+coverage, not a claim that a private consumer's full extraction has passed.
+
+Operational-config cache reuse, broad identity diagnostics and full-graph SHACL latency
+remain separate work in the [1.0 plan](RELEASE-1.0-PLAN.md).

package/docs/CONSUMER-TRIAL.md

@@ -6,11 +6,12 @@ development workspace. Saved evidence queries work without a model login. Hydrat
 prose uses the configured provider; an OAuth failure may block new extraction but does not
 remove an already published snapshot.
 
-Use a pinned, reviewed toolkit version and its matching documentation. The current `main`
-contains features beyond npm `0.1.2`, including explicit routing declarations. To evaluate
-those features before their release, use both locally prepared package archives from the
-same reviewed commit; see [release preparation](RELEASING.md). Record that commit separately
-from the package version, which does not change with every development commit.
+Use a pinned, reviewed toolkit version and its matching documentation. npm `0.2.0` includes
+explicit routing declarations, committed TypeScript source projects, document linkage and
+the improved impact ranking. To evaluate a newer, unreleased commit, use both locally prepared
+package archives from that same reviewed commit; see [release preparation](RELEASING.md).
+Record the commit separately from the package version, which does not change with every
+development commit.
 
 ## Choose tasks before querying
 

package/docs/RELEASE-1.0-PLAN.md

@@ -0,0 +1,221 @@
+# Consumer hardening and the 1.0 release plan
+
+Status: maintainer-directed work, recorded on 2026-10-26 from a consumer integration report.
+The starting release is `@weftlet/toolkit@0.2.0`. **Ship a patch for T01 first.** The remaining
+items improve setup, reuse, diagnostics and document coverage; they do not block that patch
+or justify 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.
+
+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
+AI. None of those platform features is a dependency of the fixes here.
+
+## Reported evidence and boundaries
+
+The consumer reported a cold extraction in which two source documents referred to the same
+repository Markdown document. Semantic assertions gave that one repository-path identity
+different node kinds, `Component` and `Document`. An isolated, unchanged two-fact graph failed
+the public RDF validator's single-kind constraint. The references describe the same document;
+this is an extraction identity conflict, not evidence of conflicting product intent.
+
+The consumer stopped its larger hydration after independently proving that failure. No full-run
+SHACL result or published snapshot is claimed. Several minutes spent in the larger validation
+phase is a separate observation; the two-fact reproduction does not diagnose its latency.
+Fresh-install checks and the package/adapter boundary were reported as successful.
+
+Private source paths, assertions, artifacts and application data remain with the consumer.
+Upstream work uses public-safe reproductions and preserves the original application's existing
+integration. Consumer acceptance is reported separately from upstream deterministic tests.
+
+## Task list and order
+
+| ID | Task | Priority/status | Dependencies and release boundary |
+| --- | --- | --- | --- |
+| **T01** | Coherent repository-document identity and kind | **Adoption blocker; patch work in progress** | First isolated patch; preserve SHACL and all assertions |
+| **T02** | No-model hydration/setup preview | Planned usability work | Shares selection/cache identity with hydration; extend it with T07 traversal coverage |
+| **T03** | Artifact reuse across operational configuration changes | Planned efficiency work | Preserve T01's semantic identity separation; keep snapshot/config identity distinct from reusable artifact identity |
+| **T04** | Actionable, privacy-safe timeout diagnostics | Planned diagnostics work | Use stable source identifiers and run progress; document recovery with T02/T03 |
+| **T05** | Early identity checks and validation progress/profiling | Planned correctness/observability work | Build on T01; profile latency independently before selecting optimizations |
+| **T06** | Packaged release-documentation consistency | Planned release tooling work | Check the actual release archives; does not require a runtime architecture change |
+| **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–T07 can ship in independently useful increments after the blocker patch. Do not combine
+all seven into one diff or delay T01 for the optional platform work. Normal required release
+checks still apply to every shipped increment.
+
+## T01 — Resolve repository-document identity conflicts
+
+Define and enforce a coherent ID/kind policy for repository document references across semantic
+and deterministic extraction. A prompt instruction alone is insufficient when separately valid
+model outputs can conflict after assembly. Preserve both source assertions and their citations,
+source authority and assertion-review state. Retain single-kind SHACL validation; do not discard
+an assertion or relax the shape to conceal the conflict.
+
+Acceptance:
+
+- A public regression has two committed documents referring to the same Markdown document,
+  with one provider assertion labeling it `Component` and the other `Document` under the same
+  repository-path identity. Both assertions survive under the coherent policy and align with
+  deterministic document links; the assembled graph passes RDF/SHACL validation.
+- Verify subject and object references, preserved provenance and unreviewed/inferred assertion
+  authority. Other incompatible identities remain diagnosable rather than silently merged away.
+- Version the relevant extractor/prompt/cache identity so incompatible old artifacts cannot
+  satisfy a fresh extraction. Test a fresh build, subsequent artifact reuse and unchanged
+  snapshot identity/content on repeat input. Keep historical saved snapshots readable and unchanged.
+- Run the normal deterministic/publication gate and a fresh installed-package smoke. Publish
+  the patch, then request a genuine consumer re-run against the recorded inputs; do not infer
+  consumer acceptance from the upstream fixture.
+
+Completion evidence will link the implementation PR, tested source commit, validation record,
+published patch and subsequent consumer result. No patch publication or consumer pass is claimed
+by this task list yet.
+
+## T02 — Preview scope and work without calling a model
+
+Add a no-model preview command, tentatively `hydrate --plan`; the CLI spelling is not implemented
+by this plan. Use the same source-selection and identity logic as hydration to avoid preview drift.
+Report selected sources and sizes, inclusion reasons, role/approval classification, expected
+artifact hits/misses and extraction count, plus document/byte limits and any violations.
+
+Acceptance:
+
+- Preview calls no provider and performs no extraction, indexing, snapshot publication or active
+  checkout mutation. Distinguish unavailable/corrupt cache entries from known reusable artifacts.
+- Identify the commit, configuration and selection assumptions; a later changed input can
+  invalidate the estimate. Report uncertainty explicitly instead of promising a cache hit.
+- Test empty/no-document scope, cold and warm artifacts, missing sources, budget violations and
+  semantic-identity changes. Provide machine-readable output and a concise human summary.
+- With T07, show complete inclusion/exclusion reasons, unresolved links, ownership/classification
+  gaps, coverage and budget effects before any model call. Do not silently trim the selection.
+
+## T03 — Reuse valid artifacts after operational changes
+
+The consumer reported that changing only a timeout selected a different cache profile and made
+completed extractions unavailable for reuse. Investigate both storage-location selection and
+artifact key construction. Separate operational controls from semantic-output identity, while
+retaining complete configuration metadata on snapshots and queries.
+
+Acceptance:
+
+- Changing supported operational settings such as timeout does not hide or invalidate an
+  otherwise reusable extraction. Explicitly classify each setting rather than assuming all
+  non-source changes are harmless; retain provider-specific extension behavior.
+- Changing source bytes/identity, model or relevant model settings, prompt/schema/extractor/
+  ontology identity, or other output-affecting policy invalidates reuse as required. T01's new
+  identity must not accidentally reuse old conflicting artifacts.
+- Preserve force-extraction semantics, concurrent-writer safety, isolation between consumers,
+  credentials and private cache contents. Record reuse and reasons for a miss without secrets.
+- Test interrupted work followed by a changed timeout: valid completed artifacts are reused,
+  incomplete/invalid ones are re-extracted, and source provenance remains correct.
+
+## T04 — Explain timeouts and recovery
+
+Report a privacy-safe source identifier, phase, elapsed time, configured limit and completed/
+remaining counts when extraction times out. Explain which completed artifacts can be retained
+and how to inspect the plan or adjust a bound before retrying. The documented two-minute default
+was insufficient for the reported workload; that observation alone does not select a new default.
+
+Acceptance:
+
+- Use a stable opaque identifier by default, with an explicit local mapping or opt-in detail for
+  identifying the source. Avoid leaking source text, full prompts, credentials or provider stderr.
+- Distinguish extraction timeout, cancellation, provider failure and infrastructure problems.
+  Preserve completed artifacts and the last valid published snapshot.
+- Test timeout/cancellation during a multi-source run, accurate progress counts, safe recovery
+  instructions and secret-free logs. MCP protocol stdout remains clean.
+
+## T05 — Detect inexpensive conflicts early and explain validation work
+
+Add inexpensive graph-assembly checks for incompatible identities before expensive validation.
+Keep the full conformance requirement. Separately instrument and profile large RDF/SHACL
+validation to determine where time is spent before choosing optimizations.
+
+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.
+- Report elapsed time and honest phase/heartbeat progress for long validation. Do not display a
+  fabricated completion percentage when the validator exposes no meaningful denominator.
+- Record reproducible public-fixture sizes, fact/node counts, runtime versions, wall time and
+  resource observations. Separate measured bottlenecks from hypotheses.
+- Any optimized validation/projection path has equivalence tests, including negative cases;
+  failure must preserve the prior snapshot. Keep model-independent profiling separate from live
+  extraction performance and from the reported two-fact correctness defect.
+
+## 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. Source documentation has since been updated, but immutable published archives retain
+their original text. Add a repeatable release-documentation check rather than relying on a
+post-publication source edit.
+
+Acceptance:
+
+- Distinguish current setup/version statements and executable installation examples from valid
+  historical release evidence. Do not rewrite historical versions indiscriminately.
+- Validate current instructions against the actual prepared core/toolkit versions and tarball
+  contents before publication. Test both mismatches and intentionally historical references.
+- Define how versioning updates or generates current-release documentation so normal Changesets
+  bumps cannot silently leave it stale. Verify installation examples from fresh packed output.
+
+## T07 — Traverse canonical documents with explicit coverage and authority
+
+Start from configured SOT and master-roadmap entry points and recursively follow supported
+canonical Markdown links to owner/task documents. Resolve against the chosen repository commit,
+with cycle detection, canonical identities and deduplication. Report missing, ambiguous, outside-
+scope or unsupported links instead of inventing targets or automatically fetching external URLs.
+
+Extract requirements, business rules, constraints and cross-feature dependencies while retaining
+source citations and explicit ownership. Reaching a document through a link does not approve it.
+Routine implementation checklists and inferred plans cannot become approved intent through
+traversal. Classify sources/claims explicitly; flag rules without clear SOT ownership and retain
+their inferred/unreviewed state. Validation documents are excluded from product-intent extraction
+by default and retained through a separately classified validation-evidence path.
+
+Acceptance:
+
+- Split delivery into canonical selection/traversal, role/ownership classification and semantic
+  extraction/linkage increments. Keep the existing direct-source configuration usable.
+- The T02 preview exposes entry points, traversed paths, inclusion/exclusion reasons, roles,
+  approval/ownership state, unresolved links and exact budget/coverage limits without model calls.
+- Support cycles, shared targets, relative links/fragments and rename/delete cases without
+  duplicate extraction. Test cross-feature owner/task references and validation documents,
+  including mixed or ambiguous content that needs explicit classification.
+- Compute the necessary selection before scheduling model work. If limits prevent full requested
+  coverage, stop or require an explicit narrower scope/budget decision; never silently truncate
+  dependencies to fit a document count. Persist incomplete coverage and its reason where relevant.
+- Reuse unchanged extraction artifacts incrementally. Recompute reachability/classification when
+  links or configuration change; invalidate affected relationships and preserve removed-source
+  history. Partial failures retain completed artifacts and the last valid snapshot.
+- Prove cross-source linkage using extracted public prose and real code relationships, with
+  missing links, ambiguous ownership, conflicting claims and false cross-domain matches as
+  negative cases. Separate deterministic fixtures from budgeted live-provider evaluation.
+
+## Official 1.0 acceptance
+
+After T01's patch is available, work through T02–T07 in bounded increments and record implementation
+PRs and validation evidence here or in the linked validation record. Review the exact 1.0 scope
+against completed evidence; any deferral needs an explicit maintainer decision and must remain
+visible rather than being treated as done. The companion website, hosted AI and broader 2.0
+product plan remain separate.
+
+Before calling the consumer migration accepted or publishing 1.0:
+
+1. Confirm the patched identity policy in a genuine consumer hydration, including completed full
+   graph validation and snapshot publication, querying and an unchanged repeat. Keep provider
+   details, source scope and remaining gaps explicit; the consumer performs its own application work.
+2. Verify no-model scope preview, budget/coverage reporting, operational cache reuse and recovery
+   diagnostics against the implemented task scope. Exercise SOT traversal and authority separation
+   with public fixtures and reviewed consumer evidence.
+3. Pass supported-platform build/tests, fresh packed and public-registry installation, real
+   TypeScript indexing, RDF/SHACL, CLI/MCP, provenance and source-inventory checks. Check packaged
+   release instructions before publishing the exact reviewed archives.
+4. Record independently assessed usefulness and semantic-quality limits. Preserve the distinction
+   between deterministic checks, live-provider tests, browser checks and private consumer results.
+   Existing untested environments or deferred capabilities remain explicitly labeled.
+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.
+
+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

@@ -1,8 +1,16 @@
 # Weftlet npm releases
 
-`@weftlet/core@0.1.2` and `@weftlet/toolkit@0.1.2` are published. The first automatic
-release completed in [run 39672652013](https://github.com/jchewitt/weftlet/actions/runs/39672652013),
-including package tags and GitHub Releases at commit `3d8d1f38a9e70b38178921cdabf5e8714c417c1c`. Their first trusted
+`@weftlet/core@0.2.0` and `@weftlet/toolkit@0.2.0` are published through GitHub OIDC.
+[Run 40344526047](https://github.com/jchewitt/weftlet/actions/runs/40344526047) completed at
+commit `ffe7f1d81f0421b35220bd7ba5b1555246c7a0e1`, including registry integrity checks,
+package tags and GitHub Releases. The first attempt published core, then toolkit publication
+stopped with Sigstore `TLOG_CREATE_ENTRY_ERROR` HTTP 409. Re-running failed jobs on the same
+workflow restored the prepared archives and acceptance receipt; attempt 2 completed without
+changing versions. See [validation](VALIDATION.md) for the verification record.
+
+The first automatic release, 0.1.2, completed in
+[run 39672652013](https://github.com/jchewitt/weftlet/actions/runs/39672652013),
+including package tags and GitHub Releases at commit `3d8d1f38a9e70b38178921cdabf5e8714c417c1c`. The first trusted
 publication passed in [run 39661957651](https://github.com/jchewitt/weftlet/actions/runs/39661957651)
 from commit `720a5f964fe3cb6c438be6d22b4aa8b4ad44de17`, with matching registry archive integrity,
 npm provenance and a fresh public CLI installation. Earlier Weftlet and `@launch-echo` releases
@@ -26,8 +34,8 @@ preparation route; native Windows has focused CI coverage. See [validation](VALI
    **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.1.2`
-   and `@weftlet/toolkit@0.1.2`, plus corresponding GitHub Releases, at that exact source commit.
+5. After both versions are verified, a separate job creates tags such as `@weftlet/core@0.2.0`
+   and `@weftlet/toolkit@0.2.0`, plus 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 →
@@ -140,7 +148,7 @@ Package-specific tags identify the exact published source, for example:
 
 ```sh
 git fetch --tags
-git switch --detach '@weftlet/toolkit@0.1.2'
+git switch --detach '@weftlet/toolkit@0.2.0'
 ```
 
 Tags support inspection and reproduction, not mutation of npm history. To roll a consumer back,
@@ -150,8 +158,8 @@ Verify a new public release in a fresh disposable project, substituting its vers
 
 ```sh
 npm init -y
-npx --yes @weftlet/toolkit@0.1.1 init --yes
-npx --yes @weftlet/toolkit@0.1.1 config validate
+npx --yes @weftlet/toolkit@0.2.0 init --yes
+npx --yes @weftlet/toolkit@0.2.0 config validate
 ```
 
 Check registry hashes, transitive core resolution and provenance. Deprecating the previous

package/docs/ROADMAP.md

@@ -3,6 +3,14 @@
 Project: `jchewitt/weftlet`. Extraction provenance is recorded in the
 [source inventory](SOURCE-INVENTORY.md).
 
+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 published packages remain 0.2.0. The received consumer findings are tracked in the
+[consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md): first release the blocking
+document-identity patch, then address setup, reuse, diagnostics and document coverage before
+official 1.0 acceptance. The 2.0 plan distinguishes proposed work from delivered capability.
+
 | Milestone | Delivered and checked | Remaining limits |
 | --- | --- | --- |
 | 1. Standalone | Explicit committed inventory, core/toolkit boundary, public examples, build/tests, packed independent consumer and real TypeScript indexing | GitHub exported; both @launch-echo packages published at 0.1.0 and public installation verified |
@@ -89,8 +97,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.1.2 through GitHub OIDC, with provenance and a fresh public
-installation verified. Changesets now prepares reviewed version PRs for the fixed package group;
+`@weftlet/toolkit` are published at 0.2.0 through GitHub OIDC; the publication and verification
+record is 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.

package/docs/VALIDATION.md

@@ -8,6 +8,78 @@ The milestone entries below record the original cloud checks. Subsequent
 establishes live Codex success on Windows and the full deterministic checks on WSL,
 while identifying remaining native Windows issues.
 
+## Repository document identity patch, 2026-10-26
+
+The public reproduction confirms the reported 0.2.0 defect: two unchanged semantic
+assertions give one repository document ID different kinds and fail single-kind SHACL.
+[ADR-015](ADR-015-repository-document-identity.md) records the canonical identity policy,
+cache contract and immutable snapshot migration. The consumer follow-ups are tracked in
+the [1.0 plan](RELEASE-1.0-PLAN.md).
+
+- Local `pnpm context-graph:publication-check` passed: 227 deterministic tests (1 core,
+  226 toolkit), one optional OML skip, 12 advisory architecture findings, inventory,
+  licenses and a fresh packed-consumer CLI/npx/MCP, real SCIP and RDF/SHACL smoke.
+- The new public regression uses two committed source documents and a deterministic
+  module provider that reproduces the conflicting classifications. Both semantic facts
+  retain their citations, confidence and separate source/assertion authority; deterministic
+  document links and SPARQL join the canonical document. Real TypeScript indexing and
+  SHACL pass. Fresh extraction reports 2 extracted/0 reused; repeat reports 0/2 with
+  identical snapshot identity/content digest. Raw provider output is preserved byte for byte.
+- Seeded artifacts using the released 0.2.0 cache-key formula are not reused or overwritten.
+  Historical graph-v4 snapshot bytes remain unchanged and readable. Subject references
+  normalize too; unrelated concept-kind conflicts still fail SHACL. A missing document
+  mentioned in plain prose retains a cited implementation-gap diagnostic.
+- Independent review found and resolved that missing-path diagnostic regression. No blocking
+  findings remained. All 79 original imported source paths and source hashes are preserved.
+
+These are deterministic upstream checks, not live semantic-quality or private consumer
+acceptance results. The consumer's full hydration was stopped after its isolated reproduction;
+no complete consumer SHACL verdict or published snapshot is claimed. Full-graph validation
+latency remains a separate investigation. Release and hosted-check evidence will be recorded
+after the patch completes the normal publishing workflow.
+
+## Weftlet 0.2.0 publication, 2026-10-26
+
+The maintainer authorized publication of both packages. [Release PR 4](https://github.com/jchewitt/weftlet/pull/4)
+committed their `0.2.0` versions to main at `ffe7f1d81f0421b35220bd7ba5b1555246c7a0e1`.
+[Trusted-publishing run 40344526047](https://github.com/jchewitt/weftlet/actions/runs/40344526047)
+completed successfully on attempt 2. Both npm `latest` tags resolve to `0.2.0`.
+
+- Exact release-PR head `a818ee6312f6970015cea66f55cf6bb2cc62e363` passed the
+  [dispatched Ubuntu/Windows checks](https://github.com/jchewitt/weftlet/actions/runs/40042137308).
+  Local `pnpm release:prepare` also passed 222 deterministic tests, one optional OML skip,
+  12 advisory architecture findings, inventory, licenses and fresh packed-consumer checks.
+  The publication workflow repeated preparation at the merged source commit.
+- Independent review checked the generated release plan, versions/changelogs, all 79 original
+  source identities and the actual archives. Core contains 11 entries and toolkit 179;
+  runtime assets, public examples and licenses/notices are present. No credentials, Git history,
+  caches or generated graph snapshots were included. Toolkit's packed core dependency is `^0.2.0`.
+- Both public npm tarballs match the hosted prepared archives byte for byte, and those hashes
+  match the locally reviewed archives. Public SLSA provenance subjects match their SHA-512
+  digests and reference this exact commit, repository and `publish.yml` workflow. This checks
+  provenance content and source identity; it is not a separate cryptographic signature audit.
+- Attempt 1 published and verified core, then toolkit's provenance submission failed with
+  `TLOG_CREATE_ENTRY_ERROR` / HTTP 409 for an equivalent transparency-log entry. The core
+  acceptance receipt and original archives were retained. Registry state was inspected before
+  rerunning only failed jobs in the same run. Attempt 2 completed toolkit publication using the
+  unchanged version/archives; core was already present. No provenance setting was disabled.
+- Package tags `@weftlet/core@0.2.0` and `@weftlet/toolkit@0.2.0`, and their public GitHub
+  Releases, point to `ffe7f1d81f0421b35220bd7ba5b1555246c7a0e1`. The release records contain
+  the verified archive digests. Main's package versions agree with npm.
+- A fresh public-registry consumer on Linux / Node 24.19.0 installed only
+  `@weftlet/toolkit@0.2.0` directly (`npm install --ignore-scripts`); core resolved transitively
+  to `0.2.0`. Both lockfile registry URLs and integrity hashes match the prepared archives.
+  CLI init/configuration and the npm-exec launcher passed. Real TypeScript indexing produced
+  15 SCIP facts within 22 total facts; the impact query returned 22 and SHACL conformed.
+  Repeat hydration preserved snapshot identity/content. Saved queries preserved snapshot bytes
+  and labeled excluded working edits. MCP initialized, discovered `impact.scan`, returned a
+  bounded 20-fact response and reported a missing snapshot as an error. No semantic documents
+  were selected: both hydrations extracted/reused zero artifacts, so this does not establish
+  model extraction or semantic artifact reuse.
+
+Live model/authentication quality, browser interaction and genuine fresh-task cloud restoration
+remain separate. No source application was changed and no live model call was made for release.
+
 ## Development workspace recovery, 2026-10-23
 
 The existing Codex development workspace became executable again at repository commit

package/docs/WEFTLET-2.0-PLAN.md

@@ -0,0 +1,282 @@
+# Weftlet 2.0 product plan
+
+Status: proposed direction captured at the maintainer's request on 2026-10-26.
+Baseline: published `@weftlet/core` and `@weftlet/toolkit` **0.2.0**, with release evidence in
+[VALIDATION.md](VALIDATION.md). **“2.0” names this product plan; it does not announce npm
+version 2.0.0, a delivery date, or a single large release.** Changes should ship through small,
+reviewed milestones using the existing Changesets workflow.
+
+The maintainer supports developing this direction. Detailed schemas, hosting, commercial
+terms and policy choices below remain proposals to resolve before their dependent work.
+This planning increment implements no features, changes no license and provisions no services.
+
+## Product outcome
+
+Help teams establish and maintain an agreed set of product rules, connect those rules to
+implementation and evidence, and make the relevant rules available to development agents.
+
+A team should be able to adopt Weftlet in a poorly documented project, generate a bounded set
+of cited proposals, approve or correct them, publish documentation through its chosen source
+adapter, and see subsequent disagreements between intent, code and other documents.
+An owner can confirm that the current implementation expresses the intended business rules
+and establish an initial documentation baseline through explicit review.
+
+The first complete demonstration is: a repository with sparse documentation produces useful
+candidate rules; a reviewer resolves a real disagreement; a documentation PR is merged; an
+agent retrieves the approved, scoped decision through MCP and identifies any remaining code gap.
+
+## Current capabilities and gaps
+
+| Area | Available in 0.2.0 | Work proposed here |
+| --- | --- | --- |
+| No documentation | TypeScript/code relationships, configured contracts, tests and supplied runtime/routing evidence; semantic sources may be empty | Cited implementation summaries and candidate business rules derived from code |
+| Partial documentation | Selected committed Markdown/text extraction, document links, scoped coverage/gap reports | Cross-source reconciliation, amendment proposals and approval workflow |
+| Evidence authority | Implementation, tests, observations, inferred/draft facts; source approval separated from model assertion review | Durable derivation history and approvals bound to specific claims/content revisions |
+| Agent decisions | Task/checklist text helps querying and source selection | Capture explicit accepted decisions as durable evidence before polished docs exist |
+| Queries | Local saved snapshots, RDF/SPARQL/SHACL, impact scans, continuation, CLI/MCP and draft overlays | Domain-scoped approved rules, exceptions and unresolved conflicts available to agents |
+| Providers | Codex CLI with ChatGPT or explicit API-key mode; tested module extension contract | Tested direct API adapters and an optional Weftlet-managed inference service |
+| Setup and UI | CLI init/config/doctor; bounded HTML/DOT/SVG viewer | Assisted setup and optional hosted review/management application |
+| Source adapters | Repository evidence plus extractor/invariant extension points | Explicit proposal/publication capabilities; GitHub Markdown first, other sources later |
+
+Current approval uses document paths/globs. Generated text written under an approved path could
+appear to come from a declared source, even though model-extracted assertions remain unreviewed.
+That is a prerequisite to address before automatic documentation backfill. Current citations
+also do not preserve a complete code → generated document → re-extracted assertion lineage.
+Existing gap reports do not establish completeness of a project's business requirements.
+
+## Immediate priority: consumer integration findings
+
+The maintainer supplied a consumer integration report on 2026-10-26. The
+[consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md) records its seven items and acceptance
+criteria. First ship the blocking repository-document identity/kind fix as an isolated patch;
+then work through the other improvements toward an official 1.0. Ordinary reliability fixes
+ship independently of the companion platform described here.
+
+| Intake item | Status | Next action |
+| --- | --- | --- |
+| Consumer integration report | Received; task list recorded | Preserve private evidence with the consumer and use public-safe upstream reproductions |
+| Reproduction and severity | Identity/kind defect is the reported adoption blocker | Reproduce two-document conflict upstream; keep validation latency a separate investigation |
+| Fix/release mapping | Blocker patch in progress; remaining tasks planned | Release T01 first, then T02–T07 and genuine consumer acceptance before official 1.0 |
+
+For each finding, retain toolkit/version, repository SHA, relevant configuration and scope,
+exact command or MCP request, expected/actual behavior, logs/exit status, snapshot identity,
+dirty-worktree state and provider details where relevant. Distinguish infrastructure failure,
+configuration error, extraction gap, incorrect relationship, policy violation and usability issue.
+Use the [consumer trial](CONSUMER-TRIAL.md) for evidence collection. Private application code,
+logs and product documents stay with the consumer; publish only reviewed reproductions and summaries.
+Consumer findings do not authorize modifying the original source application from this repository.
+
+## Proposed product boundaries
+
+- **Local toolkit:** indexing, immutable evidence, generation orchestration, local review data,
+  queries and MCP continue to work in a repository. Saved queries remain available when a
+  model, website or network is unavailable, with explicit version/freshness limitations.
+- **Optional companion service:** project connections, review queues, decisions, publication
+  jobs, history, synchronization status and organization management. Customers choose which
+  proposals and source excerpts leave their machine; whole-repository upload is not a prerequisite.
+- **Source adapters:** read versioned evidence, prepare a target-specific proposal, and apply it
+  through explicitly supported operations. Read access does not imply write capability.
+- **Model providers:** perform bounded extraction/generation under the same structured-output,
+  citation, timeout, cancellation and cache contracts. Provider output cannot grant approval.
+
+Initially, published documentation on the selected GitHub branch is the authoritative document
+destination. The companion tracks proposals and decisions without silently becoming a competing
+source of truth. Review decisions and their provenance must be exportable in a versioned format
+usable by the toolkit; access to existing evidence cannot depend on continued subscription.
+
+## Evidence and decision semantics
+
+Define these records before the website depends on them; exact field names remain an ADR task:
+
+| Record | Required meaning |
+| --- | --- |
+| Evidence | Source identity, revision/commit, digest, citation span, extraction method and scope |
+| Proposed claim | Stable identity and revision; kind (implementation description or proposed requirement); statement, conditions, domain and exceptions; supporting/contradicting evidence; inference and uncertainty |
+| Derivation | Links from source evidence through model output, generated documents and subsequent extraction; provider/model/prompt identities |
+| Decision | Authorized actor, exact claim/content revision, scope, explicit meaning (accuracy review or adoption as intent), action, timestamp/reason and any superseded decision |
+| Publication | Destination identity/base revision, proposed diff, idempotency identity, PR/write result and published revision |
+| Reconciliation | Applicable rule versions, compared source revisions, potential conflict or implementation gap, and resolution status |
+
+Preserve these distinctions throughout extraction, RDF, queries, visualization and write-back:
+
+1. Code supports statements about implementation. Tests support what was checked; a test-file
+   link does not prove execution. Runtime traces describe observations for their recorded scope.
+   Owners can explicitly adopt a proposed rule as intent; model confidence cannot do that.
+2. Source approval and approval of an extracted assertion are separate. Approval is scoped to
+   content/claim revisions and authorized actors, not inherited merely from a file location.
+3. Re-ingesting generated text preserves its derivation and does not create independent
+   corroboration or automatically increase confidence or authority.
+4. Code changes can stale supporting evidence or implementation summaries. They do not revoke
+   or rewrite approved business intent. Superseding intent requires a recorded decision.
+5. Decision status, publication status, graph freshness and implementation compliance are
+   separate. Approval, opening a PR, merging it and refreshing a graph are distinct events.
+6. Scope includes domain, conditions, applicable population/version and exceptions. Fourteen-day
+   and thirty-day rules may legitimately coexist in different scopes. A newer document does
+   not automatically override another domain or a shared contract's owner.
+7. Model-identified conflicts remain potential conflicts until reviewed or deterministically
+   established. Only explicit approved deterministic rules become hard CI gates. Missing required
+   evidence remains unknown/incomplete, not a pass.
+8. Source text is evidence input. It cannot authorize writes, impersonate an approver or instruct
+   the extraction process to alter its permissions. Approval records need a verifiable trust basis.
+
+## Delivery sequence
+
+M0 consumer hardening is in progress; M1–M7 remain proposed work. Each should be split into
+independently testable PRs and retain saved-snapshot compatibility; schema changes need an
+explicit migration ADR.
+
+| Milestone | Depends on | Deliverable and completion evidence |
+| --- | --- | --- |
+| **M0 — Consumer hardening** | Received report; [1.0 task list](RELEASE-1.0-PLAN.md) | Ship the identity/kind blocker patch first, then bounded setup/reuse/diagnostics/coverage improvements and genuine consumer acceptance. Release independently of the companion platform. |
+| **M1 — Claims, lineage and approvals** | M0 triage | Versioned records, durable derivation, revision-scoped approvals, actor trust and explicit legacy handling. Prove generated documents cannot acquire approval through paths or repeated extraction. Verify persistence/RDF/projection/query equivalence and old-snapshot readability. |
+| **M2 — Code-derived drafts** | M1 | Opt-in generation for selected TypeScript modules using existing local Codex first; structured candidate claims and Markdown rendered from those claims. Demonstrate no-doc and partial-doc fixtures with citations, unknown rationale, bounded cost, cache reuse and rename/delete invalidation. |
+| **M3 — Decisions and reconciliation** | M1–M2 | Capture explicit accepted requirements/decisions, compare changes from code and documents, distinguish scope differences from conflicts, and propose focused amendments. Demonstrate a resolved documentation disagreement with a remaining implementation gap. |
+| **M4 — Review website and GitHub publication** | M1–M3 | Thin optional application using local generation, review bundles, scoped approvals, GitHub Markdown PRs and publication/refresh tracking. Demonstrate the entire review → merge → MCP workflow, including stale revisions, human edits and failed/retried publication. |
+| **M5 — Managed inference and usage** | Stable extraction contract; M4 project identity | One tested hosted provider behind a Weftlet project key; usage ledger, budgets, metering and billing/recovery semantics. Preserve local Codex; add direct BYOK adapters individually. Prove isolation, bounded spending, cancellation and retry accounting before a paid pilot. |
+| **M6 — Guided onboarding** | M0 findings; relevant M2/M4/M5 capabilities | Repository discovery, concrete config recommendations, execution-mode choice, upload/cost preview, small initial run and actionable diagnostics. Prove setup in independent supported projects without overwriting existing integration or approving intent. Deterministic setup improvements can ship earlier. |
+| **M7 — Further adapters and offerings** | Evidence from the first complete workflow | Evaluate Figma, Trello, GitHub Projects, Canva or other requested sources one at a time. Document supported reads/writes and validate one adapter before expanding. Consider enterprise/self-hosted service requirements after the hosted pilot. |
+
+### M2: bootstrap without manufacturing intent
+
+Begin from the existing implementation graph and selected code/tests. Produce cited implementation
+summaries, candidate rules, conditions/exceptions and questions requiring an owner. Render drafts
+from the same structured claims used by the graph, avoiding a mandatory prose-generation then
+prose-re-extraction round trip. Generated descriptions remain useful and queryable before approval,
+with their status visible. Commit-only generation remains the initial reproducible baseline;
+support for working changes must be explicit and retain draft identities.
+
+Test dead or conditional code, ambiguous names, unsupported interpretations and behavior that could
+be a bug. Selecting a module does not establish exhaustive coverage of its business rules.
+Changed inputs invalidate affected generated claims; unchanged artifacts can be reused. Keep the
+last valid snapshot/proposals when generation fails. No automatic generation during ordinary queries.
+
+### M3: intent created during development
+
+Capture concise, explicitly accepted decisions with their source instruction and acceptance event.
+The actual owner instruction can be recorded before a formal document exists; an agent's proposed
+interpretation retains proposal status. Do not treat every prompt, task argument, plan or completed
+code change as approved intent. Review any generated paraphrase independently of the original source.
+
+Compare code → documents, documents → code, and documents → documents. Group evidence by domain
+and shared contract, retain contradictions and require explicit resolution of competing claims.
+If a reviewer approves a thirty-day refund policy while code enforces fourteen days, publish the
+decision/documentation and keep the implementation gap open. Confidence or recency alone cannot
+select the authoritative rule. Capture new discoveries separately from frozen evaluation expectations.
+
+### M4: review, publication and agent access
+
+Review coherent batches by capability/workflow, emphasizing consequential changes and unresolved
+questions. Show the proposed statement, citations/source revisions, existing rules, related code/tests
+and exact destination diff. Offer approve, edit, reject and request-clarification actions. If bulk
+approval is supported, bind it to an explicit immutable set of claims and revisions.
+Make approval meaning explicit: confirming an implementation description's accuracy records that
+review; adopting a requirement as product intent is a separate decision.
+
+Use GitHub Markdown and PR creation as the first source-write workflow. Preserve human edits;
+generated sections can refresh under an explicitly configured policy. Check destination revisions
+before applying updates, use idempotent operations, and show conflicts/failures rather than overwrite.
+Opening a PR does not mark documentation published. For the initial integration, publication on the
+configured branch establishes the effective documentation revision; any earlier effective-decision
+policy must be explicitly designed and displayed.
+
+MCP should return relevant approved rules and exceptions, their revisions and provenance, unresolved
+conflicts, implementation gaps and synchronization/freshness status. Cloud and local views must agree
+on the underlying facts. Historical or draft evidence remains usable with labels and cannot silently
+satisfy current-diff validation. MCP access improves consistency but does not prove model compliance.
+
+Before a shared hosted pilot, validate project/tenant isolation, authenticated review permissions,
+export/deletion/retention behavior, browser interaction and accessibility, and failure recovery.
+Choose the hosting stack and operating budget in a separate design decision.
+
+### M5–M6: execution choices and setup experience
+
+| Execution choice | Intended behavior |
+| --- | --- |
+| Local Codex | Preserve the existing developer login and configured local CLI. No mandatory API billing or hosted generation. |
+| Customer provider | Add supported direct API adapters with credentials on the chosen execution side. Decide explicitly whether any hosted BYOK mode stores customer secrets. |
+| Weftlet-managed AI | Local tooling sends selected extraction/generation inputs to a hosted API using a project-scoped Weftlet key; the service invokes a supported provider and returns validated, cited results. |
+
+Separate project/service authorization from upstream model credentials and business-rule approval.
+Individual ChatGPT/Codex login sessions stay on the developer's machine. Managed inference must use
+provider accounts and terms suitable for the offered service. Never silently fall back from local or
+customer-paid execution to Weftlet-billed inference, or change models during recovery without policy.
+
+Show selected source scope, model, estimated usage, budget cap and actual usage. Establish spend
+reservations/limits, cancellation, timeouts, provider failure reporting, retry/idempotency behavior,
+cache accounting and reconciliation of uncertain charges. Distinguish actual provider consumption
+from an estimate; bytes/documents alone do not establish a price. Credentials stay out of configs,
+source control and logs. Live tests require explicit bounded budgets; use deterministic fixtures in CI.
+
+Guided setup should inspect the repository first, then suggest roots, documentation scope, TypeScript
+projects/aliases and configuration. AI may help with ambiguous choices. Show concrete proposed
+changes and data that would leave the machine before the first cloud operation. Make the first run
+small, explain missing prerequisites, and preserve an existing setup. Do not advertise unsupported
+languages, frameworks, providers or adapter write operations. The cloud dashboard can then show
+project readiness, coverage, progress, review batches and usage.
+
+## Evaluation and release criteria
+
+Use public-safe fixtures covering no docs, partial docs, stale tickets, conflicting documentation,
+same wording in different domains, changed requirements and asynchronous consumers. Freeze expected
+findings before measurement, and supplement deterministic checks with separately reported, budgeted
+live-model evaluations and a private real-project pilot.
+
+Required cases include invalid/misattributed citations, generated-doc feedback loops, approval under
+an approved directory without content review, stale/forged/unauthorized approvals, changes after
+approval, rename/delete, supersession, conflicting effective scopes, concurrent reviewers, human edits,
+duplicate/retried writes, partial publication failure, offline saved queries and stale MCP clients.
+Hosted work adds tenant isolation, credential handling, cancellation and usage/billing recovery tests.
+
+Record source/config/model revisions, expected relationships, retrieval within declared budgets,
+missed consumers, incorrect claims, useful discoveries, review time, edits/rejections, query/generation
+latency, cache reuse and cost. Approval rate alone is not accuracy. Set quality/performance targets
+after obtaining the first baseline; do not invent pass thresholds or imply complete business coverage.
+
+Keep deterministic tests, provider-dependent integration tests, browser tests and real-project
+evaluation distinct. Existing browser/live-authentication, larger-graph and genuine fresh-cloud
+restoration gaps remain tracked in [ROADMAP.md](ROADMAP.md) and
+[ENVIRONMENT-VALIDATION.md](ENVIRONMENT-VALIDATION.md); this plan does not close them.
+Only advertise capabilities after their relevant validation. Preserve the current core/toolkit
+boundary, snapshot provenance, licenses and supported local installation through each increment.
+
+## Commercial direction and decisions still open
+
+The proposed commercial value is ongoing rule review, reconciliation and source synchronization.
+Managed AI reduces setup friction and can be offered separately from the collaboration service.
+
+| Offering | Proposed scope |
+| --- | --- |
+| Open-source toolkit | Local extraction/graphs/queries/MCP, portable decision records and file workflows |
+| Hosted companion | Shared review queues, permissions/history, source synchronization, managed PRs and organization administration |
+| Managed inference | Included usage or transparent metered credits with explicit budgets; customers can also choose local tools or supported BYOK |
+| Enterprise options | Evaluate self-hosting, organizational controls, deployment needs and support from customer evidence |
+
+No prices, margins, provider commitments or subscription terms are set. Keep workspace/team pricing
+and AI consumption understandable and separable. Validate review burden, recurring usefulness and
+actual model/hosting cost before choosing a pricing model.
+
+The recommendation is to retain Apache-2.0 for the toolkit and evaluate the companion's commercial
+license separately. The maintainer is open to future licensing changes, but no change is selected.
+Existing Apache releases retain their granted permissions; future changes require the rights to
+the affected code and preservation of applicable third-party licenses, notices and attribution.
+
+Resolve these decisions in small ADRs as their milestones approach:
+
+- Claim identity, derivation format, approval authenticity, revocation/supersession and legacy migration.
+- Domain/shared-contract ownership, scope/exception resolution and when approved decisions take effect.
+- Canonical source selection, review-record storage/export and local/cloud synchronization protocol.
+- Companion repository/layout, hosting stack, identity/tenancy, retention and operating budget.
+- First managed provider, direct versus hosted BYOK, supported models and provider commercial terms.
+- Usage units, cache/retry/failed-job charges, budget enforcement, pricing and billing policy.
+- Adapter-specific write capabilities, revision checks and failure recovery.
+- License/product boundaries and any enterprise/self-hosting commitments.
+
+## Next handoff
+
+1. Resolve and publish the identity/kind blocker patch under M0, then obtain a genuine consumer re-run.
+2. Complete the remaining [1.0 tasks](RELEASE-1.0-PLAN.md) and review acceptance without waiting for the website or managed AI.
+3. Design M1's minimal records and compatibility rules, then implement M2 on bounded public fixtures.
+4. Review real extraction/review results before committing to hosted scope, paid operation or more adapters.
+
+Maintain this plan as milestones become concrete, linking implementation PRs, ADRs and validation
+evidence. Keep [ROADMAP.md](ROADMAP.md) as the concise index of delivered capability and remaining work.

package/docs/extraction-manifest.json

@@ -108,7 +108,7 @@
       "destinationPath": "package.json",
       "sourceSha256": "a575dbb2fed8c554b95e8e9b3e03a0c21cab1be7249860bbebc18e046b2ff78d",
       "modified": true,
-      "destinationSha256": "c7a5cbf191d699a51a22fb961ba84e9f73521c0cc332c697f67a9267812de9ee"
+      "destinationSha256": "897f14e438ff7e639f8a906c21fa8e436285180ef05dc6f3c5f73bb94c586ed6"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/LICENSE",
@@ -143,7 +143,7 @@
       "destinationPath": "packages/core/package.json",
       "sourceSha256": "2a29066eb8452f22fafcb06bb035a84dda93c5705dba32aba600a1b7e5aaf19c",
       "modified": true,
-      "destinationSha256": "b7ab260df2ff6005788e6891449205b9b9c9f96aca13b680578a4f776aa21b52"
+      "destinationSha256": "96b88f6a7de48d24b24697fb8824bf46f340eec8723aed19b06684d21784c1fb"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/src/core.ts",
@@ -192,7 +192,7 @@
       "destinationPath": "scripts/check-publication.mjs",
       "sourceSha256": "88692c21d34cef2d2e5b20c92ab3ec26cbe6336889dbb7b534c681ded7f466b2",
       "modified": true,
-      "destinationSha256": "546465bb9907051ebbae9f1c421b8b7be23414ce51c44891092d0fb793f67e8b"
+      "destinationSha256": "7db15ce23e217d8bc14772ff1287dfff0f81e9f402b3d8a5053d386736e8c078"
     },
     {
       "sourcePath": "tools/context-graph/scripts/generate-third-party-notices.mjs",
@@ -283,7 +283,7 @@
       "destinationPath": "src/extraction/document.ts",
       "sourceSha256": "62a2da37d8cc0637b192b7e70ae7a0dce72244d335da9df0e0ad9b0eb7c4e1f1",
       "modified": true,
-      "destinationSha256": "de198e73b3b2c828c99bb35c806461dba06526df9ae94592926d26346fbefe79"
+      "destinationSha256": "0235abe0e2a7a0cb06495027c5dc240cf5b0658faabbdc01d0006fa3b456432c"
     },
     {
       "sourcePath": "tools/context-graph/src/git.test.ts",
@@ -311,14 +311,14 @@
       "destinationPath": "src/application/hydrator.test.ts",
       "sourceSha256": "95f20a526fe69ce3a506ef01da1c20827e09d631a34126e781a07979cc43de07",
       "modified": true,
-      "destinationSha256": "bbd264bf4224632f3e0fea81718910fab4dd5f8e79680faccf61059219bf9dde"
+      "destinationSha256": "9baaacb29c863abdb48c96b054a7f430ce18784badfe585ec5ee88a17f21c0bd"
     },
     {
       "sourcePath": "tools/context-graph/src/hydrator.ts",
       "destinationPath": "src/application/hydrator.ts",
       "sourceSha256": "bb41c5b53b26da10274d8b967b99c78ff12b485df16bfc66445252e35c94fb9d",
       "modified": true,
-      "destinationSha256": "8c751fe04922d1117728672b78a1de2d6f42f403e9d506f387c95661e641a5c0"
+      "destinationSha256": "356dcec76c68e76492a56fd17017e1809f8cc30f237bfe540c827ade8337ad88"
     },
     {
       "sourcePath": "tools/context-graph/src/index.ts",
@@ -444,14 +444,14 @@
       "destinationPath": "src/extraction/semantic.test.ts",
       "sourceSha256": "908fe8166dd63f499c28b2c4d20db2e0110b453f66421b2154461287c2d94dac",
       "modified": true,
-      "destinationSha256": "77958d8fb6d384d55f53c3ab200a7f812a951365e1c08e3ba35c93ef44bddcb3"
+      "destinationSha256": "94c79552f70a891888a6df342fde4cd0ac097344f779f9339c3cb3140a3729a6"
     },
     {
       "sourcePath": "tools/context-graph/src/semantic.ts",
       "destinationPath": "src/extraction/semantic.ts",
       "sourceSha256": "1a41fb3fc5a9508c76be59d1c50b74d70ec96411fcbb7f63b0e098c1813d8473",
       "modified": true,
-      "destinationSha256": "9872f2b8ac3bd14f33194d76082fecf0fd34325a6e74b2397f538898aa8fe21e"
+      "destinationSha256": "eb31d432f0cbb7bd6799562a7e514aa04bbbd2df221f4ef916989eeeea3997f0"
     },
     {
       "sourcePath": "tools/context-graph/src/snapshot-checks.test.ts",
@@ -607,17 +607,20 @@
     "docs/ADR-012-impact-ranking.md",
     "docs/ADR-013-relative-module-requests.md",
     "docs/ADR-014-routing-declarations.md",
+    "docs/ADR-015-repository-document-identity.md",
     "docs/CLOUD-ENVIRONMENT.md",
     "docs/CONSUMER-TRIAL.md",
     "docs/ENVIRONMENT-VALIDATION.md",
     "docs/IMPACT-EVALUATION.md",
     "docs/MIGRATING-TO-WEFTLET.md",
     "docs/PROVIDERS.md",
+    "docs/RELEASE-1.0-PLAN.md",
     "docs/RELEASING.md",
     "docs/ROADMAP.md",
     "docs/SOURCE-INVENTORY.md",
     "docs/VALIDATION.md",
     "docs/VIEWER.md",
+    "docs/WEFTLET-2.0-PLAN.md",
     "docs/architecture-baseline.json",
     "docs/architecture-policy.md",
     "docs/extraction-manifest.json",
@@ -743,6 +746,8 @@
     "src/extraction/module-request.ts",
     "src/extraction/providers.test.ts",
     "src/extraction/providers.ts",
+    "src/extraction/repository-nodes.test.ts",
+    "src/extraction/repository-nodes.ts",
     "src/extraction/routing.test.ts",
     "src/extraction/routing.ts",
     "src/extraction/scip-project.test.ts",
@@ -773,6 +778,7 @@
     "tests/rdf.test.ts",
     "tests/routing.test.ts",
     "tests/runtime.test.ts",
+    "tests/semantic-identity.test.ts",
     "tests/snapshot-lifecycle.test.ts"
   ],
   "publicationAuthorization": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weftlet/toolkit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Evidence-backed context graphs for AI development agents: product intent, contracts, code, tests and runtime behavior",
   "license": "Apache-2.0",
   "type": "module",
@@ -63,7 +63,7 @@
     "n3": "2.7.2",
     "rdf-validate-shacl": "0.6.5",
     "sparqljs": "3.7.4",
-    "@weftlet/core": "^0.2.0"
+    "@weftlet/core": "^0.2.1"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",