its-magic 0.1.2-23 → 0.1.2-25

package/README.md

@@ -210,6 +210,17 @@ Deterministic ordering behavior (US-0058):
   remain sorted-canonical by story ID.
 - Commands fail closed on ambiguous placement anchors using
   `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`.
+- Commands fail closed on non-monotonic state checkpoint timestamps using
+  `STATE_TIMESTAMP_NON_MONOTONIC`.
+
+Intake runtime safety behavior (US-0059):
+- `/intake` requires role-specific `po` capability by default and fails fast with
+  `SUBAGENT_CAPABILITY_UNAVAILABLE` when unavailable.
+- Silent in-band fallback is disabled by default and only allowed with explicit
+  `INTAKE_SUBAGENT_FALLBACK=allow`.
+- Drift detection distinguishes self-write updates from external concurrent
+  writers; true conflicting external writes fail safe with
+  `INTAKE_CONCURRENT_WRITER_DETECTED`.
 
 ## Workflow
 
@@ -307,6 +318,12 @@ Compaction behavior:
   `docs/engineering/state-archive/`.
 - `docs/engineering/decisions.md` stays a compact index with bounded summaries
   and canonical links to `decisions/DEC-xxxx.md`.
+- Enforced rollover thresholds:
+  - `STATE_HOT_MAX_LINES` (default `1200`)
+  - `STATE_HOT_MAX_CHECKPOINTS` (default `80`)
+  `/refresh-context` must archive oldest checkpoints into deterministic
+  `state-pack-*` files when thresholds are exceeded, keeping only bounded recent
+  checkpoints in hot surface.
 
 `/ask` policy (read-only):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-23",
+  "version": "0.1.2-25",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/template/.cursor/commands/intake.md

@@ -28,6 +28,26 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
 - Missing acceptance criteria or unclear scope
 - Decision gate triggered (see escalation rule)
 
+## Runtime capability and writer-safety guard (US-0059 / DEC-0041)
+
+- `/intake` requires the role-specific `po` subagent capability by default.
+- Before any artifact mutation, run capability preflight:
+  - if `po` capability is unavailable, fail fast with
+    `SUBAGENT_CAPABILITY_UNAVAILABLE`,
+  - emit deterministic remediation guidance (for example: enable role-capable
+    runtime or explicitly opt in to fallback policy).
+- Silent in-band fallback is forbidden unless explicit policy opt-in is
+  configured (`INTAKE_SUBAGENT_FALLBACK=allow`).
+- For artifact mutations, enforce deterministic single-writer scope:
+  - establish writer identity (`writer_id`) and run identity (`intake_run_id`),
+  - bind writes to target artifacts (`backlog`, `acceptance`, `vision`,
+    `po_to_tl`) for this run.
+- Drift guard semantics:
+  - self-write changes from the same `(writer_id, intake_run_id)` are valid and
+    must not trigger concurrent-writer blockers,
+  - external conflicting mutation during active run must fail safe with
+    `INTAKE_CONCURRENT_WRITER_DETECTED` and no partial overwrite.
+
 ## Steps
 1. Determine intake mode from `.cursor/scratchpad.md`:
    - guided mode: `INTAKE_GUIDED_MODE=1` (default)
@@ -129,4 +149,7 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
   - `handoffs/po_to_tl.md` may prepend the latest handoff section only.
 - If the insertion anchor for any target section is missing/ambiguous, fail with
   `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS` and avoid partial writes.
+- If intake appends a `docs/engineering/state.md` checkpoint, enforce UTC
+  monotonic timestamp guard (`new >= last`); on violation fail with
+  `STATE_TIMESTAMP_NON_MONOTONIC` and avoid partial writes.
 

package/template/.cursor/commands/refresh-context.md

@@ -27,6 +27,12 @@ description: "its-magic refresh context: compact state and decisions."
 1. Compact state and decisions into a short context pack.
 2. Update sprint summary with current status.
 3. Ensure handoffs and state are consistent.
+4. Enforce state hot-surface rollover when configured thresholds are exceeded:
+   - evaluate `STATE_HOT_MAX_LINES` and `STATE_HOT_MAX_CHECKPOINTS` from
+     `.cursor/scratchpad.md`,
+   - archive oldest low-frequency checkpoints into deterministic pack files under
+     `docs/engineering/state-archive/`,
+   - preserve only bounded recent checkpoints in `docs/engineering/state.md`.
 
 ## Deterministic artifact ordering contract (US-0058 / DEC-0040)
 
@@ -38,4 +44,7 @@ description: "its-magic refresh context: compact state and decisions."
   context section; historical details remain intact.
 - Missing/ambiguous anchors fail with `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`
   (no partial write).
+- Archive write or rollover boundary ambiguity fails with
+  `STATE_ARCHIVE_WRITE_FAILED` or `STATE_ARCHIVE_BOUNDARY_AMBIGUOUS`
+  (no partial write).
 

package/template/.cursor/scratchpad.local.example.md

@@ -96,17 +96,26 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 # Knowledge curation / intake
 # - EARLY_RESEARCH: 0|1 (PO/TL search web during intake/architecture)
 # - INTAKE_GUIDED_MODE: 0|1 (guided intake follow-up/options/research behavior)
+# - INTAKE_SUBAGENT_FALLBACK: deny|allow (deny by default; when deny, missing
+#   role-specific intake subagent capability fails fast)
 # - ID_NAMESPACE_BOOTSTRAP: 0|1 (optional fresh-project ID bootstrap mode; when 1, allow first IDs to start at 0001 only if deterministic freshness checks pass)
 # - TOKEN_PROFILE: lean|balanced|full (tiered token-cost profile defaults)
 #   - lean: lowest-token default profile; reduce non-critical automation/research intensity
 #   - balanced: default profile; preserves current behavior with moderate overhead
 #   - full: highest-context profile; maximize context breadth/autonomy
+# - STATE_HOT_MAX_LINES: integer >= 200 (hot-surface soft cap trigger for
+#   archival rollover checks)
+# - STATE_HOT_MAX_CHECKPOINTS: integer >= 10 (max recent checkpoints to retain
+#   in `state.md` after rollover)
 # - Manual-override precedence: explicit flag values in this file remain authoritative
 #   for that flag and override profile defaults.
 EARLY_RESEARCH=1
 INTAKE_GUIDED_MODE=1
+INTAKE_SUBAGENT_FALLBACK=deny
 ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
+STATE_HOT_MAX_LINES=1200
+STATE_HOT_MAX_CHECKPOINTS=80
 #
 # Publish targets
 # - RELEASE_PUBLISH_MODE: disabled|confirm|auto

package/template/.cursor/scratchpad.md

@@ -41,11 +41,11 @@ MAGIC_BENCH_SESSION=
 # - AUTO_EXECUTE_ON_BLOCK: stop|skip (behavior when a planned item blocks)
 # - AUTO_EXECUTE_SELECTION: planned_then_priority
 # - AUTO_TEAM_SCOPE_ENFORCE: 0|1 (when TEAM_MODE=1, enforce TEAM_MEMBER + ACTIVE_TASK_IDS)
-AUTO_FLOW_MODE=manual
+AUTO_FLOW_MODE=auto_until_decision
 PHASE_MODE=interactive
 PERMISSION_MODE=interactive
 AUTO_INSTALL_DEPS=0
-AUTO_RELEASE_NOTES=0
+AUTO_RELEASE_NOTES=1
 AUTO_BACKLOG_DRAIN=0
 AUTO_BACKLOG_MAX_STORIES=1
 AUTO_BACKLOG_ON_BLOCK=stop
@@ -56,6 +56,14 @@ AUTO_EXECUTE_ON_BLOCK=stop
 AUTO_EXECUTE_SELECTION=planned_then_priority
 AUTO_TEAM_SCOPE_ENFORCE=1
 #
+# Team mode
+# - TEAM_MODE: 0|1 (enable task/member scoped team workflow)
+# - TEAM_MEMBER: short id for current developer
+# - ACTIVE_TASK_IDS: comma-separated task ids (for example T-12,T-13)
+TEAM_MODE=0
+TEAM_MEMBER=
+ACTIVE_TASK_IDS=
+#
 # Sprint planning
 # - SPRINT_MAX_TASKS: integer >= 1 (max atomic tasks per sprint, default 12)
 # - SPRINT_AUTO_SPLIT: 0|1 (propose splitting when over threshold)
@@ -86,22 +94,31 @@ SYNC_CUSTOM_PHASES=
 ALLOW_AUTO_PUSH=0
 AUTO_PUSH_BRANCH_ALLOWLIST=
 #
-# Knowledge curation
+# Knowledge curation / intake
 # - EARLY_RESEARCH: 0|1 (PO/TL search web during intake/architecture)
 # - INTAKE_GUIDED_MODE: 0|1 (guided intake follow-up/options/research behavior)
+# - INTAKE_SUBAGENT_FALLBACK: deny|allow (deny by default; when deny, missing
+#   role-specific intake subagent capability fails fast)
 # - ID_NAMESPACE_BOOTSTRAP: 0|1 (optional fresh-project ID bootstrap mode; when 1, allow first IDs to start at 0001 only if deterministic freshness checks pass)
 # - TOKEN_PROFILE: lean|balanced|full (tiered token-cost profile defaults)
 #   - lean: lowest-token default profile; reduce non-critical automation/research intensity
 #   - balanced: default profile; preserves current behavior with moderate overhead
 #   - full: highest-context profile; maximize context breadth/autonomy
+# - STATE_HOT_MAX_LINES: integer >= 200 (hot-surface soft cap trigger for
+#   archival rollover checks)
+# - STATE_HOT_MAX_CHECKPOINTS: integer >= 10 (max recent checkpoints to retain
+#   in `state.md` after rollover)
 # - Manual-override precedence: explicit flag values in this file remain authoritative
 #   for that flag and override profile defaults.
 EARLY_RESEARCH=1
 INTAKE_GUIDED_MODE=1
+INTAKE_SUBAGENT_FALLBACK=deny
 ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
+STATE_HOT_MAX_LINES=1200
+STATE_HOT_MAX_CHECKPOINTS=80
 
-# Publish targets (US-0054)
+# Publish targets
 # - RELEASE_PUBLISH_MODE: disabled|confirm|auto
 #   - disabled: skip post-release publish target execution
 #   - confirm: require explicit operator confirmation before publish (default)
@@ -121,7 +138,7 @@ RELEASE_TARGETS_DEFAULT=
 SECURITY_REVIEW=0
 COMPLIANCE_PROFILES=GDPR
 
-# Cross-repo compatibility observability
+# Compatibility observability
 # - CROSS_REPO_OBSERVABILITY: 0|1 (enable compatibility visibility and checks)
 # - COMPATIBILITY_GATE_ON_CRITICAL: 0|1 (when enabled, critical unresolved
 #   compatibility findings trigger decision gate before release)
@@ -131,19 +148,15 @@ CROSS_REPO_OBSERVABILITY=0
 COMPATIBILITY_GATE_ON_CRITICAL=1
 COMPATIBILITY_SOURCES=
 
-# Component-scoped execution mode
+# Component scope
 # - COMPONENT_SCOPE_MODE: 0|1 (enable scoped planning/execution guardrails)
 # - TARGET_COMPONENTS: comma-separated component IDs intended in scope
 COMPONENT_SCOPE_MODE=0
 TARGET_COMPONENTS=
 
-# Optional spec-pack documentation (US-0031)
+# Optional docs packs
 # - SPEC_PACK_MODE: 0|1 (enable Design Concept, CRS, Technical Spec generation/validation; default 0)
 #   When 0, intake/architecture/release add no required spec-pack steps.
 SPEC_PACK_MODE=0
-
-# Optional user-guide documentation (US-0032)
-# - USER_GUIDE_MODE: 0|1 (enable per-feature user guides at docs/user-guides/US-xxxx.md; default 0)
-#   When 0, intake/architecture/sprint-plan/execute/qa/release add no required user-guide steps or blocking checks.
 USER_GUIDE_MODE=0
 

package/template/README.md

@@ -210,6 +210,17 @@ Deterministic ordering behavior (US-0058):
   remain sorted-canonical by story ID.
 - Commands fail closed on ambiguous placement anchors using
   `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`.
+- Commands fail closed on non-monotonic state checkpoint timestamps using
+  `STATE_TIMESTAMP_NON_MONOTONIC`.
+
+Intake runtime safety behavior (US-0059):
+- `/intake` requires role-specific `po` capability by default and fails fast with
+  `SUBAGENT_CAPABILITY_UNAVAILABLE` when unavailable.
+- Silent in-band fallback is disabled by default and only allowed with explicit
+  `INTAKE_SUBAGENT_FALLBACK=allow`.
+- Drift detection distinguishes self-write updates from external concurrent
+  writers; true conflicting external writes fail safe with
+  `INTAKE_CONCURRENT_WRITER_DETECTED`.
 
 ## Workflow
 
@@ -307,6 +318,12 @@ Compaction behavior:
   `docs/engineering/state-archive/`.
 - `docs/engineering/decisions.md` stays a compact index with bounded summaries
   and canonical links to `decisions/DEC-xxxx.md`.
+- Enforced rollover thresholds:
+  - `STATE_HOT_MAX_LINES` (default `1200`)
+  - `STATE_HOT_MAX_CHECKPOINTS` (default `80`)
+  `/refresh-context` must archive oldest checkpoints into deterministic
+  `state-pack-*` files when thresholds are exceeded, keeping only bounded recent
+  checkpoints in hot surface.
 
 `/ask` policy (read-only):
 

package/template/docs/engineering/artifact-ordering-policy.md

@@ -8,7 +8,7 @@ anchors are missing or ambiguous.
 
 | Artifact | Policy | Deterministic rule |
 |---|---|---|
-| `docs/engineering/state.md` | `append-bottom` | Add new checkpoints only at end of file, in chronological order. |
+| `docs/engineering/state.md` | `append-bottom` | Add new checkpoints only at end of file, in chronological order; enforce hot-surface rollover when configured thresholds are exceeded. |
 | `docs/product/backlog.md` | `sorted-canonical` | Keep stories sorted by numeric `US-xxxx` ID; mutate only target story block. |
 | `docs/product/acceptance.md` | `sorted-canonical` | Keep `US-xxxx` rows ordered by numeric ID aligned to backlog order. |
 | `handoffs/release_queue.md` | `append-bottom` | Append only one row per new sprint in release order. |
@@ -20,6 +20,10 @@ anchors are missing or ambiguous.
 - Re-running a command without semantic changes must not reorder rows/blocks.
 - No oscillation between top and bottom insertion paths.
 - No broad rewrites of unrelated story/sprint entries.
+- For `docs/engineering/state.md`, each newly appended checkpoint timestamp must
+  be monotonic (`new_timestamp >= last_checkpoint_timestamp`) in UTC.
+- For rollover reruns, archive partition boundaries and pack naming must be
+  deterministic (no duplicate or oscillating pack generation).
 
 ## Fail-safe behavior
 
@@ -27,3 +31,16 @@ If required placement anchors are missing or ambiguous:
 - stop with reason code `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`,
 - emit remediation guidance with expected anchor and file path,
 - perform no partial mutation.
+
+If a new `state.md` checkpoint timestamp is older than the current last
+checkpoint timestamp:
+- stop with reason code `STATE_TIMESTAMP_NON_MONOTONIC`,
+- emit remediation guidance with the expected minimum timestamp,
+- perform no partial mutation.
+
+If configured state hot-surface rollover cannot determine a safe archive
+boundary or cannot persist archive pack writes:
+- stop with reason code `STATE_ARCHIVE_BOUNDARY_AMBIGUOUS` or
+  `STATE_ARCHIVE_WRITE_FAILED`,
+- emit remediation guidance with threshold/boundary details and target path,
+- perform no partial mutation.

package/template/docs/engineering/runbook.md

@@ -131,6 +131,17 @@ Context compaction policy:
   append-only/non-destructive.
 - `docs/engineering/decisions.md` is a compact index with bounded summaries and
   canonical links to full records in `decisions/DEC-xxxx.md`.
+- Enforced rollover thresholds:
+  - `STATE_HOT_MAX_LINES` (default `1200`)
+  - `STATE_HOT_MAX_CHECKPOINTS` (default `80`)
+  When either threshold is exceeded during `/refresh-context`, older checkpoints
+  are archived into deterministic `state-pack-*` files and only bounded recent
+  checkpoints remain in hot surface.
+
+Rollover fail-safe reason codes:
+
+- `STATE_ARCHIVE_BOUNDARY_AMBIGUOUS`
+- `STATE_ARCHIVE_WRITE_FAILED`
 
 `/ask` retrieval policy:
 
@@ -834,6 +845,8 @@ Required write discipline:
 Fail-safe contract:
 - Missing/ambiguous placement anchors fail closed with
   `ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS`.
+- Non-monotonic `state.md` checkpoint timestamps fail closed with
+  `STATE_TIMESTAMP_NON_MONOTONIC`.
 - No partial mutation on fail-safe path.
 - Re-run without semantic changes must be ordering-idempotent.
 
@@ -842,6 +855,28 @@ Execution guidance:
 - Packaging smoke: run npm local tests in `packaging/npm/`.
 - CI evidence: inspect `npm-test`, `brew-test`, and `choco-test` job logs.
 
+## Intake runtime capability and single-writer safety (US-0059 / DEC-0041)
+
+`/intake` enforces deterministic runtime preflight and drift safety before
+artifact mutation.
+
+Capability preflight:
+- Required role capability: `po` subagent.
+- Default policy: fail fast when unavailable with
+  `SUBAGENT_CAPABILITY_UNAVAILABLE`.
+- Fallback policy is explicit only:
+  - `INTAKE_SUBAGENT_FALLBACK=deny` (default): no silent fallback.
+  - `INTAKE_SUBAGENT_FALLBACK=allow`: explicit operator opt-in for fallback path.
+
+Single-writer drift safety:
+- Intake run binds a deterministic writer/run identity (`writer_id`,
+  `intake_run_id`) to target artifacts.
+- Self-write updates for the active writer/run are valid and must not trigger
+  concurrent drift blockers.
+- External concurrent conflicting writes fail safe with
+  `INTAKE_CONCURRENT_WRITER_DETECTED`.
+- Fail-safe path performs no partial overwrite.
+
 ## Project run steps
 
 ### Prerequisites