scrumrun 1.5.2 → 2.1.0

package/docs/COMMANDS.md

@@ -0,0 +1,71 @@
+# ScrumRun 2.0 Command Reference
+
+The canonical grammar is:
+
+```text
+/sc <noun> <subject> <action> [args]
+```
+
+Use `/sc` inside a supported AI client. The equivalent CLI form is `npx scrumrun@latest sc ...`. CLI-native workflows execute immediately; reasoning-heavy routes tell the installed agent to execute the validated workflow.
+
+## Plan
+
+```text
+/sc plan intake <request>
+/sc plan intake --approve <token>
+/sc plan task --add|--list|--show|--run|--audit|--cancel|--retry
+/sc plan sprint --add|--list|--show|--start|--complete|--block
+/sc plan feature --add|--list|--show|--activate|--complete
+/sc plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block [--note] [typed evidence flags]
+/sc plan challenge <question>
+```
+
+CLI-native: intake/approval, Task/Run list/show, Task retry, and Run transitions. A retry requires a failed, blocked, or partial Task and creates a new Run.
+
+## Knowledge
+
+```text
+/sc knowledge fact --add|--list|--show|--approve|--reject|--deprecate|--invalidate
+/sc knowledge decision --add|--list|--show|--resolve|--deprecate|--invalidate
+/sc knowledge insight --propose|--list|--show|--confirm|--stale|--reject|--deprecate|--invalidate
+/sc knowledge dossier --add|--list|--show|--refresh|--stale|--deprecate|--archive
+/sc knowledge context --build|--update|--show|--clear
+/sc knowledge map --build|--show
+/sc knowledge study <focus>
+/sc knowledge vault --add|--list|--show|--remove|--path
+```
+
+Creation options include `--title`, `--content`, repeated `--evidence`, repeated `--relation "used_by: Target"`, `--subject type:id`, `--source`, `--source-id`, `--confidence`, `--valid-from`, `--valid-until`, and `--review-trigger`. Promotion options accept repeated `--evidence` and `--note`.
+
+`study` queries the semantic index. `map --build` regenerates both SQLite and bounded `map.md`. `context --clear` deletes only the disposable index.
+
+## Rules and review
+
+```text
+/sc rules guardrail --add|--list|--show|--retire
+/sc rules reviewer --add|--list|--show|--run
+/sc review code --run
+/sc review artifact --run
+/sc review migration --run
+/sc review release --run
+```
+
+`review artifact --run` is CLI-native and returns a machine-readable 20-invariant project audit. Other review routes require repository reasoning and remain read-only unless fixes receive separate approval.
+
+## Config and lifecycle
+
+```text
+/sc config project --show|--language|--interaction|--approval|--quick-tasks
+/sc config init --local|--shared|--lean|--no-agent-hint|--force
+/sc config update [all|codex|opencode|claude] [--migrate]
+/sc config migrate --to 2 --dry-run|--apply|--rollback
+/sc config doctor [all|codex|opencode|claude] [--strict] [--recover]
+/sc config uninstall --force
+/sc config help <topic>
+```
+
+Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `status`) remain available for shell automation. Ordinary update runs only a read-only migration preflight; `--migrate` is explicit application consent.
+
+Run transitions accept typed evidence through `--command`, `--test`, `--file`, `--review`, `--decision`, `--insight`, `--risk`, or generic `--evidence kind:value`. `doctor --recover` is an explicit write that resolves only safe pending kernel transactions; doctor without it remains read-only.
+
+Run `npx scrumrun@latest commands` for grammar rendered directly from the current manifest.

package/docs/ENTITY-MODEL.md

@@ -0,0 +1,38 @@
+# ScrumRun 2.0 Entity Model
+
+This document explains the model. Exact ids, directories, initial states, transitions, structural cardinalities, truth ownership, and authority boundaries are generated from `lib/v2/schema.js` into [`SCHEMA.md`](SCHEMA.md). Do not maintain another hand-written schema table here.
+
+## Core distinction
+
+| Entity | Question | Lifetime |
+|---|---|---|
+| Feature | Why does this initiative matter? | Long-lived |
+| Task | What atomic outcome is approved? | Until outcome/closure |
+| Sprint | When are related Tasks grouped? | Timebox/batch |
+| Run | How did one execution attempt happen? | Immutable attempt history |
+| Memory | What do we know, and why? | Reviewed until stale/deprecated/invalidated |
+
+```text
+FEAT-003
+   └── TASK-018
+          ├── executed_by → RUN-044
+          ├── included_in → SPRINT-012
+          ├── constrained_by → DEC-018
+          └── generated → INS-041
+```
+
+Task is always the executable unit. A Task may be independent of a Sprint. Sprint never substitutes for Task. A retry creates another Run for the same Task.
+
+## Canonical artifacts
+
+All artifacts carry `id`, `kind`, `status`, `created`, `updated`, and `method`. Relations live in frontmatter for structural ownership and in `## Relations` for extensible graph edges. The generated [`SCHEMA.md`](SCHEMA.md) is the authoritative inventory.
+
+## Operational flow
+
+Approval creates one Task and one Run. The Run progresses `executing → validating → learning → completed|failed|blocked`, while the Task mirrors `running → validating → learning → completed|failed|blocked`. Pair mutations are recoverable.
+
+Feature and Sprint provide context/grouping and do not own execution history. Review attaches evidence. Memory explains decisions and constraints across all of them.
+
+## Generated projections
+
+`state.md` summarizes active work/memory. `map.md` summarizes bounded nodes/edges. SQLite stores the complete derived graph/search index. All are fingerprinted or explicitly stale and can be rebuilt from Markdown plus source code. Freshness uses a metadata watch fast path and content-hash fallback; the watch is disposable evidence, never truth.

package/docs/RELEASE-SCORECARD.md

@@ -0,0 +1,43 @@
+# ScrumRun 2.1.0 Local Release Scorecard
+
+Date: 2026-07-22  
+Package: `2.1.0`  
+Method contract: `2.0.0`  
+Scope: local implementation and package readiness; external registry/tag/release verification remains owner-gated.
+
+## Scoring rule
+
+A score of 9.5 or higher requires a single documented contract, machine enforcement on the critical path, adversarial/failure tests, deterministic recovery where mutation is involved, bounded performance, and an explicit residual-risk statement. Documentation alone cannot earn 9.5.
+
+| Area | Score | Executable evidence |
+|---|---:|---|
+| Conceptual model | 9.7 | Frozen Feature → Task → Sprint → Run → Memory schema; Task/Sprint and retry invariants; ADR-015 and ADR-018. |
+| Documentation architecture | 9.7 | SPEC is normative, CORE is operational, ADRs explain trade-offs, generated SCHEMA is drift-checked, README/skill/templates are conformance-tested. |
+| Artifact kernel | 9.7 | One executable schema, safe-path checks, lossless frontmatter transitions, conflict refusal, fsync atomic writes, and durable multi-file transactions with failure injection. |
+| Run history and audit | 9.8 | Stable ordered event ids, RFC3339 timestamps, typed evidence, state reconstruction, completion gates, retry preservation, explicit early-v2 migration, and byte-exact rollback. |
+| Real conformance | 9.7 | Twenty normative invariants point to executable tests; clean-project audit, malformed artifacts, secrets, symlinks, migration interruption, transaction interruption, and cache corruption are exercised. |
+| Local state and retrieval | 9.6 | Intake/state share one canonical fingerprint; state/map/SQLite expose staleness; metadata fast path falls back to full content hashes; cache schema mismatch rebuilds once; stale map display is refused. |
+| Overall operation | 9.6 | Read-only intake, explicit approval, atomic Task/Run creation, Policy Engine ids, migration preflight/apply/rollback, package E2E, installed-asset doctor, Node 22/24/26 CI definition, and release budgets. |
+
+Minimum local score: **9.6/10**.
+
+## Release evidence
+
+- Full suite: `npm test`.
+- Performance suite: `npm run benchmark`.
+- Contract drift: `scripts/generate-contract-docs.js --check` runs before tests.
+- Project conformance: `/sc review artifact --run`, twenty invariants, zero findings at the release checkpoint.
+- Installed integration: `doctor codex --strict`, exact prompt/skill hashes and zero project findings.
+- Package boundary: `npm pack --dry-run --json`, explicit file inventory, no repository-local `.scrumrun/`, tests, vault, backup, migration state, or cache.
+- Tarball E2E: install, v2 memory, ongoing v1 migration, rollback, doctor, and uninstall run from the packed package in the test suite.
+
+The exact final tarball checksum belongs in the owner-gated release Review/Run after all included files are frozen; embedding a tarball's own checksum inside an included document would change that checksum.
+
+## Residual risks and gates
+
+- Registry smoke, npm dist-tags, `v2.1.0` tag, push, and GitHub release are not proven by local tests and require explicit owner authorization.
+- The built-in code-intelligence adapter currently covers JavaScript/TypeScript; other languages require replaceable adapters.
+- Remote Node 22/24/26 CI must pass on the release commit even though the same matrix is declared locally in `.github/workflows/ci.yml`.
+- Semantic retrieval is intentionally lexical/structural rather than a probabilistic embedding system; confirmed Markdown evidence remains the authority.
+
+These are bounded release or extension risks, not hidden correctness claims. A failed external gate stops promotion and results in a new immutable SemVer; it never rewrites an existing npm version.

package/docs/RELEASE.md

@@ -0,0 +1,51 @@
+# ScrumRun Package Release Procedure
+
+Publication is owner-gated. Tests, packaging, local commits, and release metadata preparation do not authorize npm publication, git push, tags, GitHub releases, or dist-tag changes.
+
+The npm package/CLI follows SemVer independently from the ScrumRun method contract. For this release, package `2.1.0` implements method `2.0.0`. Published package `2.0.0` is immutable and must never be overwritten or reused.
+
+## Local release gate
+
+```bash
+npm test
+npm run benchmark
+git diff --check
+npm pack --dry-run
+npx scrumrun@latest sc review artifact --run   # in a clean v2 fixture/current package equivalent
+```
+
+Confirm package contents exclude repository-local `.scrumrun/` state, caches, migration records, backups, vaults, tests, and secrets. The `.scrumrun/` directory inside project templates is expected. Confirm package metadata, README, changelog, tarball filename, checksum, and Git tag agree on `2.1.0`; SPEC, CORE, artifact frontmatter, migration, and installed skill continue to declare method `2.0.0`.
+
+Record the local evidence and residual risks against [`RELEASE-SCORECARD.md`](./RELEASE-SCORECARD.md). Scores describe local readiness only and never replace registry smoke or owner approval.
+
+## Optional registry candidate (separate owner approval required)
+
+1. Set a new unpublished prerelease such as `2.1.0-rc.1` and create a reviewed commit.
+2. `npm pack`; record tarball SHA-256/integrity.
+3. Publish to `next`, never `latest`:
+
+   ```bash
+   npm publish --tag next
+   ```
+
+4. Install from the registry into a clean fixture.
+5. Run init, intake/approval, memory confirmation/query, v1 update preflight/apply/rollback, doctor, and uninstall.
+6. Fix findings in a new RC; never replace an already-published version.
+
+An RC is immutable. Fixes create `rc.2`, `rc.3`, and so on. Skipping an RC does not skip any local, tarball, owner, registry-smoke, or final-promotion gate.
+
+## Final release (new owner approval required)
+
+1. Set `2.1.0`, rerun every local gate, inspect the exact tarball, and create the final local metadata commit.
+2. Stop and request explicit owner authorization for each external boundary.
+3. Publish npm `2.1.0` to `next` using the reviewed tarball/source commit (`npm publish --tag next`); never publish from a changed worktree and do not move `latest` yet.
+4. Install the registry artifact in a clean fixture and run init, intake/approval, Run lifecycle, memory query, v1 migration apply/rollback, doctor, and uninstall.
+5. Only after registry smoke passes, create/push tag `v2.1.0`, promote/verify `latest` with an explicit dist-tag command, and create the GitHub release from `CHANGELOG.md` with the migration guide and checksum.
+6. Verify npm metadata, dist-tags, Git tag/commit, GitHub release, README, and checksums all agree.
+
+## Recovery
+
+- RC defect: publish another RC; keep `latest` unchanged.
+- Final package defect before `latest`: do not promote; publish a new patch after correction because `2.1.0` cannot be replaced.
+- Defect after `latest`: assess deprecation vs immediate patch; never overwrite/unpublish without explicit owner decision and current npm-policy review.
+- Migration issue: stop promotion, preserve registry artifact/checksum, use the documented rollback fixture, and publish a corrected version.

package/docs/SCHEMA.md

@@ -0,0 +1,89 @@
+# ScrumRun 2.0.0 Executable Schema
+
+> Generated by `scripts/generate-contract-docs.js` from `lib/v2/schema.js`. Do not edit this file manually.
+
+## Authority boundaries
+
+| Concern | Authoritative source | Scope |
+|---|---|---|
+| semantics | `SPEC.md` | normative meanings and invariants |
+| schema | `lib/v2/schema.js` | machine-enforced ids, paths, statuses, transitions, relations, and ownership metadata |
+| commands | `lib/commands/manifest.js` | public command grammar and compatibility routes |
+| projectPolicy | `.scrumrun/guardrails.md` | owner/project constraints |
+| projectTruth | `.scrumrun/**/*.md` | authored canonical project records |
+| projections | `.scrumrun/state.md, .scrumrun/map.md, .scrumrun/.cache/` | disposable derived views; never authority |
+
+The boundaries above are deliberately different: SPEC owns meanings, the executable schema owns mechanically enforced values, the command manifest owns grammar, project Markdown owns authored project truth, and generated views own nothing.
+
+## Artifact contract
+
+| Kind | Stable ID | Canonical directory | Allowed initial status | Truth owned by this artifact |
+|---|---|---|---|---|
+| feature | `FEAT-NNN` | `features/` | `backlog`, `proposed` | initiative purpose, scope, dependencies, and lifecycle |
+| task | `TASK-NNN` | `tasks/` | `backlog`, `proposed`, `running` | scope, acceptance criteria, approval, and intended status |
+| sprint | `SPRINT-NNN` | `sprints/` | `proposed` | timebox or delivery-batch membership; never execution history |
+| run | `RUN-NNN` | `runs/` | `executing` | append-only execution events, evidence, result, and attempt number |
+| review | `REV-NNN` | `reviews/` | `proposed` | scoped findings, checks, evidence, and verdict |
+| knowledge | `K-NNN` | `memory/knowledge/` | `candidate` | approved evidence-backed fact and validity |
+| decision | `DEC-NNN` | `memory/decisions/` | `open` | decision, rationale, validity, and lifecycle |
+| insight | `INS-NNN` | `memory/insights/` | `candidate` | explanatory candidate/confirmed context and evidence |
+| dossier | `DOS-NNN` | `memory/dossiers/` | `active` | reviewed topic bundle and freshness |
+
+Every artifact also requires `id`, `kind`, `status`, `created`, `updated`, and `method: 2.0.0`.
+
+## Structural cardinalities
+
+| Frontmatter field | Target | Cardinality | Meaning |
+|---|---|---|---|
+| `feature` | feature (`FEAT-NNN`) | 0..1 | long-lived initiative containing the artifact |
+| `sprint` | sprint (`SPRINT-NNN`) | 0..1 | optional delivery batch containing a Task or Run |
+| `task` | task (`TASK-NNN`) | 1 for Run; otherwise 0..1 | atomic work executed or reviewed by the artifact |
+
+Task is the atomic unit. A Task may have zero or one Sprint. A Task may have many Runs, but every Run belongs to exactly one Task and has a monotonically increasing attempt number within that Task. Sprint membership is authoritative on `Task.sprint`; a Sprint's `## Tasks` list is a human-readable projection that must agree with it.
+
+## Scalar constraints
+
+| Field | Kinds | Presence | Type | Meaning |
+|---|---|---|---|---|
+| `attempt` | run | required | positive integer | monotonic execution-attempt number within one Task |
+| `ledger` | run | optional | integer 1 | canonical Run event-ledger schema; required for newly authored Runs |
+
+Native creation uses the declared initial statuses. Migration may restore a historical non-initial status only with provenance and validation.
+
+## Run event ledger
+
+Newly authored Runs use `ledger: 1`. Their `## Events` section contains append-only JSON event blocks with stable ids in the form `RUN-NNN-EVT-NNN`.
+
+Every event requires `schema`, `id`, contiguous `sequence`, RFC3339 `occurred_at`, `timestamp_precision`, `actor`, `from`, `to`, `reason`, and structured `evidence`. Event types are `transition`, `snapshot`. Evidence kinds are `approval`, `command`, `test`, `file`, `review`, `decision`, `insight`, `risk`, `note`, `migration`, `legacy`.
+
+A native ledger begins with `created → executing`; an evidenced migration `snapshot` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated. Run owns the event history; Task stores its intended scope and synchronized current status without copying Run events.
+
+## Truth questions
+
+- **feature:** Why does this initiative exist?
+- **task:** What approved atomic outcome is intended?
+- **sprint:** When are related Tasks grouped?
+- **run:** How did one execution attempt actually happen?
+- **review:** What independent validation was performed?
+- **knowledge:** What verified project fact is reusable?
+- **decision:** What normative choice constrains future work?
+- **insight:** Why is something arranged or constrained this way?
+- **dossier:** What evidence belongs to one retrieval topic?
+
+## Lifecycles
+
+| Kind | Declared transitions |
+|---|---|
+| feature | `backlog` → `proposed`, `active`, `cancelled`<br>`proposed` → `active`, `cancelled`<br>`active` → `paused`, `completed`, `cancelled`<br>`completed` → terminal<br>`paused` → `active`, `cancelled`<br>`cancelled` → terminal |
+| task | `backlog` → `proposed`, `running`, `cancelled`<br>`proposed` → `running`, `cancelled`<br>`running` → `validating`, `failed`, `blocked`, `cancelled`<br>`validating` → `learning`, `failed`, `blocked`<br>`learning` → `completed`, `failed`, `blocked`<br>`partial` → `running`, `cancelled`<br>`completed` → terminal<br>`failed` → `running`, `cancelled`<br>`blocked` → `running`, `cancelled`<br>`cancelled` → terminal |
+| sprint | `proposed` → `running`, `cancelled`<br>`running` → `partial`, `completed`, `blocked`, `cancelled`<br>`partial` → `running`, `completed`, `cancelled`<br>`completed` → terminal<br>`blocked` → `running`, `cancelled`<br>`cancelled` → terminal |
+| run | `executing` → `validating`, `failed`, `blocked`<br>`validating` → `learning`, `failed`, `blocked`<br>`learning` → `completed`, `failed`, `blocked`<br>`partial` → `executing`, `failed`, `blocked`<br>`completed` → terminal<br>`failed` → terminal<br>`blocked` → `executing`, `failed` |
+| review | `proposed` → `running`<br>`running` → `passed`, `failed`<br>`passed` → `archived`<br>`failed` → `running`, `archived`<br>`archived` → terminal |
+| knowledge | `candidate` → `approved`, `rejected`<br>`approved` → `deprecated`, `invalidated`<br>`rejected` → `candidate`<br>`deprecated` → `approved`<br>`invalidated` → terminal |
+| decision | `open` → `resolved`, `deprecated`, `invalidated`<br>`resolved` → `deprecated`, `invalidated`<br>`deprecated` → `open`<br>`invalidated` → terminal |
+| insight | `candidate` → `confirmed`, `invalidated`<br>`confirmed` → `stale`, `deprecated`, `invalidated`<br>`stale` → `confirmed`, `deprecated`, `invalidated`<br>`deprecated` → `confirmed`<br>`invalidated` → terminal |
+| dossier | `active` → `stale`, `deprecated`, `archived`<br>`stale` → `active`, `deprecated`, `archived`<br>`deprecated` → `archived`<br>`archived` → terminal |
+
+## Projections
+
+`state.md`, `map.md`, context packages, and `.cache/` are disposable. They may summarize or index canonical artifacts, but they cannot introduce status, policy, relations, decisions, or knowledge.

package/docs/SEMANTIC-MEMORY.md

@@ -0,0 +1,68 @@
+# Semantic Memory
+
+ScrumRun memory explains why code exists in its current form. It separates operational events, normative Decisions, reviewed facts, and contextual Insights so an agent can retrieve the smallest relevant evidence package.
+
+## Choosing a kind
+
+- Knowledge: descriptive fact verified by evidence.
+- Decision: normative constraint—what must or must not happen.
+- Insight: explanation, rationale, trade-off, warning, failure history, or testing note.
+- Dossier: curated evidence bundle for a topic/module.
+
+“Pricing calculations must run on the backend” is a Decision. “This function stays in pricing because quotations use it before checkout exists” is an Insight.
+
+## Evidence and lifecycle
+
+AI-created facts/insights always start as candidates. Confirmation requires one or more resolvable artifact IDs or project paths. Paths cannot traverse outside the project, follow symlinks, or reference the vault.
+
+Useful metadata:
+
+```yaml
+subject_type: symbol
+subject_id: function:calculateFinalPrice
+source_type: run
+source_id: RUN-044
+confidence: 0.8
+valid_from: 2026-01-01
+valid_until: null
+last_verified_commit: <git-hash-or-unavailable>
+review_trigger: pricing implementation changes
+```
+
+Confirmed memory may become stale, deprecated, or invalidated. Those records remain auditable. Queries exclude rejected/deprecated/invalidated truth by default and label stale evidence explicitly.
+
+## Relations and code graph
+
+```text
+symbol:calculateFinalPrice
+  ├── defined_in → module:pricing
+  ├── depends_on → TaxCalculator
+  ├── used_by → OrderService
+  ├── constrained_by → DEC-018
+  ├── has_insight → INS-041
+  └── protected_by → price-calculation.spec.ts
+```
+
+The JS/TS adapter records qualified symbol identity, path, kind, line, fingerprint, commit, exports, and lexical/module provenance. Moves with identical fingerprints remap. Unprovable rename/removal becomes orphaned history. Evidence or implementation drift marks linked records stale only in the projection; canonical Markdown changes only through explicit review.
+
+## Learning from Runs
+
+A validated Run may contain:
+
+```text
+## Learning Candidates
+
+- [placement_rationale] function:calculateFinalPrice | Keep pricing in the domain because quotations use it. | evidence: src/quotation/service.ts | relations: used_by=module:src/quotation/service.ts
+```
+
+Entering `learning` extracts `INS-NNN` candidates. Malformed extraction emits a warning and never blocks the Run.
+
+## Query and maintenance
+
+```bash
+npx scrumrun@latest sc knowledge map --build
+npx scrumrun@latest sc knowledge study calculateFinalPrice
+npx scrumrun@latest sc knowledge context --clear
+```
+
+SQLite is ignored and disposable. Queries default to 10 records/40 relations and hard-cap at 100/100. Match type, truth state, warnings, relation counts, and evidence are returned so recommendations remain explainable.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,78 @@
+# Troubleshooting
+
+## “Project must be explicitly migrated to v2”
+
+Run `npx scrumrun@latest update` for a read-only preflight, then review and apply with `update --migrate`. See [`MIGRATION-1-to-2.md`](../MIGRATION-1-to-2.md).
+
+## Migration is blocked
+
+- Symlink: replace it with a regular local file/directory or preserve it outside `.scrumrun/`.
+- Malformed `method.json`: do not guess; restore the correct v1 state/marker and rerun dry-run.
+- Secret outside vault: move the value to `.scrumrun/vault.local.md`, redact the canonical source, and retry.
+- Ambiguous history: warnings are expected and preserved; blockers must be resolved before apply.
+
+Dry-run is safe to repeat and writes nothing.
+
+## Rollback refuses
+
+Rollback detected post-migration work that it would erase. Copy/export wanted changes, reconcile the paths named in the error, and retry. Never delete the migration backup to force rollback.
+
+## `state.md` or `map.md` is stale
+
+`state.md` refreshes after runtime transitions. Rebuild the semantic map with:
+
+```bash
+npx scrumrun@latest sc knowledge map --build
+```
+
+Fresh projections include a source fingerprint and a watch fingerprint. A matching watch avoids a full read. If file metadata changed, ScrumRun hashes canonical/source content before deciding whether the projection is actually stale. `check: "schema"` means the disposable SQLite format changed and one rebuild is required; `check: "hash"` means the safe fallback was used.
+
+Stale generated views are warnings, not canonical corruption.
+
+## Doctor reports `TRANSACTION_PENDING`
+
+An approved multi-file mutation was interrupted after its durable journal was prepared. Ordinary doctor/audit is read-only and leaves the evidence untouched. Either retry the same approved operation, which recovers before writing, or explicitly run:
+
+```bash
+npx scrumrun@latest doctor codex --recover --strict
+```
+
+Prepared transactions restore their original bytes; committed transactions verify the applied bytes and finalize. Recovery refuses if a target changed to content matching neither journal side, because that would overwrite later owner work. Receipts contain hashes and outcomes, not file contents.
+
+## SQLite is missing/corrupt
+
+Delete or clear only the disposable cache:
+
+```bash
+npx scrumrun@latest sc knowledge context --clear
+npx scrumrun@latest sc knowledge map --build
+```
+
+Canonical Markdown is unchanged. Query automatically rebuilds a missing/stale index.
+
+## Memory cannot be confirmed
+
+Every confirmed fact/insight/Decision needs resolvable evidence. Use an existing artifact ID such as `RUN-044`/`DEC-018` or a regular project path. Absolute paths, traversal, symlinks, missing files, and vault references are rejected.
+
+## A query returns stale/orphaned memory
+
+Inspect its invalidation warning and code/evidence relations. For a real code move, rebuild may show `remappedFrom`. For a rename/removal without proof, the old symbol remains orphaned. Review the canonical memory; mark stale and reconfirm with current evidence, or invalidate it.
+
+## Doctor reports missing clients
+
+```bash
+npx scrumrun@latest install codex
+npx scrumrun@latest install claude
+npx scrumrun@latest install opencode
+npx scrumrun@latest doctor all
+```
+
+Use `doctor --compat` only while validating one-cycle v1 adapters.
+
+## Node.js is unsupported
+
+ScrumRun 2.0 requires Node.js `>=22.13.0` because semantic indexing uses native `node:sqlite`. Upgrade Node, then rerun doctor.
+
+## Safe uninstall
+
+`uninstall` previews. `uninstall --force` removes `.scrumrun/` and only removes `AGENTS.md` when it is recognized as ScrumRun-generated. Export any memory you want to keep first.

package/lib/code-intel/adapter.js

@@ -0,0 +1,20 @@
+"use strict";
+
+class LanguageAdapter {
+  constructor({ id, extensions }) {
+    if (!id || !Array.isArray(extensions) || !extensions.length) throw new Error("LanguageAdapter requires id and extensions.");
+    this.id = id;
+    this.extensions = new Set(extensions.map((extension) => extension.toLowerCase()));
+  }
+
+  supports(file) {
+    const extension = file.slice(file.lastIndexOf(".")).toLowerCase();
+    return this.extensions.has(extension);
+  }
+
+  scan() {
+    throw new Error(`${this.id} adapter must implement scan().`);
+  }
+}
+
+module.exports = { LanguageAdapter };

package/lib/code-intel/javascript.js

@@ -0,0 +1,199 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { LanguageAdapter } = require("./adapter");
+const { sha256 } = require("../v2/artifacts");
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function maskSource(source) {
+  const chars = [...source];
+  let state = "code";
+  let escaped = false;
+  for (let index = 0; index < chars.length; index++) {
+    const char = chars[index];
+    const next = chars[index + 1];
+    if (state === "line") {
+      if (char === "\n") state = "code";
+      else chars[index] = " ";
+      continue;
+    }
+    if (state === "block") {
+      if (char === "*" && next === "/") {
+        chars[index] = chars[index + 1] = " ";
+        index++;
+        state = "code";
+      } else if (char !== "\n") chars[index] = " ";
+      continue;
+    }
+    if (["single", "double", "template"].includes(state)) {
+      if (char !== "\n") chars[index] = " ";
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if ((state === "single" && char === "'") || (state === "double" && char === '"') || (state === "template" && char === "`")) {
+        state = "code";
+      }
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      chars[index] = chars[index + 1] = " ";
+      index++;
+      state = "line";
+    } else if (char === "/" && next === "*") {
+      chars[index] = chars[index + 1] = " ";
+      index++;
+      state = "block";
+    } else if (char === "'") {
+      chars[index] = " ";
+      state = "single";
+    } else if (char === '"') {
+      chars[index] = " ";
+      state = "double";
+    } else if (char === "`") {
+      chars[index] = " ";
+      state = "template";
+    }
+  }
+  return chars.join("");
+}
+
+function closingBrace(masked, open) {
+  if (open < 0 || masked[open] !== "{") return -1;
+  let depth = 0;
+  for (let index = open; index < masked.length; index++) {
+    if (masked[index] === "{") depth++;
+    else if (masked[index] === "}" && --depth === 0) return index + 1;
+  }
+  return -1;
+}
+
+function declarationEnd(masked, start) {
+  const open = masked.indexOf("{", start);
+  const semicolon = masked.indexOf(";", start);
+  if (open >= 0 && (semicolon < 0 || open < semicolon)) {
+    const close = closingBrace(masked, open);
+    if (close >= 0) return close;
+  }
+  const newline = masked.indexOf("\n", start);
+  return semicolon >= 0 ? semicolon + 1 : newline >= 0 ? newline : masked.length;
+}
+
+function lineAt(source, index) {
+  return source.slice(0, index).split("\n").length;
+}
+
+function declarations(source) {
+  const masked = maskSource(source);
+  const patterns = [
+    { kind: "function", regex: /\b(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)\s*\(/g },
+    { kind: "class", regex: /\b(?:export\s+(?:default\s+)?)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)\b/g },
+    { kind: "interface", regex: /\b(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)\b/g },
+    { kind: "type", regex: /\b(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*(?:<[^;=]+>)?\s*=/g },
+    { kind: "enum", regex: /\b(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)\b/g },
+    { kind: "function", regex: /\b(?:export\s+(?:default\s+)?)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/g }
+  ];
+  const found = [];
+  const seen = new Set();
+  for (const pattern of patterns) {
+    pattern.regex.lastIndex = 0;
+    let match;
+    while ((match = pattern.regex.exec(masked))) {
+      const key = `${match.index}:${match[1]}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const end = declarationEnd(masked, match.index);
+      const normalized = masked.slice(match.index, end).replace(/\s+/g, " ").trim();
+      found.push({
+        name: match[1],
+        kind: pattern.kind,
+        line: lineAt(source, match.index),
+        start: match.index,
+        end,
+        exported: /^\s*export\b/.test(masked.slice(Math.max(0, match.index - 20), match.index + 20)) || /\bexport\b/.test(match[0]),
+        fingerprint: sha256(`${pattern.kind}\0${normalized}`)
+      });
+    }
+  }
+  return { masked, declarations: found.sort((a, b) => a.start - b.start) };
+}
+
+function importSpecifiers(source) {
+  const specifiers = new Set();
+  const patterns = [
+    /^\s*(?:import|export)\s+(?:[^"'\n]*?\s+from\s+)?["']([^"']+)["']/gm,
+    /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g,
+    /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g
+  ];
+  for (const regex of patterns) {
+    let match;
+    while ((match = regex.exec(source))) specifiers.add(match[1]);
+  }
+  return [...specifiers].sort();
+}
+
+function resolveImport(projectRoot, sourceFile, specifier) {
+  if (!specifier.startsWith(".")) return `package:${specifier}`;
+  const base = path.resolve(path.dirname(sourceFile), specifier);
+  const candidates = [
+    base,
+    ...[".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"].map((extension) => `${base}${extension}`),
+    ...[".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"].map((extension) => path.join(base, `index${extension}`))
+  ];
+  const target = candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+  if (!target) return `module:${posix(path.relative(projectRoot, base))}`;
+  return `module:${posix(path.relative(projectRoot, target))}`;
+}
+
+class JavaScriptAdapter extends LanguageAdapter {
+  constructor() {
+    super({ id: "javascript-typescript", extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"] });
+  }
+
+  scan({ projectRoot, file, relative, commit }) {
+    const source = fs.readFileSync(file, "utf8");
+    const parsed = declarations(source);
+    const moduleId = `module:${posix(relative)}`;
+    const dependencies = importSpecifiers(source).map((specifier) => ({
+      specifier,
+      target: resolveImport(projectRoot, file, specifier)
+    }));
+    const symbols = parsed.declarations.map((declaration) => ({
+      id: `symbol:${posix(relative)}#${declaration.kind}:${declaration.name}`,
+      name: declaration.name,
+      qualifiedName: `${posix(relative)}#${declaration.kind}:${declaration.name}`,
+      kind: declaration.kind,
+      path: posix(relative),
+      line: declaration.line,
+      fingerprint: declaration.fingerprint,
+      commit,
+      exported: declaration.exported,
+      language: this.id,
+      start: declaration.start,
+      end: declaration.end
+    }));
+    return {
+      module: {
+        id: moduleId,
+        name: posix(relative),
+        qualifiedName: posix(relative),
+        kind: "module",
+        path: posix(relative),
+        line: 1,
+        fingerprint: sha256(source),
+        commit,
+        exported: true,
+        language: this.id
+      },
+      symbols,
+      dependencies,
+      masked: parsed.masked
+    };
+  }
+}
+
+module.exports = { JavaScriptAdapter, declarations, importSpecifiers, maskSource, resolveImport };