scrumrun 1.5.2 → 2.0.0

package/docs/COMMANDS.md

@@ -0,0 +1,69 @@
+# 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
+/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]
+/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 `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.

package/docs/RELEASE.md

@@ -0,0 +1,44 @@
+# ScrumRun 2.0 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.
+
+## 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.json`, README, changelog, SPEC, CORE, skill, migration guide, and tag all name 2.0.0.
+
+## Release candidate (owner approval required)
+
+1. Set `2.0.0-rc.1` metadata 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.
+
+## Final promotion (new owner approval required)
+
+1. Set `2.0.0`, rerun every local/registry gate, and create the final metadata commit.
+2. Create/push tag `v2.0.0` and publish npm `2.0.0`.
+3. Promote `latest` only after registry smoke tests pass.
+4. Create the GitHub release from `CHANGELOG.md` and link the migration guide.
+5. Verify npm metadata, Git tag/commit, GitHub release, README, and checksums agree.
+
+## Recovery
+
+- RC defect: publish another RC; keep `latest` unchanged.
+- Final package defect before `latest`: do not promote; publish `2.0.1` after correction if 2.0.0 already exists.
+- Defect after `latest`: assess deprecation vs immediate 2.0.1; never overwrite/unpublish without explicit owner decision and 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,80 @@
+# 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 |
+
+Native creation uses the declared initial statuses. Migration may restore a historical non-initial status only with provenance and validation.
+
+## 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,66 @@
+# 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
+```
+
+Stale generated views are warnings, not canonical corruption.
+
+## 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 };

package/lib/code-intel/learning.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const path = require("node:path");
+const { ArtifactRepository, sha256 } = require("../v2/artifacts");
+const { createMemory } = require("../memory/service");
+
+function learningSection(body) {
+  const match = String(body || "").match(/^## Learning Candidates\s*\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m);
+  return match ? match[1] : "";
+}
+
+function parseCandidate(line) {
+  const match = line.match(/^\s*-\s*\[([a-z][a-z0-9_]*)\]\s+([^|]+?)\s*\|\s*([^|]+?)(?:\s*\|\s*evidence:\s*([^|]+?))?(?:\s*\|\s*relations?:\s*(.+?))?\s*$/i);
+  if (!match) return null;
+  const subject = match[2].trim();
+  const evidence = match[4] ? match[4].split(/\s*,\s*/).filter(Boolean) : [];
+  const relations = match[5]
+    ? match[5].split(/\s*,\s*/).map((item) => item.replace(/^([a-z][a-z0-9_]*)\s*=\s*/i, "$1: ")).filter(Boolean)
+    : [];
+  return { insightKind: match[1].toLowerCase(), subject, content: match[3].trim(), evidence, relations };
+}
+
+function extractLearningCandidates(projectRoot, runId) {
+  const repository = new ArtifactRepository(path.join(projectRoot, ".scrumrun"));
+  const run = repository.read("run", runId);
+  if (!run) throw new Error(`Run not found: ${runId}`);
+  if (!run.record || !["learning", "completed"].includes(run.record.status)) {
+    throw new Error(`Run ${runId} must be learning or completed before extracting knowledge.`);
+  }
+  const lines = learningSection(run.body).split(/\r?\n/).filter((line) => /^\s*-\s+/.test(line) && !/Pending\./i.test(line));
+  const created = [];
+  const warnings = [];
+  const seen = new Set();
+  for (const line of lines) {
+    const candidate = parseCandidate(line);
+    if (!candidate) {
+      warnings.push(`Ignored malformed learning candidate: ${line.trim()}`);
+      continue;
+    }
+    const key = sha256(`${candidate.subject}\0${candidate.content}`);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const generic = candidate.subject.match(/^(function|class|interface|type|enum):(.+)$/);
+    const subjectType = candidate.subject.startsWith("symbol:") || generic ? "symbol" : "module";
+    try {
+      const artifact = createMemory(projectRoot, "insight", {
+        title: candidate.content.length > 100 ? `${candidate.content.slice(0, 97)}...` : candidate.content,
+        content: candidate.content,
+        evidence: [runId, ...candidate.evidence],
+        relations: [`derived_from: ${runId}`, `insight_kind: ${candidate.insightKind}`, ...candidate.relations],
+        subjectType,
+        subjectId: candidate.subject,
+        sourceType: "run",
+        sourceId: runId,
+        confidence: 0.6,
+        reviewTrigger: "subject implementation or evidence changes"
+      });
+      created.push(artifact.record.id);
+    } catch (error) {
+      warnings.push(`Could not create candidate for ${candidate.subject}: ${error.message}`);
+    }
+  }
+  return { created, warnings };
+}
+
+module.exports = { extractLearningCandidates, learningSection, parseCandidate };