scrumrun 2.0.0 → 2.1.0

package/templates/shared/skills/scrumrun/SKILL.md

@@ -37,6 +37,8 @@ Normal hot path:
 
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
+Generated state and semantic indexes use a metadata-watch fast path with a full content-hash fallback. Treat cache-schema mismatch as a request to rebuild the disposable projection, never as permission to rewrite canonical Markdown.
+
 For a v1 project without canonical v2 artifacts, use the dual-layout reader conceptually and recommend `scrumrun migrate --to 2 --dry-run`. `update` may run that read-only preflight automatically, but only explicit `update --migrate` may apply it.
 
 ## Domain model
@@ -74,6 +76,8 @@ At intake:
 5. recommend one route and at most two useful alternatives in guided mode;
 6. ask one explicit approval question before execution; config may change presentation, never remove the gate.
 
+Evaluate every active Guardrail into a structured `passed`, `blocked`, or `deferred` result. Report blocked results with the exact `GR-NNN` id and reason code. Keep deferred results visible and enforce them at the mutation, migration, review, or owner gate they identify; never describe a deferred check as passed.
+
 Do not create canonical artifacts, change status, edit application code, or treat ambiguous acknowledgement as approval. Temporary context may exist only in ignored disposable cache.
 
 ## Approved execution
@@ -91,13 +95,17 @@ During execution:
 2. preserve existing owner work and unrelated dirty files;
 3. enforce guardrails before every material mutation;
 4. validate in proportion to risk;
-5. record exactly one history event per state transition;
+5. record exactly one structured `RUN-NNN-EVT-NNN` event per state transition, with RFC3339 time, actor, reason, and typed evidence;
 6. run configured reviewers;
 7. extract candidate learning only after validation;
 8. complete the Run, then Task, and only then the Sprint when its whole batch is done.
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
 
+Run is the sole operational-history authority. Task synchronizes current status without copying Run events. Validation, learning, completion, failure, block, and resume require a reason or structured evidence; completion also requires evidenced validation and learning. Early v2 prose Runs are migrated explicitly, with deterministic chains recovered and uncertain history represented as an evidenced snapshot.
+
+Linked canonical writes use the ignored durable transaction journal. An interrupted prepared mutation rolls back before the next approved mutation; a committed journal is verified and finalized. Audit remains read-only and reports pending recovery. Use `doctor --recover` only when explicitly requested, and never overwrite bytes changed after interruption.
+
 ## Semantic memory
 
 Canonical memory is Markdown:
@@ -118,6 +126,8 @@ Useful relations include `defined_in`, `depends_on`, `used_by`, `constrained_by`
 `.scrumrun/guardrails.md` is the sole canonical project-policy artifact in v2. `golden-rules.md` is a v1 compatibility source only.
 
 - Guardrails are mandatory, stable-id, append-preserving policies.
+- Fresh v2 rules declare `Status`, `Enforcement`, `Scope`, and `Rule`; migrated prose may use deterministic enforcement inference until normalized.
+- Duplicate ids, unknown enforcement, inactive-only policy, and configuration that weakens approval are conformance failures.
 - Retire/supersede a rule; do not silently delete policy history.
 - `config.md` stores preferences, never higher-priority safety policy.
 - Never commit or print vault values.
@@ -136,7 +146,7 @@ scrumrun migrate --to 2 --rollback
 
 Inside a v1 project, `npx scrumrun@latest update` runs a read-only preflight. `update --migrate` explicitly approves application of that verified plan and keeps rollback available.
 
-Dry-run must not write project data. Apply requires a hashed inventory, byte-exact local backup, staged validation, atomic switch, mapping report, and idempotent replay. Incomplete hybrid trees reuse existing evidenced v2 relations rather than duplicating them; legacy-only aggregates leave the active tree but remain byte-exact in the ignored backup. Ambiguous records are preserved and warned, never guessed. Vault content remains local and is never rendered. Rollback must refuse if it would erase post-migration changes.
+Dry-run must not write project data. Apply requires a hashed inventory, byte-exact local backup, staged validation, atomic switch, mapping report, and idempotent replay. Incomplete hybrid trees reuse existing evidenced v2 relations rather than duplicating them; early v2 prose Runs upgrade to ledger schema 1 only through the same explicit apply gate. Legacy-only aggregates leave the active tree but remain byte-exact in the ignored backup. Ambiguous records are preserved as warnings or evidenced snapshots, never guessed. Vault content remains local and is never rendered. Rollback must refuse if it would erase post-migration changes.
 
 ## Command grammar
 
@@ -180,7 +190,7 @@ Review is read-only unless the user separately authorizes fixes.
 - `init`: initialize ScrumRun without overwriting existing state silently.
 - `update`: refresh integrations and preflight v1 read-only; apply only with explicit `--migrate`.
 - `migrate`: invoke the explicit migration workflow.
-- `doctor`: verify installed root command and skill content; `--strict` also requires a warning-free project artifact audit.
+- `doctor`: verify installed root command and skill content; `--strict` also requires a warning-free project artifact audit, while explicit `--recover` resolves safe pending kernel transactions.
 - `uninstall`: preview by default; delete only recognized ScrumRun files with explicit `--force`.
 - `help`: show grammar or one focused topic.