scrumrun 3.1.2 → 4.1.0

package/docs/ENTITY-MODEL.md

@@ -1,4 +1,4 @@
-# ScrumRun 2.0 Entity Model
+# ScrumRun 4.0 Markdown 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.
 
@@ -6,32 +6,35 @@ This document explains the model. Exact ids, directories, initial states, transi
 
 | Entity | Question | Lifetime |
 |---|---|---|
+| Core | How must the agent work? | Stable, sealed policy |
+| Guardrails | What may never be broken here? | Stable, sealed project policy |
+| Knowledge | What do we know, and why? | Reviewed until stale/deprecated/invalidated |
+| Backlog | What is provisioned but not started? | Tasks with `status: backlog` |
 | 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 |
+| Sprint | Which Tasks ship together? | Feature, fix, or maintenance batch |
+| Task | What concrete outcome must be delivered? | Until outcome/closure |
+| Run | What happened while executing a Task or Sprint? | Optional audit/handoff record |
 
 ```text
-FEAT-003
+SPRINT-012 (type: fix)
    └── TASK-018
-          ├── executed_by → RUN-044
-          ├── included_in → SPRINT-012
-          ├── constrained_by → DEC-018
-          └── generated → INS-041
+          ├── feature → FEAT-003
+          ├── depends_on → TASK-014, DEC-018
+          ├── guardrails → GR-004
+          └── run → RUN-044 (optional)
 ```
 
-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.
+Task is the executable unit. A Task may be independent of a Sprint. A Sprint groups Tasks and may be `feature`, `fix`, or `maintenance`. Runs are optional and never substitute for a Task's direct Markdown handoff.
 
 ## 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.
+All artifacts carry `id`, `kind`, `status`, `created`, `updated`, and `method`. Relations use simple frontmatter and relative links: `sprint: SPRINT-012`, `feature: FEAT-003`, `depends_on: [TASK-014, DEC-018]`, and `## Related`. Unknown fields and sections are preserved. 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.
+Approval creates or refines a Task. An optional Run can record strict audit or handoff history, but no Run, ledger, permit, or status synchronization blocks normal Markdown work. An approved Task continues through discover → implement → verify → fix → verify until its `## Done when` contract is delivered.
 
-Feature and Sprint provide context/grouping and do not own execution history. Review attaches evidence. Memory explains decisions and constraints across all of them.
+Feature and Sprint provide context/grouping and do not own execution history. Review attaches evidence. Knowledge, Decisions, and Insights explain constraints across all of them. Core and Guardrails are sealed Markdown policy: only explicit owner-reviewed maintenance may change them.
 
 ## Generated projections
 

package/docs/ERROR-CODES.md

@@ -77,6 +77,7 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 | `SR-E-150` | Guardrail check blocked the operation. | Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently. |
 | `SR-E-151` | Guardrail obligation is still pending. | Resolve each pending guardrail via `scrumrun plan run --satisfy-guardrail` before completing the Run. |
 | `SR-E-152` | Guardrail declaration is malformed. | Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check `.scrumrun/guardrails.md`. |
+| `SR-E-153` | Declarative Guardrail YAML is malformed. | Use the documented yaml enforcement block with match, on_violation, severity, and optional evidence. |
 
 ### Edit permits (Mutation Gateway)
 
@@ -121,6 +122,9 @@ SR-E-102 Run transition rejected: missing validation or learning evidence.
 |---|---|---|
 | `SR-E-450` | Conformance check failed. | The reported invariant identifies the exact violation; the message includes the file and expected shape. |
 | `SR-E-451` | Installed client asset is stale. | Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge. |
+| `SR-E-452` | Task Markdown is missing a required section. | Add the reported section (e.g. `## Request`, `## Done when`) to the Task file. The validator lives in `lib/v2/task-schema.js`. |
+| `SR-E-453` | Completed Task has no `## Completion` or associated Run `## Technical Summary`. | Append a short `## Completion` bullet list to the Task, or complete the Run with `plan run --complete --summary "..."`. |
+| `SR-E-454` | Task is running inside a git repository but no `git.branch` was captured. | Warning-only. Reconcile with `scrumrun repair --apply`, or add `git: { branch: <name>, base_sha: <sha> }` to the Task frontmatter. |
 
 ### Configuration and installation
 

package/docs/QUICKSTART.md

@@ -1,18 +1,19 @@
 # Quickstart
 
-Get from "never heard of it" to your first approved Run in under 10 minutes.
+Get from "never heard of it" to your first delivered Task in under 10 minutes.
 No `SPEC.md` reading required.
 
 ## The three-minute mental model
 
 ScrumRun gives an AI coding agent a small vocabulary and a project memory.
 
-- **Task** — one atomic piece of work.
-- **Sprint** — a batch of Tasks grouped by time or theme. Optional.
-- **Run** — one attempt at executing a Task. Retries create new Runs; the
-  previous one is never overwritten.
-- **Feature** — a bigger initiative that groups Tasks and its own decisions.
-- **Memory** — what the project learned: facts, decisions, insights, dossiers.
+- **Core** — how the agent works; read first and never edited during product work.
+- **Guardrails** — rules that cannot be broken.
+- **Knowledge** — facts, decisions, insights, and dossiers about the project.
+- **Task** — one concrete delivery, independent or inside a Sprint.
+- **Sprint** — a feature, fix, or maintenance batch of Tasks. Optional.
+- **Feature** — a bigger initiative that groups delivery context.
+- **Run** — optional audit/handoff Markdown for a Task or Sprint.
 
 Everything lives as Markdown under `.scrumrun/`. Any Markdown-capable agent
 can follow it.
@@ -64,24 +65,25 @@ command (`| less`, `> intake.txt`) or set `NO_COLOR=1` to get the plain
 Markdown summary instead; add `--json` for a fully structured payload
 you can feed to CI or a downstream tool.
 
-Only then does a Task and a Run get created.
+Only then does the Task become approved. The agent executes it directly in code and Markdown; a Run is optional.
 
-## Watching the Run
+## Delivering the Task
 
-The agent executes inside the approved scope. Every step lands in an
-append-only ledger under `.scrumrun/runs/RUN-NNN.md` with a stable event
-id, timestamp, actor, reason, and typed evidence.
+The agent executes inside the approved scope until `## Done when` is true.
+It does not stop after an inventory, partial fix, or progress report. Any
+missing implementation discovered in scope is work to do now, not a follow-up.
 
 ```
-RUN-001-EVT-001  planned by owner       reason: "checkout double-charge fix"
-RUN-001-EVT-002  executed               command: npm test  → 132 passed
-RUN-001-EVT-003  validated (REV-001)    guardrail checks: passed
-RUN-001-EVT-004  learned (INS-001)      "refresh triggers duplicate submit"
-RUN-001-EVT-005  completed
+TASK-001
+  → inspect the duplicate-submit path
+  → implement the fix
+  → run the relevant checks
+  → correct failures
+  → write ## Completion and status: completed
 ```
 
-A retry does not overwrite `RUN-001`. It creates `RUN-002` beside it. The
-old attempt stays as evidence.
+A Run may be added when a strict audit or detailed handoff is useful. It never
+needs to exist for normal work to start or finish.
 
 You can render a Run's ledger as a human timeline instead of reading the
 raw JSON:

package/docs/SCHEMA.md

@@ -20,9 +20,9 @@ The boundaries above are deliberately different: SPEC owns meanings, the executa
 | 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 |
+| task | `TASK-NNN` | `tasks/` | `backlog`, `proposed`, `in_progress`, `running` | scope, owner-defined sections, links, and status |
+| sprint | `SPRINT-NNN` | `sprints/` | `proposed` | timebox or delivery-batch membership; may be feature, fix, or maintenance |
+| run | `RUN-NNN` | `runs/` | `executing` | optional human-readable execution record and outcome |
 | 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 |
@@ -37,9 +37,9 @@ Every artifact also requires `id`, `kind`, `status`, `created`, `updated`, and `
 |---|---|---|---|
 | `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` | task (`TASK-NNN`) | 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.
+Task is the atomic unit. A Task may have zero or one Sprint. A Run is optional Markdown history and may reference either a Task or a Sprint; it never controls Task status in Markdown-first work. Sprint membership is authoritative on `Task.sprint`; a Sprint's `## Tasks` list is a human-readable projection that must agree with it. Additional owner-defined relations such as `depends_on: [TASK-014, DEC-018]` are preserved as local Markdown graph data.
 
 ## Scalar constraints
 
@@ -58,14 +58,14 @@ Newly authored Runs use `ledger: 1`. Their `## Events` section contains append-o
 
 Every event requires `schema`, `id`, contiguous `sequence`, RFC3339 `occurred_at`, `timestamp_precision`, `actor`, `from`, `to`, `reason`, and structured `evidence`. Event types are `transition`, `snapshot`, `guardrail`, `mutation`. Evidence kinds are `approval`, `command`, `test`, `file`, `review`, `decision`, `insight`, `risk`, `note`, `migration`, `legacy`, `guardrail`, `mutation`.
 
-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.
+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 when a strict audit Run is used. Run owns optional event history; Task Markdown owns the delivered scope and status in normal work.
 
 ## 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?
+- **task:** What concrete outcome is intended?
+- **sprint:** Which Tasks are grouped for this delivery?
+- **run:** What happened while executing a Task or Sprint?
 - **review:** What independent validation was performed?
 - **knowledge:** What verified project fact is reusable?
 - **decision:** What normative choice constrains future work?
@@ -77,7 +77,7 @@ A native ledger begins with `created → executing`; an evidenced migration `sna
 | 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 |
+| task | `backlog` → `proposed`, `in_progress`, `running`, `cancelled`<br>`proposed` → `in_progress`, `running`, `cancelled`<br>`in_progress` → `completed`, `failed`, `blocked`, `cancelled`<br>`running` → `validating`, `completed`, `failed`, `blocked`, `cancelled`<br>`validating` → `learning`, `completed`, `failed`, `blocked`<br>`learning` → `completed`, `failed`, `blocked`<br>`partial` → `in_progress`, `running`, `cancelled`<br>`completed` → terminal<br>`failed` → `in_progress`, `running`, `cancelled`<br>`blocked` → `in_progress`, `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 |
@@ -86,6 +86,10 @@ A native ledger begins with `created → executing`; an evidenced migration `sna
 | 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 |
 
+## Declarative Guardrail enforcement
+
+Project Guardrails may include an optional fenced `yaml enforcement` block. Its restricted, dependency-free YAML schema is defined normatively in `SPEC.md §6.1`: `match.paths[]`, `match.diff[]`, `match.symbols[]`, `on_violation` (`block` or `warn`), `severity`, and optional `evidence`. The pure evaluator consumes only that normalized rule data and a supplied ChangeSet; it has no network or LLM dependency. Prose-only Guardrails remain valid.
+
 ## 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

@@ -66,3 +66,31 @@ scrumrun knowledge context --clear
 ```
 
 SQLite is ignored and disposable. The derived index records its search backend: FTS5/BM25 is selected when the current Node.js SQLite build supports it; otherwise ScrumRun uses deterministic parameterized token matching over the same artifact, code, and relation tables. 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.
+
+## Deterministic Dossier compaction
+
+Compaction is an opt-in maintenance operation for a project with many related,
+already reviewed memory records. It never calls an LLM and never runs in the
+background:
+
+```bash
+scrumrun knowledge dossier --compact --dry-run
+scrumrun knowledge dossier --compact --apply --approve
+scrumrun knowledge dossier --compact --rollback DOS-001
+```
+
+Only approved Knowledge and confirmed Insights without `superseded_by` are
+eligible. Each record is represented by its subject, declared relations
+(including `used_by`), and explicit `#tags` or `## Tags`/`## Topics` bullets.
+Two records are connected when the Jaccard overlap of those features is at
+least `memory.compaction.threshold` (default `0.6`). Connected components with
+at least `memory.compaction.min_members` records (default `3`) become proposed
+clusters. IDs, feature sorting, links, and labels are all deterministic.
+
+Dry-run is read-only and reports member IDs, pair evidence, score and effective
+configuration. Apply additionally requires the explicit `--approve` flag: it
+creates a Dossier with original artifact IDs as evidence and adds only
+`superseded_by: DOS-NNN` to the source records. Sources are never deleted. The
+Dossier holds a reversible snapshot; rollback restores byte-exact sources only
+when they have not changed since compaction, then archives the Dossier. This
+refusal protects later owner edits rather than overwriting them.

package/lib/actions/index.js

@@ -0,0 +1,81 @@
+"use strict";
+
+const { addPlanArtifact, amendPlanArtifact } = require("../runtime/orchestrator");
+const { createMemory } = require("../memory/service");
+
+const REGISTRY = Object.freeze({
+  "plan.task.add": {
+    describe: "Create a Task (optionally as backlog or fix).",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return addPlanArtifact(projectRoot, "task", payload.title, {
+        type: payload.type || null,
+        status: payload.status || null
+      });
+    }
+  },
+  "plan.feature.add": {
+    describe: "Create a Feature.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return addPlanArtifact(projectRoot, "feature", payload.title, {});
+    }
+  },
+  "plan.sprint.add": {
+    describe: "Create a Sprint.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return addPlanArtifact(projectRoot, "sprint", payload.title, {});
+    }
+  },
+  "plan.task.amend": {
+    describe: "Amend an existing Task's title/sections/type/feature/sprint.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "id");
+      return amendPlanArtifact(projectRoot, "task", payload.id, payload);
+    }
+  },
+  "knowledge.fact.add": {
+    describe: "Create a Knowledge (K-NNN) candidate.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return createMemory(projectRoot, "knowledge", payload);
+    }
+  },
+  "knowledge.decision.add": {
+    describe: "Create a Decision (DEC-NNN) candidate.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return createMemory(projectRoot, "decision", payload);
+    }
+  },
+  "knowledge.insight.propose": {
+    describe: "Propose an Insight (INS-NNN) candidate.",
+    handler: (projectRoot, payload) => {
+      requireString(payload, "title");
+      return createMemory(projectRoot, "insight", payload);
+    }
+  }
+});
+
+function requireString(payload, field) {
+  if (!payload || typeof payload[field] !== "string" || !payload[field].trim()) {
+    throw new Error(`payload.${field} must be a non-empty string`);
+  }
+}
+
+function listActions() {
+  return Object.entries(REGISTRY).map(([name, { describe }]) => ({ name, describe }));
+}
+
+function executeAction(name, projectRoot, payload) {
+  const entry = REGISTRY[name];
+  if (!entry) {
+    const known = Object.keys(REGISTRY).sort().join(", ");
+    throw new Error(`Unknown action "${name}". Known actions: ${known}`);
+  }
+  const normalizedPayload = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  return entry.handler(projectRoot, normalizedPayload);
+}
+
+module.exports = { REGISTRY, executeAction, listActions };

package/lib/commands/manifest.js

@@ -36,7 +36,7 @@ const nouns = Object.freeze({
       fact: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--approve [--evidence] [--note]", "--reject [--note]", "--deprecate [--note]", "--invalidate [--note]"],
       decision: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--resolve [--evidence] [--note]", "--deprecate [--note]", "--invalidate [--note]"],
       insight: ["--propose [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--confidence] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--confirm [--evidence] [--note]", "--stale [--note]", "--reject [--note]", "--deprecate [--note]", "--invalidate [--note]"],
-      dossier: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--refresh [--evidence] [--note]", "--stale [--note]", "--deprecate [--note]", "--archive [--note]"],
+      dossier: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--refresh [--evidence] [--note]", "--stale [--note]", "--deprecate [--note]", "--archive [--note]", "--compact --dry-run", "--compact --apply --approve", "--compact --rollback <DOS-NNN>"],
       context: ["--build", "--update", "--show", "--clear"],
       map: ["--build", "--show"],
       errors: ["--show"],
@@ -55,7 +55,7 @@ const nouns = Object.freeze({
     description: "run scoped evidence-based quality gates",
     subjects: {
       code: ["--run"],
-      artifact: ["--run", "--record --task <TASK-NNN> [--run <RUN-NNN>] [--title] [--evidence]"],
+      artifact: ["--run [--staged]", "--record --task <TASK-NNN> [--run <RUN-NNN>] [--title] [--evidence]"],
       migration: ["--run"],
       release: ["--run"]
     }
@@ -65,9 +65,10 @@ const nouns = Object.freeze({
     subjects: {
       project: ["--show", "--language", "--interaction", "--approval", "--quick-tasks"],
       init: ["--local", "--shared", "--lean", "--no-agent-hint", "--force"],
-      update: ["all [--migrate]", "codex [--migrate]", "opencode [--migrate]", "claude [--migrate]"],
+      update: ["all [--project] [--seal-policy] [--migrate]", "codex [--project] [--seal-policy] [--migrate]", "opencode [--project] [--seal-policy] [--migrate]", "claude [--project] [--seal-policy] [--migrate]"],
       migrate: ["--to 2 --dry-run", "--to 2 --apply", "--to 2 --rollback"],
       doctor: ["all [--strict] [--recover] [--dry-run]", "codex [--strict] [--recover] [--dry-run]", "opencode [--strict] [--recover] [--dry-run]", "claude [--strict] [--recover] [--dry-run]"],
+      watch: ["--start", "--stop", "--status"],
       uninstall: ["--force"],
       help: ["<topic>"]
     }

package/lib/commands/render.js

@@ -29,15 +29,16 @@ ${grammarLines().join("\n")}
 
 - Natural-language product work begins with a read-only understanding pass; do not invoke \`plan intake\` merely to satisfy procedure.
 - Intake, contextualization, policy, risk, classification, and planning are read-only until explicit approval.
-- After approval, work directly in source files and relevant \`.scrumrun/\` Markdown. Create/refine a Task, acceptance criteria, technical summary, and follow-ups directly. Feature/Sprint/Run are useful only when they add context.
+- After approval, work directly in source files and relevant \`.scrumrun/\` Markdown until the approved Task is delivered. Keep executing discover → implement → verify → fix → verify; a progress report is allowed only when the owner asks for it and never ends the workflow. Do not answer with an inventory, partial progress report, decomposition, or remaining-work list; those are internal steps. A gap discovered in scope is work to implement now, not a “next step”. Feature/Sprint/Run are useful only when they add context.
 - A Run is optional audit/handoff context, never a prerequisite for starting, amending, or completing a Task. Do not block on a missing Run, a legacy status, or stale generated state.
 - The CLI can inspect/repair/report structured artifacts, but it does not own the daily workflow.
 - \`guardrails.md\` is canonical project policy; \`golden-rules.md\` is v1 compatibility only.
 - Evaluate active Guardrails as \`passed\`, \`blocked\`, or \`deferred\`; cite exact \`GR-NNN\` ids and keep deferred execution gates visible.
-- Block only for an explicit Guardrail, secret/security risk, destructive action without approval, or an unmet required Acceptance Criterion. Optional unrun E2E/review coverage is a follow-up/risk, not a failed Run.
+- Block only for an explicit Guardrail, secret/security risk, destructive action without approval, or an unmet required delivery criterion. \`Follow-ups\` may only contain work outside the approved \`Done when\` contract; optional unrun E2E/review coverage is a follow-up/risk, not a failed Run.
 - Use the CLI only for \`init\`, \`update --project\`, \`migrate\`, \`repair\`, \`doctor\`, reports, or release checks. Do not invoke \`npx scrumrun@latest\` during execution.
 - Never invoke \`plan run --fail|--block|--retry|--finalize|--complete|--validate\` or \`plan task --start\` during normal work. These optional strict-audit commands must not decide a Task outcome.
 - Strict per-path Mutation Gateway permits and ledger finalization remain available only when the owner explicitly requests strict execution.
+- Never edit \`core.md\` or \`guardrails.md\` during product work. They are sealed policy; owner-requested policy changes are reviewed and sealed at the maintenance edge.
 - Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
 - Never print vault values or write before approval.
 - Unknown nouns, subjects, actions, ids, or ambiguous approval must produce a deterministic explanation, never a guessed mutation.

package/lib/errors.js

@@ -40,6 +40,7 @@ const CATALOG = Object.freeze({
   "SR-E-150": { summary: "Guardrail check blocked the operation.", remediation: "Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently." },
   "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `scrumrun plan run --satisfy-guardrail` before completing the Run." },
   "SR-E-152": { summary: "Guardrail declaration is malformed.", remediation: "Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check .scrumrun/guardrails.md." },
+  "SR-E-153": { summary: "Declarative Guardrail YAML is malformed.", remediation: "Use the documented yaml enforcement block with match, on_violation, severity, and optional evidence." },
 
   // Edit permits (Mutation Gateway)
   "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `scrumrun plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
@@ -66,6 +67,9 @@ const CATALOG = Object.freeze({
   // Conformance / doctor
   "SR-E-450": { summary: "Conformance check failed.", remediation: "The reported invariant identifies the exact violation; the message includes the file and expected shape." },
   "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge." },
+  "SR-E-452": { summary: "Task Markdown is missing a required section.", remediation: "Add the reported section (e.g. `## Request`, `## Done when`) to the Task file. The validator lives in `lib/v2/task-schema.js`." },
+  "SR-E-453": { summary: "Completed Task has no `## Completion` or associated Run `## Technical Summary`.", remediation: "Append a short `## Completion` bullet list to the Task, or complete the Run with `plan run --complete --summary \"...\"`." },
+  "SR-E-454": { summary: "Task is running inside a git repository but no `git.branch` was captured.", remediation: "Warning-only. Reconcile with `scrumrun repair --apply`, or add `git: { branch: <name>, base_sha: <sha> }` to the Task frontmatter." },
 
   // Configuration / install
   "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `scrumrun init` in the repository root." },

package/lib/git/context.js

@@ -0,0 +1,30 @@
+"use strict";
+
+const { execFileSync } = require("node:child_process");
+
+function git(projectRoot, args) {
+  try {
+    const output = execFileSync("git", args, {
+      cwd: projectRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return output.replace(/\r?\n$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function readGitContext(projectRoot) {
+  const inside = git(projectRoot, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside !== "true") return { isRepo: false, branch: null, headSha: null };
+  const branch = git(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const headSha = git(projectRoot, ["rev-parse", "HEAD"]);
+  return {
+    isRepo: true,
+    branch: branch === "HEAD" ? null : branch,
+    headSha: headSha || null
+  };
+}
+
+module.exports = { readGitContext };

package/lib/guardrails/changeset.js

@@ -0,0 +1,45 @@
+"use strict";
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function git(projectRoot, args) {
+  try { return execFileSync("git", args, { cwd: projectRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
+  catch { return null; }
+}
+
+function existsAtHead(projectRoot, relative) {
+  try {
+    execFileSync("git", ["cat-file", "-e", `HEAD:${relative}`], { cwd: projectRoot, stdio: "ignore" });
+    return true;
+  } catch { return false; }
+}
+
+function changedPaths(projectRoot, staged) {
+  const names = git(projectRoot, staged ? ["diff", "--cached", "--name-only", "--diff-filter=ACMR"] : ["diff", "HEAD", "--name-only", "--diff-filter=ACMR"]);
+  const paths = names === null ? [] : names.split(/\r?\n/).filter(Boolean);
+  if (staged) return paths;
+  const status = git(projectRoot, ["status", "--porcelain"]);
+  if (status !== null) {
+    for (const line of status.split(/\r?\n/)) {
+      const candidate = line.slice(3).trim();
+      if (candidate && !candidate.includes(" -> ")) paths.push(candidate);
+    }
+  }
+  return [...new Set(paths)];
+}
+
+function collectChangeSet(projectRoot, { staged = false } = {}) {
+  const diff = git(projectRoot, staged ? ["diff", "--cached", "--no-ext-diff", "--unified=0"] : ["diff", "HEAD", "--no-ext-diff", "--unified=0"]);
+  const paths = changedPaths(projectRoot, staged);
+  const untrackedContent = staged ? "" : paths
+    .filter((relative) => !existsAtHead(projectRoot, relative))
+    .map((relative) => {
+      const file = path.join(projectRoot, relative);
+      try { return fs.statSync(file).isFile() ? `\n--- ${relative}\n${fs.readFileSync(file, "utf8")}` : ""; } catch { return ""; }
+    }).join("");
+  return { paths, diff: `${diff || ""}${untrackedContent}`, symbols: [], source: staged ? "git-index" : "git-worktree" };
+}
+
+module.exports = { collectChangeSet };