knodin 0.6.0 → 0.7.3

package/docs/GIT-HISTORY-REVIEW.md

@@ -0,0 +1,39 @@
+# Bounded Git-history review signals
+
+`knodin review` and the MCP gateway's `review` operation return `signals` beside
+the compatibility `riskScore`. The signal groups stay separate:
+
+- `graphImpact`: changed files and affected flows from indexed relationships;
+- `testGaps`: missing test-path/reference facts;
+- `structuralCentrality`: inbound, outbound, and total indexed references for
+  each changed symbol;
+- `history`: rename-aware churn, co-change commit facts, and coupling ratios.
+
+History output includes the exact contributing commit IDs, availability,
+confidence, configured bounds, commands executed, analyzed counts, truncation,
+and explicit omissions. Results are sorted deterministically. CLI and MCP output
+also retain the review's graph `staleness` field.
+
+## Bounds and unavailable states
+
+The defaults are 250 commits, 25 changed files, 100 related-file facts, a
+2-second timeout per Git command, and an 8 MiB output ceiling. Review uses one
+bounded `git log` pass after HEAD and shallow-state probes, and caches facts by
+repository, HEAD, requested files, and bounds. User-provided file paths must be
+repository-relative; revisions never enter the history command.
+
+`shallow`, `unborn`, `git-unavailable`, `not-a-repository`, `timeout`, and
+`unavailable` are explicit. Missing history never produces synthetic commits or
+coupling. Shallow results contain only locally present commits and disclose that
+omission. Commit, file, and related-file truncation likewise names what was
+omitted and why.
+
+## Interpretation limit
+
+Co-change and coupling show correlation in the inspected history only. They do
+not assert causation, defect likelihood, ownership, or mandatory remediation.
+Treat them as review context alongside graph impact, test gaps, and structural
+centrality—not as an opaque score or automated decision.
+
+The reproducible synthetic-DAG evidence, raw replay, resource measurement, and
+verifier are under `benchmarks/evaluations/c85-git-history/`.

package/docs/MCP.md

@@ -4,6 +4,10 @@ knodin exposes exactly one MCP tool named `knodin`. Capabilities such as
 context, explain, review, search, docs, doctor, repositories, and systems are
 operations of that gateway, not separate top-level tools.
 
+Use `operation: "evidence"` for deterministic `locate`, `outline`, `evidence`,
+and `expand` source delivery with a verified complete-file hash handshake and
+recoverable hard-budget continuations. See `docs/PROGRESSIVE-EVIDENCE.md`.
+
 ## Choose a scope
 
 - **Personal:** `knodin init --scope personal` configures detected clients with
@@ -98,3 +102,14 @@ If the handshake fails:
 
 MCP requests never trigger update-network checks. Cached update state is
 available through the `doctor` operation without changing stdio framing.
+When local diagnostics have been explicitly enabled for the repository, an MCP
+operation failure records the same bounded, sanitized failure envelope as the
+CLI. It never records request arguments, queries, source, or raw responses. Use
+the CLI `knodin diagnostics collect` and `inspect` workflow to review and share
+support evidence; no MCP failure is uploaded automatically.
+
+The `review` operation serializes graph impact, test gaps, structural
+centrality, and bounded Git-history facts separately. Churn, co-change, and
+coupling include contributing commits, bounds, omissions, confidence, and the
+response's graph freshness. See `docs/GIT-HISTORY-REVIEW.md`; co-change is
+correlation only and never an ownership, defect, or remediation assertion.

package/docs/PROGRESSIVE-EVIDENCE.md

@@ -0,0 +1,37 @@
+# Progressive source evidence
+
+`knodin evidence` returns exact local source through four deterministic levels:
+
+1. `locate` — stable file identity, path, hash, size, freshness, and confidence.
+2. `outline` — top-level declaration signatures and exact line ranges.
+3. `evidence` — requested verbatim source lines with edit anchors intact.
+4. `expand` — the complete verbatim file within caller-selected hard budgets.
+
+CLI:
+
+```bash
+knodin evidence locate src/widget.ts
+knodin evidence evidence src/widget.ts --start 10 --end 30
+knodin evidence evidence src/widget.ts --continuation <evidence-handle> \
+  --baseline-hash <sha256> --baseline-bytes <bytes>
+```
+
+The single MCP gateway uses `operation: "evidence"`, `file`, and
+`evidenceLevel`. Supply a returned `continuation` to recover omitted source.
+Every response names returned and omitted material, a reason, whether more
+exists, a stable continuation and evidence handle, freshness, confidence, the
+path taken, and exact item/UTF-8-byte/local-token-estimate budgets.
+The mandatory recoverability envelope requires at least 1,600 effective bytes
+(the lower of the byte cap and four times the local token-estimate cap); smaller
+requests fail closed instead of dropping contract fields.
+
+Source omission occurs only when a server-issued evidence handle is valid and
+both `baselineHash` and `baselineBytes` equal the current complete local file.
+Missing or partial metadata/handle, a stale/tampered hash, source changed since
+a handle was issued, or a renamed path selects a named `full-*` recovery path.
+Invalid or tampered handles fail closed. Inputs
+must identify an exact repository-relative regular file; ambiguous selection,
+absolute/traversal paths, and symlinks are refused.
+
+This protocol does not summarize source and does not support token-savings or
+task-success claims. See the C83 checked-in replay and limitations for bounds.

package/docs/REPOSITORIES-AND-WORKTREES.md

@@ -5,6 +5,7 @@ that discovered repositories form one software system.
 
 ```bash
 knodin repos discover <root...> --depth 4 --linked-worktrees=skip
+knodin repos discover <root...> --json --signals
 knodin repos init <root...> --dry-run
 knodin repos status <root...>
 knodin repos doctor <root...>
@@ -23,6 +24,35 @@ Results distinguish:
 - stale linked-worktree metadata;
 - an unrelated repository under the same discovery root.
 
+### Opt-in repository signals
+
+`repos discover --json --signals` adds a deterministic `signals` object to
+every repository record; honest absence is `{}`. Without `--signals`, the JSON
+shape and bytes are unchanged. Linked worktrees inspect their own checkout and
+retain the existing `--linked-worktrees=skip|include` behavior.
+
+Inspection is read-only, offline, credential-free, and restricted to these
+repository-relative markers: `.github/workflows`, `.gitlab-ci.yml`,
+`.circleci/config.yml`, `azure-pipelines.yml`, `Jenkinsfile`,
+`sonar-project.properties`, `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, and
+`.vscode/mcp.json`. Marker contents are never read. Hook-manager detection is
+restricted to `lefthook.yml`, `lefthook.yaml`, `.husky`, and
+`.pre-commit-config.yaml`; Husky content reads are further restricted to
+`.husky/pre-commit`, `.husky/commit-msg`, and `.husky/pre-push`. Only these
+allowlisted regular hook configurations are read, with a combined 64 KiB cap,
+to report `aidevTrackReferenced`. Remote URLs are read
+from local Git configuration and emitted only as sanitized `name`, `host`, and
+`owner` fields—credentials, paths, and repository names are omitted.
+
+Returned fields, when present, are `hookManager`, sorted `markerFiles`, sorted
+`remotes`, `ciProviders`, `agentConfigs`, and `aidevTrackReferenced`. The fixed
+allowlists, 64 KiB hook-content ceiling, 16 KiB Git-output ceiling, discovery
+depth, and existing response budgets bound work and serialization. The command
+performs no writes, network or credential access, source egress, or incremental
+model spend. Marker presence is descriptive only: it does not prove that a
+skill applies or that a detected service is configured correctly. `knodin
+doctor` and the single MCP gateway are unchanged.
+
 Sibling location never establishes system membership or a relationship.
 `repos init` works sequentially and performs each live repository operation in
 a disposable process with a 768 MiB RSS ceiling. A worker that exceeds the

package/docs/SCIP-IMPORT.md

@@ -0,0 +1,57 @@
+# Optional SCIP import
+
+knodin can add compiler-produced SCIP facts to its local graph without running a
+language server. The tier is deliberately opt-in:
+
+```sh
+knodin index --scip path/to/index.scip
+```
+
+The input must be a regular file inside the repository. knodin never discovers,
+downloads, or produces a SCIP index, and a normal `knodin init` or `knodin
+index` does not import one. Repositories without the flag keep the existing
+native and LSIF behavior byte-for-byte at the command boundary.
+
+## Evidence and conflicts
+
+Imported definitions use stable repository/file/range identities, `SCIP_*`
+kinds, a summary containing the original SCIP symbol and `scip` provenance,
+`scip_reference`, `scip_relationship_reference`, `scip_implementation`,
+`scip_type_definition`, or `scip_definition` reference kinds, and `scip_import`
+file edges. Native and LSIF facts are not deleted or overwritten. If two tiers
+define the same name, normal ambiguity-safe resolution returns all candidates
+and requires a file, kind, or identity selector. A stale SCIP input is refused
+rather than replacing fresher source-derived evidence.
+
+Every successful index result includes the producer name/version and represented
+languages from the SCIP file plus the exact limits used. Defaults are 64 MiB,
+10,000 documents, 250,000 decoded facts, and 30 seconds. Inputs that are
+missing, malformed, oversized, stale relative to a represented source file, or
+contain absolute, traversal, missing, symlink, or non-file document paths fail
+before the SCIP tier is replaced.
+
+## Known bounds and limitations
+
+- The importer supports standard SCIP `Index`, `Document`, `Occurrence`,
+  `SymbolInformation`, and `Relationship` fields needed for definitions,
+  references, source ranges, and relationships. Unknown protobuf fields are
+  skipped, but unsupported wire types and malformed ranges fail closed.
+- Precision and coverage are bounded by the producer. Checked-in coverage is
+  npm-integrity-pinned `@sourcegraph/scip-typescript@0.4.0` over TypeScript. Its
+  emitted documents omit the optional language field, so the import report says
+  `unknown`; other conforming producers and languages are not certified by C84.
+- The index mtime must be at least as new as every represented source file.
+  This is a conservative local freshness check, not a claim that the producer
+  indexed the exact Git commit or compiler configuration.
+- An import replaces the prior SCIP tier as one snapshot. It does not merge
+  multiple SCIP files, watch an index, start a daemon, or provide live LSP.
+  Live LSP requires a separately approved roadmap item.
+- SCIP local symbols are scoped by document. Relationship flags remain distinct
+  (`reference`, `implementation`, `type-definition`, or `definition`); only an
+  actual cross-file occurrence reference contributes a `scip_import` file edge.
+- The checked-in replay is synthetic and authorizes no superiority,
+  production-readiness, trusted-distribution, or cross-platform claim.
+
+The replay, verifier, raw results, and resource report live under
+`benchmarks/evaluations/c84-scip-import/`; run `npm run verify:c84` entirely
+offline to reproduce them.

package/docs/SIGNED-UPDATES.md

@@ -123,6 +123,11 @@ activating signed checks, the release owners must record:
 This external ceremony is deliberately a release gate rather than generated
 test material masquerading as production trust.
 
+The fail-closed preparation contracts and multi-custodian rehearsal procedure
+are in [`ROOT-CEREMONY-RUNBOOK.md`](ROOT-CEREMONY-RUNBOOK.md). Their import seam
+accepts public material only and always returns `productionActivation: false`;
+it does not alter the production `trust-unconfigured` behavior.
+
 ## Client policy and recovery
 
 The implemented policy modes are `notify-only`, `download-verify-only`,

package/docs/TELEMETRY.md

@@ -40,3 +40,7 @@ Telemetry never persists source, raw tool output, command text, usernames, or
 absolute paths. A measured baseline is an executed, bounded, repository-local
 full-file read; it is not inferred from file counts. Unsupported baselines and
 metrics remain `null` or are counted as unavailable instead of being modeled.
+
+ROI telemetry is separate from troubleshooting diagnostics. Telemetry measures
+product behavior; `knodin diagnostics` retains sanitized failure envelopes and
+creates a user-inspectable support bundle. See `docs/DIAGNOSTICS.md`.

package/docs/releases/0.7.0.md

@@ -0,0 +1,24 @@
+# knodin 0.7.0
+
+This release is the dogfood-readiness release for local code intelligence with
+bounded, user-controlled troubleshooting evidence.
+
+- Adds `knodin diagnostics enable|status|collect|inspect|clear|disable` with a
+  private, bounded local failure journal and redacted support bundles. Nothing
+  is uploaded automatically.
+- Captures sanitized CLI and MCP failure correlation IDs without retaining
+  source, queries, arguments, environment values, credentials, or raw paths.
+- Adds contained execution profiles with explicit platform support and
+  fail-closed behavior when the requested containment cannot be established.
+- Adds structural cold-start routing and checked-in C87 latency evidence while
+  preserving truthful response budgets and freshness metadata.
+- Integrates lifecycle refresh through hook-manager-native Lefthook routing,
+  while preserving repository-owned configuration and distinguishing graph
+  repair from lifecycle reinitialization.
+- Tightens freshness proof, response-budget accounting, package smoke coverage,
+  and roadmap evidence for the completed local feature set.
+
+This ordinary 0.x release is intended for normal installation, including the
+initial Docusign rollout. The external evidence and signed-release gates in
+`roadmap/competitive-roadmap.md` remain open and continue to block GA and
+trusted-distribution claims; publication does not waive or simulate them.

package/docs/releases/0.7.1.md

@@ -0,0 +1,21 @@
+# knodin 0.7.1
+
+This is the first normally published 0.7 release of knodin. It provides local,
+opt-in diagnostics that users can collect and deliberately share when they
+need troubleshooting help; it is not a special dogfood build or prerelease.
+
+- Adds `knodin diagnostics enable|status|collect|inspect|clear|disable` with a
+  private, bounded local failure journal and redacted support bundles. Nothing
+  is uploaded automatically.
+- Captures sanitized CLI and MCP failure correlation IDs without retaining
+  source, queries, arguments, environment values, credentials, or raw paths.
+- Adds contained execution profiles, structural cold-start routing, lifecycle
+  refresh improvements, tighter freshness proof, and truthful response-budget
+  accounting.
+- Corrects the release test suite so the competitive sandbox contract is
+  verified on systems both with and without Bun installed.
+
+This ordinary 0.x release is suitable for installation through npm,
+Artifactory, and Homebrew, including use by Docusign employees. The external
+evidence and signed-release gates recorded in `roadmap/competitive-roadmap.md`
+remain open and continue to block GA and trusted-distribution claims.

package/docs/releases/0.7.2.md

@@ -0,0 +1,21 @@
+# knodin 0.7.2
+
+This is the first normally published 0.7 release of knodin. It provides local,
+opt-in diagnostics that users can collect and deliberately share when they
+need troubleshooting help; it is not a special dogfood build or prerelease.
+
+- Adds `knodin diagnostics enable|status|collect|inspect|clear|disable` with a
+  private, bounded local failure journal and redacted support bundles. Nothing
+  is uploaded automatically.
+- Captures sanitized CLI and MCP failure correlation IDs without retaining
+  source, queries, arguments, environment values, credentials, or raw paths.
+- Adds contained execution profiles, structural cold-start routing, lifecycle
+  refresh improvements, tighter freshness proof, and truthful response-budget
+  accounting.
+- Makes release verification deterministic across macOS and Linux, both with
+  and without Bun, including foreground execution of lifecycle-hook fixtures.
+
+This ordinary 0.x release is suitable for installation through npm,
+Artifactory, and Homebrew, including use by Docusign employees. The external
+evidence and signed-release gates recorded in `roadmap/competitive-roadmap.md`
+remain open and continue to block GA and trusted-distribution claims.

package/docs/releases/0.7.3.md

@@ -0,0 +1,23 @@
+# knodin 0.7.3
+
+This is the first normally published 0.7 release of knodin. It provides local,
+opt-in diagnostics that users can collect and deliberately share when they
+need troubleshooting help; it is not a special dogfood build or prerelease.
+
+- Adds `knodin diagnostics enable|status|collect|inspect|clear|disable` with a
+  private, bounded local failure journal and redacted support bundles. Nothing
+  is uploaded automatically.
+- Captures sanitized CLI and MCP failure correlation IDs without retaining
+  source, queries, arguments, environment values, credentials, or raw paths.
+- Adds contained execution profiles, structural cold-start routing, lifecycle
+  refresh improvements, tighter freshness proof, and truthful response-budget
+  accounting.
+- Makes release verification deterministic across macOS and Linux, both with
+  and without Bun, including foreground execution of lifecycle-hook fixtures.
+- Ensures `configure --scope cli-only` removes repository-detected Knodin MCP
+  configuration even when that agent's CLI is not installed locally.
+
+This ordinary 0.x release is suitable for installation through npm,
+Artifactory, and Homebrew, including use by Docusign employees. The external
+evidence and signed-release gates recorded in `roadmap/competitive-roadmap.md`
+remain open and continue to block GA and trusted-distribution claims.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.6.0",
+	"version": "0.7.3",
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
 	"repository": {
@@ -17,16 +17,21 @@
 	},
 	"type": "module",
 	"bin": {
-		"knodin": "dist/bin/cli.js"
+		"knodin": "dist/bin/launcher.js"
 	},
 	"files": [
 		"dist",
 		"docs/DEAD-CODE-AND-IMPACT.md",
 		"docs/DOCTOR-AND-UPDATES.md",
+		"docs/DIAGNOSTICS.md",
 		"docs/INDEXING-POLICY-AND-PROVENANCE.md",
 		"docs/INSTALLATION.md",
 		"docs/MCP.md",
 		"docs/COMMAND-OUTPUT-COMPRESSION.md",
+		"docs/CONTAINED-EXECUTION.md",
+		"docs/PROGRESSIVE-EVIDENCE.md",
+		"docs/GIT-HISTORY-REVIEW.md",
+		"docs/SCIP-IMPORT.md",
 		"docs/CLI.md",
 		"docs/PT-ACCESS-RECOMMENDATION.md",
 		"docs/REPOSITORIES-AND-WORKTREES.md",
@@ -40,6 +45,10 @@
 		"docs/releases/0.5.0.md",
 		"docs/releases/0.5.1.md",
 		"docs/releases/0.6.0.md",
+		"docs/releases/0.7.0.md",
+		"docs/releases/0.7.1.md",
+		"docs/releases/0.7.2.md",
+		"docs/releases/0.7.3.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",
@@ -63,18 +72,40 @@
 		"test:watch": "vitest --watch",
 		"test:coverage": "tsx scripts/run-vitest-shards.ts --coverage",
 		"scan:sonar": "npm run test:coverage && sh scripts/run-sonar-scan.sh",
+		"mirror:sync": "sh tools/hooks/sync-ghes-mirror.sh",
 		"test:pack-install": "tsx scripts/pack-install-smoke.ts",
 		"test:package-managers": "tsx scripts/package-manager-smoke.ts",
 		"test:naming-screen": "node --test scripts/naming-screen.test.js",
 		"measure:schema": "tsx scripts/measure-tool-schema.ts",
 		"check:dependency-deprecations": "tsx scripts/check-dependency-deprecations.ts",
 		"check:hygiene": "node scripts/check-repository-hygiene.mjs",
+		"check:roadmap": "tsx scripts/check-roadmap.ts",
+		"verify:c79": "tsx scripts/verify-c79.ts",
+		"bench:c80": "tsx benchmarks/evaluations/c80-structural-routing/runner.ts",
+		"verify:c80": "tsx scripts/verify-c80.ts",
+		"bench:c81": "tsx benchmarks/evaluations/c81-powered-benchmark/runner.ts",
+		"verify:c81": "tsx scripts/verify-c81.ts",
+		"bench:c82": "tsx benchmarks/evaluations/c82-compress-diagnose/runner.ts",
+		"verify:c82": "tsx scripts/verify-c82.ts",
+		"bench:c83": "tsx benchmarks/evaluations/c83-progressive-evidence/runner.ts",
+		"verify:c83": "tsx scripts/verify-c83.ts",
+		"bench:c84": "tsx benchmarks/evaluations/c84-scip-import/runner.ts",
+		"verify:c84": "tsx scripts/verify-c84.ts",
+		"bench:c85": "tsx benchmarks/evaluations/c85-git-history/runner.ts",
+		"verify:c85": "tsx scripts/verify-c85.ts",
+		"bench:c86": "tsx benchmarks/evaluations/c86-static-embeddings/runner.ts",
+		"verify:c86": "tsx scripts/verify-c86.ts",
+		"bench:c87": "tsx benchmarks/evaluations/c87-structural-cold-start/runner.ts",
+		"verify:c87": "tsx scripts/verify-c87.ts",
+		"bench:c88": "tsx benchmarks/evaluations/c88-contained-execution/runner.ts",
+		"verify:c88": "tsx scripts/verify-c88.ts",
 		"bench:ann": "bun scripts/ann-bench.ts",
 		"bench:perf": "tsx scripts/perf-bench.ts",
 		"bench:competitive": "tsx scripts/competitive-bakeoff.ts",
 		"bench:token-optimizer": "tsx benchmarks/evaluations/token-optimizer-20260730/runner.ts",
 		"audit:token-optimizer": "tsx scripts/token-optimizer-source-audit.ts",
 		"release:attestation": "tsx scripts/release-attestation.ts",
+		"release:preflight": "tsx scripts/release-preflight.ts",
 		"lint": "biome check .",
 		"lint:fix": "biome check --write ."
 	},