its-magic 0.1.2-24 → 0.1.2-25

package/README.md

@@ -318,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-24",
+  "version": "0.1.2-25",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

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

@@ -103,6 +103,10 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 #   - 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
@@ -110,6 +114,8 @@ 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,7 +94,7 @@ 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
@@ -96,6 +104,10 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 #   - 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
@@ -103,8 +115,10 @@ 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)
@@ -124,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)
@@ -134,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

@@ -318,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. |
@@ -22,6 +22,8 @@ anchors are missing or ambiguous.
 - 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
 
@@ -35,3 +37,10 @@ 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: