@weftlet/toolkit 0.1.2 → 0.2.1

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

@@ -24,7 +24,7 @@
       "destinationPath": "THIRD_PARTY_NOTICES.md",
       "sourceSha256": "c98c42f3c3c74f4c4f38f45b785ea15de439ad6471d82040d13100b36616b01e",
       "modified": true,
-      "destinationSha256": "1c8bb26c7385fef7d391db9c89797b6f45bf6c5b102d7e832295783eb6c28d1a"
+      "destinationSha256": "cd1b40a873371c1fb20599ae8dc5d1131ea4ba650c1f4151415e2cb038339d8d"
     },
     {
       "sourcePath": "tools/context-graph/action/action.yml",
@@ -108,7 +108,7 @@
       "destinationPath": "package.json",
       "sourceSha256": "a575dbb2fed8c554b95e8e9b3e03a0c21cab1be7249860bbebc18e046b2ff78d",
       "modified": true,
-      "destinationSha256": "017fe298662e434efa27d4f21a0adb0d857fa373a6199ed2d623a6c630c5b451"
+      "destinationSha256": "897f14e438ff7e639f8a906c21fa8e436285180ef05dc6f3c5f73bb94c586ed6"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/LICENSE",
@@ -143,14 +143,14 @@
       "destinationPath": "packages/core/package.json",
       "sourceSha256": "2a29066eb8452f22fafcb06bb035a84dda93c5705dba32aba600a1b7e5aaf19c",
       "modified": true,
-      "destinationSha256": "9dbd393a312bb6a992b53d2624279b62991e64609beb506744186614f9b194cf"
+      "destinationSha256": "96b88f6a7de48d24b24697fb8824bf46f340eec8723aed19b06684d21784c1fb"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/src/core.ts",
       "destinationPath": "packages/core/src/core.ts",
       "sourceSha256": "cb3f4eb7bfe9f458494607406664445a276aad37235930a043d400ea9211ed16",
       "modified": true,
-      "destinationSha256": "64a30913c01ff2f3e112a6bcafbc142cb91fc5482f01b2aa90fae9382252dbfa"
+      "destinationSha256": "0287d0640f2ff078da19be1439d02fcab22998262562d4af7b5f26ddca0839f4"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/src/index.ts",
@@ -192,21 +192,21 @@
       "destinationPath": "scripts/check-publication.mjs",
       "sourceSha256": "88692c21d34cef2d2e5b20c92ab3ec26cbe6336889dbb7b534c681ded7f466b2",
       "modified": true,
-      "destinationSha256": "6aa819a74fea8b161396b3a8c52e8e86ea2db856bc10ffbfdebaf22fa0af2cfe"
+      "destinationSha256": "7db15ce23e217d8bc14772ff1287dfff0f81e9f402b3d8a5053d386736e8c078"
     },
     {
       "sourcePath": "tools/context-graph/scripts/generate-third-party-notices.mjs",
       "destinationPath": "scripts/generate-third-party-notices.mjs",
       "sourceSha256": "42cd4996ecab49b008634958e47b0a9eadf9ea775678b8daaeeafea59eaabadf",
       "modified": true,
-      "destinationSha256": "5caf7a08a42e6c482a5c46d87e71413a6776a5af34685dbe98a16ba7035f5c0c"
+      "destinationSha256": "6e9ddb9a0985e2c39d8386168871efeb2589f6bc1bf8c24684cf6c546eced1b2"
     },
     {
       "sourcePath": "tools/context-graph/src/agent-context.test.ts",
       "destinationPath": "src/application/agent-context.test.ts",
       "sourceSha256": "cb87b9b7e18ae5d8ba39d4ebf1d45556479d6efb3ffa75276bc6164ee2bf30f1",
       "modified": true,
-      "destinationSha256": "f1ed006615ae0d07fb924c60fccad90a3f8cd4e5f12898d4a07db0a5fa65e7d5"
+      "destinationSha256": "c72ba1d20d1ad85ee295a7041e85a99cf973b6114eff21524d808997929e3184"
     },
     {
       "sourcePath": "tools/context-graph/src/agent-context.ts",
@@ -248,14 +248,14 @@
       "destinationPath": "src/configuration/config.test.ts",
       "sourceSha256": "70bcda6d6b48ff6fa03223c9420fe3e0e3e32c688e0a14f11034515e0707dee4",
       "modified": true,
-      "destinationSha256": "ae67cb42f86dbd72d09eac20a0755080bf9394e849dc4fdfdfe0a43b0296c6b2"
+      "destinationSha256": "ff4d15018ec35d21a95c589cf2c74bce2e340f9042b2d3ecaabca5889609e3aa"
     },
     {
       "sourcePath": "tools/context-graph/src/config.ts",
       "destinationPath": "src/configuration/config.ts",
       "sourceSha256": "e9ee8cf2134d274aa6f6a21545959fbec97e958181d9032c073293f28e04d6ca",
       "modified": true,
-      "destinationSha256": "ce6550967829b74147909121735c4dccf70982c3f9ee9ddc860b4f63535d5de0"
+      "destinationSha256": "5e34e4dfa38219570bd6f13239609b432830e76162f44a768a929895f66dc02a"
     },
     {
       "sourcePath": "tools/context-graph/src/core.ts",
@@ -283,7 +283,7 @@
       "destinationPath": "src/extraction/document.ts",
       "sourceSha256": "62a2da37d8cc0637b192b7e70ae7a0dce72244d335da9df0e0ad9b0eb7c4e1f1",
       "modified": true,
-      "destinationSha256": "819372a1ba01ed2204e2ed620d4afefb03ab8b7431e77e02f2b61bc605807124"
+      "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": "83ca72d394d9eac8eef5dbc9438c7914442dbad3bbaa07c33f1e756e6d11fd39"
+      "destinationSha256": "9baaacb29c863abdb48c96b054a7f430ce18784badfe585ec5ee88a17f21c0bd"
     },
     {
       "sourcePath": "tools/context-graph/src/hydrator.ts",
       "destinationPath": "src/application/hydrator.ts",
       "sourceSha256": "bb41c5b53b26da10274d8b967b99c78ff12b485df16bfc66445252e35c94fb9d",
       "modified": true,
-      "destinationSha256": "c95592ccb8626e8d3629f35d24e51d9d99be698c8ae270c794df47e4b3a46d14"
+      "destinationSha256": "356dcec76c68e76492a56fd17017e1809f8cc30f237bfe540c827ade8337ad88"
     },
     {
       "sourcePath": "tools/context-graph/src/index.ts",
@@ -388,14 +388,14 @@
       "destinationPath": "src/graph/query.test.ts",
       "sourceSha256": "ba07c52566da979fcbb451b0c0c99b466521993cb49415ff8b35df2b01d4ecaf",
       "modified": true,
-      "destinationSha256": "e0030981026a6643d8032174f37a0a41b17724ee6a86dae55e6b12c51f5de77f"
+      "destinationSha256": "68d7405765dec5975370f79caaf8708db42dd3dd464a7ec9c3919c796ee81b79"
     },
     {
       "sourcePath": "tools/context-graph/src/query.ts",
       "destinationPath": "src/graph/query.ts",
       "sourceSha256": "4d67f87ca660cefe9686fb5b775f86a997a25d539819ea81d321c8bd1e0aaa39",
       "modified": true,
-      "destinationSha256": "93e813d2e70d09522418e07f9ffeb36d71795c026099a8b57559b0c10b150a76"
+      "destinationSha256": "ead61dfde748cd1a02c8b1a14dc729173a6b85ec3b8213af2bd5169c60b70253"
     },
     {
       "sourcePath": "tools/context-graph/src/request.test.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": "64b4e55294ab37bc84a1c2ad0a8a563003d8ad2329e224ef0c6822965b14d257"
+      "destinationSha256": "eb31d432f0cbb7bd6799562a7e514aa04bbbd2df221f4ef916989eeeea3997f0"
     },
     {
       "sourcePath": "tools/context-graph/src/snapshot-checks.test.ts",
@@ -479,7 +479,7 @@
       "destinationPath": "src/extraction/static.ts",
       "sourceSha256": "f8dcff3e10361314c06911dc7cec1e2cb0f8d9af68a6c61a30b2a741c5c3a385",
       "modified": true,
-      "destinationSha256": "39ada50a57e2130d27c22eb18531c3feb7160004b198eb5904950227e57012df"
+      "destinationSha256": "94190f11651b21372b2c3a834e30cde5d333893bfad0b66755e5f698608d2fdb"
     },
     {
       "sourcePath": "tools/context-graph/src/storage.ts",
@@ -602,15 +602,25 @@
     "docs/ADR-007-toolkit-modules.md",
     "docs/ADR-008-weftlet-packages.md",
     "docs/ADR-009-release-automation.md",
+    "docs/ADR-010-committed-source-indexing.md",
+    "docs/ADR-011-explicit-document-links.md",
+    "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",
@@ -618,6 +628,47 @@
     "docs/licenses/lru-cache-11.5.3-BlueOak.md",
     "docs/licenses/negotiate-1.0.1-BSD.txt",
     "docs/licenses/spark-md5-3.0.2-MIT.txt",
+    "evaluations/dispatch/README.md",
+    "evaluations/dispatch/baseline.json",
+    "evaluations/dispatch/cases.json",
+    "evaluations/dispatch/context-graph.config.json",
+    "evaluations/dispatch/project/README.md",
+    "evaluations/dispatch/project/docs/delivery-flow.md",
+    "evaluations/dispatch/project/docs/dispatch-contract.md",
+    "evaluations/dispatch/project/docs/dispatch-policy.md",
+    "evaluations/dispatch/project/package.json",
+    "evaluations/dispatch/project/routing/dispatch.json",
+    "evaluations/dispatch/project/src/api/dispatch.ts",
+    "evaluations/dispatch/project/src/archive/consumer.ts",
+    "evaluations/dispatch/project/src/audit/consumer.ts",
+    "evaluations/dispatch/project/src/contracts/dispatch-plan.ts",
+    "evaluations/dispatch/project/src/contracts/dispatch-receipt.ts",
+    "evaluations/dispatch/project/src/contracts/dispatch-request.ts",
+    "evaluations/dispatch/project/src/dispatch/executor.ts",
+    "evaluations/dispatch/project/src/dispatch/outcomes.ts",
+    "evaluations/dispatch/project/src/dispatch/planner.ts",
+    "evaluations/dispatch/project/src/dispatch/policy.ts",
+    "evaluations/dispatch/project/src/dispatch/retry.ts",
+    "evaluations/dispatch/project/src/refund/planner.ts",
+    "evaluations/dispatch/project/src/refund/policy.ts",
+    "evaluations/dispatch/project/src/transport/queue.ts",
+    "evaluations/dispatch/project/test/archive.test.ts",
+    "evaluations/dispatch/project/test/dispatch.test.ts",
+    "evaluations/dispatch/project/test/policy.test.ts",
+    "evaluations/dispatch/project/test/refund.test.ts",
+    "evaluations/dispatch/project/tsconfig.json",
+    "evaluations/dispatch/relative-imports-baseline.json",
+    "evaluations/dispatch/routing-baseline.json",
+    "evaluations/dispatch/routing-protocol.md",
+    "evaluations/dispatch/routing.config.json",
+    "evaluations/weftlet/baseline.json",
+    "evaluations/weftlet/cases.json",
+    "evaluations/weftlet/context-graph.config.json",
+    "evaluations/weftlet/document-links-baseline.json",
+    "evaluations/weftlet/document-only.mjs",
+    "evaluations/weftlet/ranking-baseline.json",
+    "evaluations/weftlet/source-project-baseline.json",
+    "evaluations/weftlet/source-project.config.json",
     "examples/generic-typescript/context-graph.oml.config.json",
     "examples/pipeline/context-graph.config.json",
     "examples/pipeline/docs/admission.md",
@@ -653,6 +704,14 @@
     "scripts/check-restoration.mjs",
     "scripts/clean-build.mjs",
     "scripts/cloud-install.sh",
+    "scripts/evaluation/protocol.test.ts",
+    "scripts/evaluation/protocol.ts",
+    "scripts/evaluation/run.test.ts",
+    "scripts/evaluation/run.ts",
+    "scripts/evaluation/score.test.ts",
+    "scripts/evaluation/score.ts",
+    "scripts/git-content.mjs",
+    "scripts/inventory.test.ts",
     "scripts/npm-auth.mjs",
     "scripts/npm-auth.test.ts",
     "scripts/npm-command.mjs",
@@ -676,14 +735,30 @@
     "src/application/overlay.ts",
     "src/application/saved-evidence.ts",
     "src/cli.ts",
+    "src/configuration/scip-project.ts",
     "src/extraction/codex-auth.test.ts",
     "src/extraction/codex-auth.ts",
+    "src/extraction/codex-command.test.ts",
+    "src/extraction/codex-command.ts",
+    "src/extraction/document-references.ts",
+    "src/extraction/document.test.ts",
+    "src/extraction/module-request.test.ts",
+    "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",
+    "src/extraction/scip-project.ts",
+    "src/extraction/semantic-process.test.ts",
     "src/extraction/semantic-process.ts",
     "src/governance/governance.test.ts",
     "src/governance/governance.ts",
     "src/graph/authority.ts",
+    "src/graph/ranking.test.ts",
+    "src/graph/ranking.ts",
     "src/graph/rdf.ts",
     "src/infrastructure/module-resolution.ts",
     "src/interfaces/doctor.ts",
@@ -701,7 +776,9 @@
     "tests/module-boundaries.test.ts",
     "tests/rdf-ontology.test.ts",
     "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.1.2",
+  "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",
@@ -59,13 +59,15 @@
     "@opentelemetry/sdk-trace-base": "2.2.0",
     "@sourcegraph/scip-typescript": "0.4.0",
     "import-meta-resolve": "4.2.0",
+    "mdast-util-from-markdown": "2.1.0",
     "n3": "2.7.2",
     "rdf-validate-shacl": "0.6.5",
     "sparqljs": "3.7.4",
-    "@weftlet/core": "^0.1.2"
+    "@weftlet/core": "^0.2.1"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",
+    "@types/mdast": "4.0.4",
     "@types/n3": "1.26.1",
     "@types/node": "20.19.11",
     "@typescript-eslint/parser": "8.72.0",
@@ -115,6 +117,7 @@
     "release:prepare": "pnpm context-graph:publication-check && node scripts/release.mjs --prepare",
     "release:publish": "node scripts/release.mjs --publish",
     "govern": "tsx src/cli.ts govern --policy architecture.policy.json --output .context-graph/architecture-report.json",
+    "evaluate:impact": "tsx scripts/evaluation/run.ts",
     "weftlet": "tsx src/cli.ts",
     "changeset": "changeset",
     "release:version": "node scripts/version-packages.mjs"