@skein-code/cli 0.3.17 → 0.3.19

package/docs/NEXT_STEPS.md

@@ -9,7 +9,7 @@ one of the milestones below.
 
 - Product name: `Skein`; primary executable: `skein`.
 - Compatibility executables: `mosaic` and `mosaic-code`.
-- Current repository version: `0.3.16`.
+- Current repository version: `0.3.19`.
 - Runtime requirement: Node.js `>=22.16.0` (the runtime uses unflagged
   `node:sqlite` with FTS5, and current CLI/build dependencies require this
   Node 22 baseline).
@@ -41,8 +41,8 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package is `skein-code-cli-0.3.16.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.16.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.19.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.19.tgz.sha256`, and CI
 retains the checksum beside the package metadata. The checksum is deliberately
 not copied into this packaged document because doing so would change the
 archive it describes.
@@ -54,6 +54,48 @@ short-height case. The current full-suite count is recorded from the latest
 
 ## Recommended Order
 
+### P0-C: Local Context Engine v2 foundations
+
+Version `0.3.19` moves the persisted local index to schema v3 and records
+TypeScript compiler AST definitions, calls, and relative import facts beside
+each content hash. Old schema v2 indexes rebuild instead of crossing the parser
+contract. Python and SQL remain offline through bounded syntax-aware fallbacks;
+this release does not claim equivalent AST coverage for those languages.
+
+Matching definitions expand the lexical query, NodeNext `.js` imports resolve
+to indexed TypeScript sources, and import/call neighbors receive a bounded graph
+score. A minimum informative-term coverage removes low-value one-word matches,
+with a fallback to the original ranked candidates when no sufficiently covered
+result exists. Each hit carries generation, SHA-256 content hash, matched and
+expanded terms, and a bm25/path/symbol/phrase/graph score breakdown. Query-cache
+hits and misses are visible while cache entries remain generation-bound.
+
+The checked-in `context-benchmark-v2` fixture covers eight TypeScript, Python,
+SQL, CJK, Markdown, and mixed-language cases across ten files. The first
+expanded run failed its preselected useful-token threshold at `0.348`; the
+implementation reached `0.729` while Recall@5/10/20 and MRR remained `1.0`,
+stale-hit rate stayed `0`, warm p95 was below 10 ms, and incremental indexing
+reused every fixture file. Git-recency, diagnostics ranking, broader language
+AST adapters, and production-scale calibration remain follow-up slices.
+
+### P0-E: Token Economy measurement and bounded schema disclosure
+
+Version `0.3.18` adds the repository-owned `token-economy-benchmark-v1`
+deterministic replay. Its seven retrieval, large-output, CJK, and repeated
+zero-hit fixtures compare the legacy ceilings with the adaptive budget and
+firewall policies while requiring complete evidence and recovery coverage.
+The replay reports a 36.7% estimated-input reduction; this is a deterministic
+budget measurement, not a provider billing or task-success claim.
+
+MCP tool definitions are now marked for progressive disclosure. Catalogs of
+eight or fewer eligible tools remain fully visible; larger catalogs disclose a
+deterministically ranked maximum of eight schemas. Selected schemas retain
+their registry order and remain loaded for the current run, and Token Ledger
+receipts record the deferred count. MCP tools remain `network` operations and
+hidden tool calls remain rejected by the existing boundary. This release does
+not defer MCP connection or remote `listTools` discovery and does not claim the
+provider-cache or Context Compaction 2.0 follow-up work is complete.
+
 ### P0-D: Repository reuse and calibrated duplication enforcement
 
 Version `0.3.14` added the prompt ladder and pre-write `ReuseReceipt`. Version
@@ -174,12 +216,12 @@ Implementation progress:
   concrete paths involved. `skein doctor` surfaces this as `legacyCompatibility`
   so users see the removal timeline before aliases disappear.
 
-### P1: Local Context Engine Reliability And Benchmarking
+### P0-C: Local Context Engine Reliability And Benchmarking
 
 Keep retrieval local and measurable as the repository grows. Content hashes,
-generation-keyed query caching, overlap-aware packing, adaptive budgets, and
-targeted known-change refresh are now implemented. The next retrieval slice is
-language adapters and the expanded multilingual benchmark.
+generation-keyed query caching, overlap-aware packing, adaptive budgets,
+targeted known-change refresh, TypeScript AST facts, import adjacency, score
+provenance, and the expanded multilingual benchmark are now implemented.
 
 Definition of done:
 
@@ -200,8 +242,9 @@ Implementation progress:
   atomically persist before the next turn in TUI or headless mode.
 - Size/mtime/ctime reconciliation closes the direct-new-query zero-hit window;
   repeated empty or unchanged searches stop through the recovery circuit.
-- Remaining work is broader language adapters and production-scale benchmark
-  calibration; the reproducible benchmark pipeline already exists.
+- The v2 fixture is an enforced regression test, including a graph-only import
+  neighbor and a no-stale-hit gate. Remaining work is git-recency/diagnostics
+  signals, broader language AST adapters, and production-scale calibration.
 
 ### P1: Multi-Agent Scheduler And Team UX
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,12 @@
   },
   "skein": {
     "releaseNotes": [
+      "Local index v3 records TypeScript AST definitions, calls, and relative import adjacency for graph-assisted retrieval",
+      "Context hits expose generation, content hash, matched terms, and bm25/path/symbol/phrase/graph score provenance",
+      "Context benchmark v2 locks multilingual recall, MRR, useful-token, stale-hit, incremental-index, and warm-latency gates",
+      "Large MCP catalogs now disclose at most eight request-relevant schemas per run while preserving network permissions",
+      "Token Ledger receipts report deferred progressive schemas and selected definitions remain stable across tool turns",
+      "A deterministic Token Economy replay benchmark guards evidence, output-firewall, and no-progress invariants",
       "Calibrated Type-1/2 duplication matches now block completion until reuse or exact audited suppression",
       "Type-3 duplication remains warning-only and Type-4 semantic equivalence remains explicitly unsupported",
       "Duplication benchmark fixtures report deterministic recall, precision, false-positive rate, and latency",
@@ -58,6 +64,7 @@
     "test:pty": "sh test/pty/run-visual.sh",
     "benchmark:context": "tsx scripts/benchmark-local-index.ts",
     "benchmark:duplication": "tsx scripts/benchmark-duplication.ts",
+    "benchmark:token-economy": "tsx scripts/benchmark-token-economy.ts",
     "verify:package": "node scripts/verify-package.mjs",
     "release:verify": "npm run check && npm run verify:package --",
     "typecheck": "tsc --noEmit",
@@ -77,6 +84,7 @@
     "react": "^19.2.3",
     "string-width": "^8.2.2",
     "strip-ansi": "^7.2.0",
+    "typescript": "^5.9.3",
     "yaml": "^2.8.2",
     "zod": "^4.4.3"
   },
@@ -86,7 +94,6 @@
     "@types/react": "^19.2.7",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "overrides": {