its-magic 0.1.2-43 → 0.1.2-48

package/template/.github/workflows/ci.yml

@@ -79,12 +79,15 @@ jobs:
 
       - name: No commands set
         if: ${{ steps.runbook.outputs.TEST_COMMAND == '' && steps.runbook.outputs.LINT_COMMAND == '' && steps.runbook.outputs.TYPECHECK_COMMAND == '' }}
-        run: echo "No runbook commands set."
+        run: echo "no tests configured yet"
 
       - name: Summarise results
         if: always()
         run: |
           echo "### CI Results" >> "$GITHUB_STEP_SUMMARY"
+          if [ "${{ steps.runbook.outputs.TEST_COMMAND }}" = "" ] && [ "${{ steps.runbook.outputs.LINT_COMMAND }}" = "" ] && [ "${{ steps.runbook.outputs.TYPECHECK_COMMAND }}" = "" ]; then
+            echo "**no tests configured yet**" >> "$GITHUB_STEP_SUMMARY"
+          fi
           echo "| Step | Result |" >> "$GITHUB_STEP_SUMMARY"
           echo "|------|--------|" >> "$GITHUB_STEP_SUMMARY"
           echo "| Test | ${{ steps.test.outcome || 'skipped' }} |" >> "$GITHUB_STEP_SUMMARY"
@@ -189,116 +192,3 @@ jobs:
           echo "  2. Run:  bash scripts/validate-and-push.sh"
           echo "     (or:  powershell scripts/validate-and-push.ps1)"
           echo "  3. Fix failures, the script loops until green, then pushes."
-
-  # ── npm package test (Ubuntu) ──────────────────────────────────────
-  npm-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-      - name: npm pack
-        run: |
-          npm pack
-          TGZ=$(ls -t its-magic-*.tgz 2>/dev/null | head -1)
-          echo "TGZ=$TGZ" >> "$GITHUB_ENV"
-          echo "Package created: $TGZ"
-      - name: Install globally from tarball
-        run: npm install -g "$TGZ"
-      - name: Smoke test - help
-        run: its-magic --help
-      - name: Smoke test - install into temp dir
-        run: |
-          TEST_DIR=$(mktemp -d)
-          its-magic --target "$TEST_DIR" --mode missing --create
-          FAIL=0
-          for f in \
-            ".cursor/commands/intake.md" \
-            ".cursor/rules/core.mdc" \
-            ".cursor/hooks.json" \
-            ".cursor/scratchpad.md" \
-            "docs/engineering/runbook.md"; do
-            if [ -f "$TEST_DIR/$f" ]; then
-              echo "PASS: $f"
-            else
-              echo "FAIL: $f"
-              FAIL=1
-            fi
-          done
-          rm -rf "$TEST_DIR"
-          exit $FAIL
-      - name: Cleanup
-        if: always()
-        run: npm uninstall -g its-magic || true
-
-  # ── Homebrew formula test (macOS) ──────────────────────────────────
-  brew-test:
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Validate formula syntax
-        run: brew style packaging/homebrew/its-magic.rb || true
-      - name: Test installer.sh
-        run: |
-          TEST_DIR=$(mktemp -d)
-          sh installer.sh --target "$TEST_DIR" --mode missing --create
-          FAIL=0
-          for f in \
-            ".cursor/commands/intake.md" \
-            ".cursor/rules/core.mdc" \
-            ".cursor/hooks.json" \
-            ".cursor/scratchpad.md" \
-            "docs/engineering/runbook.md"; do
-            if [ -f "$TEST_DIR/$f" ]; then
-              echo "PASS: $f"
-            else
-              echo "FAIL: $f"
-              FAIL=1
-            fi
-          done
-          rm -rf "$TEST_DIR"
-          exit $FAIL
-
-  # ── Chocolatey package test (Windows) ──────────────────────────────
-  choco-test:
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Validate choco pack
-        shell: powershell
-        run: |
-          Push-Location packaging/chocolatey
-          choco pack
-          $nupkg = Get-ChildItem -Filter "*.nupkg" | Select-Object -First 1
-          if ($nupkg) {
-            Write-Host "PASS: Package created - $($nupkg.Name)"
-          } else {
-            Write-Host "FAIL: No .nupkg created"
-            exit 1
-          }
-          Pop-Location
-      - name: Test installer.ps1
-        shell: powershell
-        run: |
-          $testDir = Join-Path $env:TEMP "its-magic-ci-test"
-          & .\installer.ps1 -Target $testDir -Mode missing -Create
-          $fail = 0
-          $files = @(
-            ".cursor\commands\intake.md",
-            ".cursor\rules\core.mdc",
-            ".cursor\hooks.json",
-            ".cursor\scratchpad.md",
-            "docs\engineering\runbook.md"
-          )
-          foreach ($f in $files) {
-            $fp = Join-Path $testDir $f
-            if (Test-Path $fp) {
-              Write-Host "PASS: $f"
-            } else {
-              Write-Host "FAIL: $f"
-              $fail = 1
-            }
-          }
-          Remove-Item -Recurse -Force $testDir
-          exit $fail

package/template/README.md

@@ -24,6 +24,28 @@ with pause/resume, decision gates, and persistent artifacts.
 - Built-in benchmarks (live, prompted, headless).
 - Multiplatform distribution (npm, Chocolatey, Homebrew).
 
+<!-- readme-feature-coverage-catalog -->
+
+### Feature coverage catalog (US-0091)
+
+- `/bin` — POSIX npm installer + Linux remote test targets (WSL / SSH / Docker) (`US-0084`).
+- `/choco` — Configurable Multi-Target Release Publish with Confirmation Gate (`US-0054`).
+- `/devops` — First-Class Bug Issue Workflow (Open/Closed) (`US-0079`).
+- `/engineering` — Agent-Driven Codebase Map Bootstrap (`US-0082`).
+- `/engineering` — Remote Runtime Connectivity Contract for QA/Release/Publish (`US-0064`).
+- `/install` — Template/install payload omits intake gate scripts (`BUG-0001`).
+- `/intake` — Optional Caveman-style input compression (safe file scope) (`US-0090`).
+- `/lint` — CI/CD Workflows (`US-0007`).
+- `/or` — Cursor Caveman mode (scratchpad-configurable terse responses) (`US-0089`).
+- `/push` — Multiplatform Distribution (`US-0009`).
+- `/run-tests` — Baseline Regression Cleanup for Installer and Version Sync Checks (`US-0074`).
+- `/template` — End-to-End Lifecycle QA for `its-magic` Install/Upgrade/Clean (`US-0041`).
+- `/upgrade` — Missing scripts still occur on install modes missing/upgrade (`BUG-0003`).
+- `/usr` — Global Linux install fails: empty `install_include_paths` when manifest is CRLF (`BUG-0008`).
+- `/workdir` — installer.sh fails in shell path with `set: Illegal option -` (`BUG-0004`).
+- `MIGRATION` scratchpad flag — Smart Upgrade Mode (`US-0018`).
+- `US-0016` scratchpad flag — Homebrew Version Sync (`US-0016`).
+
 ## Setup
 
 its-magic is an installer you run once per repo. It copies the AI dev team
@@ -1105,6 +1127,68 @@ push / PR  ──>  checks  ──>  PASS  ──>  done
 Auto-fix commits appear as `ci: auto-fix attempt N/3`. After 3 retries the
 workflow stops and points you to `scripts/validate-and-push` for local fixing.
 
+<!-- readme-feature-coverage-catalog -->
+
+### Feature coverage catalog (US-0091)
+
+- `/acceptance` — Mandatory Intake Question Packs for First and Small Intakes (`US-0068`).
+- `/ask` — /ask Command: Context-Aware Questions Without Workflow (`US-0020`).
+- `/ask` — Context Compaction and Tiered Token-Cost Optimization Mode (`US-0053`).
+- `/auto` — Configurable Auto Phase Selection Policy (`US-0070`).
+- `/auto` — Continuous `/auto` Backlog-Drain Mode with Fine-Tune Switches (`US-0044`).
+- `/auto` — Fresh Subagent Context Per Phase and /auto Orchestration (`US-0023`).
+- `/auto` — Mid-Process `/auto` Continuation with Deterministic Resume Point (`US-0037`).
+- `/auto` — Strict Phase Role Enforcement in /auto Orchestration (`US-0069`).
+- `/auto` — Strict Runtime Proof for Per-Phase Subagent Isolation (`US-0056`).
+- `/auto` — Token-Cost Hardening for Orchestrated Runs (`US-0080`).
+- `/auto` — `/auto` continuous multi-phase loop + quiet drain (close one-phase-stop gap) (`US-0088`).
+- `/auto` — `/auto` executes phases without spawning required subagents (`BUG-0006`).
+- `/auto` — `/auto` explicit bug targeting (fix all OPEN bugs / fix `BUG-####`) (`US-0087`).
+- `/auto` — `/auto` fails with stale resume target after bug intake (`BUG-0005`).
+- `/check` — Optional Documentation Pack (Design Concept, CRS, Technical Spec) (`US-0031`).
+- `/confirmation` — Enforced Interactive Intake Question Evidence (`US-0078`).
+- `/connectivity` — Release Operator Run/Connect/Verify Hints Contract (`US-0067`).
+- `/decision` — Optional Fresh-Project ID Namespace Bootstrap (`US-0052`).
+- `/derived` — Deterministic Status Reconciliation Command (`US-0055`).
+- `/developer-dense` — Documentation Audience Profiles and Dual README Strategy (`US-0077`).
+- `/docs` — Installer-Owned `its_magic/` Folder for Framework Metadata (`US-0062`).
+- `/engineering` — Deterministic Context Slimming and Archive Enforcement Across Core Artifacts (`US-0072`).
+- `/engineering` — Deterministic State Hot-Surface Rollover and Archive Enforcement (`US-0060`).
+- `/engineering` — OS-Aware Runbook Command Auto-Bootstrap with Verified Quality Gates (`US-0063`).
+- `/flag` — Release Gate for Command/Flag Documentation Delta (`US-0030`).
+- `/intake` — Critical Evaluation in Intake and Architecture (`US-0021`).
+- `/intake` — Deterministic Intake Runtime Capability Guard and Single-Writer Drift Safety (`US-0059`).
+- `/intake` — Multi-Repo and Contract Compatibility Observability (`US-0034`).
+- `/intake` — intake evidence records asked questions that were never asked (`BUG-0007`).
+- `/integration` — Generated Test Scaffolding and Auto-Run Contract (`US-0066`).
+- `/managed` — Runtime QA Autopilot for Generated Projects (`US-0065`).
+- `/new` — First-Intake Full-Plan Coverage and Story-Map Gate (`US-0081`).
+- `/order` — Deterministic Artifact Ordering and Write Discipline (`US-0058`).
+- `/phases` — Cross-Phase Artifact Ownership Guard and Deterministic Archive Control (`US-0061`).
+- `/planning` — User-Visible Internal Metadata Sanitization Guard (`US-0071`).
+- `/product` — Backlog Reconciliation Gate for Released Sprints (`US-0043`).
+- `/push` — Phase-Triggered Sync Policy with Guarded Auto-Push (`US-0038`).
+- `/release` — Enforced Per-Phase Subagent Isolation with Audit Gate (`US-0048`).
+- `/release` — Legacy DONE-Story Acceptance/Traceability Backfill Guard (`US-0049`).
+- `/release` — Per-Sprint Release Notes and Release Queue Tracker (`US-0040`).
+- `/release` — Release Findings Artifact and Post-QA Issue Workflow (`US-0042`).
+- `/release` — Release Gate Tightening for Check-In Tests and QA/UAT Completion (`US-0039`).
+- `/remote` — Automation-driven remote execution selection (Docker / SSH / NL container intent) (`US-0086`).
+- `/remote` — Gitignored `.env` for remote and release connectivity (no AI read) (`US-0085`).
+- `/repetitive` — Delegable Intake Clarification Without Hard Blocks (`US-0083`).
+- `/research` — Knowledge Curation & Early Research (`US-0029`).
+- `/risk` — Intelligent Intake Decomposition and Risk-Aware PO Questioning (`US-0051`).
+- `/scratchpad` — Executable Scratchpad-Driven Sync and Auto-Push Wiring (`US-0076`).
+- `/scratchpad` — Scratchpad Delivery Simplification (Example-Only Install Policy) (`US-0073`).
+- `/scratchpad` — Upgrade Scratchpad Example–First Refresh (Fix Example Drift vs Materialized Baseline) (`US-0075`).
+- `/scratchpad` — Upgrade-Safe Scratchpad Example Refresh and Parity (`US-0057`).
+- `/sprint-plan` — Explicit `/sprint-plan --bulk` Mode (`US-0046`).
+- `/sprint-plan` — Sprint Sizing Rules and Configurable Sprint Planning (`US-0022`).
+- `/story` — Optional Feature User Guide Generation (`US-0032`).
+- `/uat` — UAT Artifact Lifecycle and Ownership (`US-0027`).
+- `SKILL` scratchpad flag — Skill and Templates (`US-0004`).
+- `US-0001` scratchpad flag — Core Workflow Commands (`US-0001`).
+
 ## Walkthrough examples
 
 ### Example 1: New feature from idea
@@ -1240,6 +1324,35 @@ Reliable pattern:
 - `decisions/`: decision records.
 - `.github/workflows/`: CI/CD templates.
 
+<!-- readme-feature-coverage-catalog -->
+
+### Feature coverage catalog (US-0091)
+
+- `/evidence` — Backlog-to-Sprint Traceability Contract (`US-0025`).
+- `/exit` — Milestone Lifecycle Definition and Exit Criteria (`US-0026`).
+- `/field` — Official Remote Config Template, Docs, and Fail-Fast Validation (`US-0036`).
+- `/installer` — Runbook Completion (`US-0015`).
+- `/intake` — Component-Scoped Execution Mode with Protection Guards (`US-0035`).
+- `/intake` — Configurable Guided Intake Behavior (`US-0033`).
+- `/map-codebase` — map-codebase does not write codebase-map in fresh repos (`BUG-0002`).
+- `/memory-audit` — Memory Drift Audit Command (`US-0024`).
+- `/product` — Canonical Story Status Source + Global Drift Guard (`US-0045`).
+- `/product` — Clean Install Hygiene and Complete Clean-Repo Coverage (`US-0050`).
+- `/security-review` — Security & Compliance Review Agent (`US-0028`).
+- `/skip` — Explicit Bulk Execute Orchestration Mode (`US-0047`).
+- `/strings` — Clean Placeholder Content from Templates and Active Files (`US-0019`).
+- `/write` — Artifact Templates and Starter Docs (`US-0006`).
+- `AUTO_FLOW_MODE` scratchpad flag — Automation Modes (`US-0011`).
+- `README` scratchpad flag — Voice Input Documentation (`US-0010`).
+- `TEAM_MODE` scratchpad flag — Team Mode (`US-0013`).
+- `US-0002` scratchpad flag — AI Behavior Rules (`US-0002`).
+- `US-0003` scratchpad flag — Subagent Definitions (`US-0003`).
+- `US-0005` scratchpad flag — Hook System (`US-0005`).
+- `US-0008` scratchpad flag — CLI Installer (`US-0008`).
+- `US-0012` scratchpad flag — Benchmark Suite (`US-0012`).
+- `US-0014` scratchpad flag — Quality Chain (3-Layer) (`US-0014`).
+- `US-0017` scratchpad flag — Template Drift Guard (`US-0017`).
+
 ## Developer and release deep-dive
 
 ### CI/CD via runbook

package/template/docs/engineering/auto-orchestration-reference.md

@@ -772,12 +772,55 @@ script or manual re-invocation with `start-from` / refreshed `resume_brief`) is
 `stop_reason` vocabulary: `completed`, `decision_gate`, `missing_input`,
 `pause_request`, `loop_max`, `error`, `blocked`.
 
+### Full-autonomy stop matrix (US-0092)
+
+**`AUTO_FLOW_MODE=full_autonomy`** enables **`scripts/auto_outer_driver.py`**
+(spawn-only outer driver). **TOKEN_PROFILE controls context breadth / token cost only**
+— never automation level, drain, or outer-driver invocation.
+
+| Condition | US-0088 | `full_autonomy` delta | Operator notify |
+|-----------|---------|------------------------|-----------------|
+| Next phase, no hard stop | Continue inner `/auto` | Outer driver **re-invokes** when Cursor ends turn early | Quiet OK when `AUTO_QUIET=1` |
+| `decision_gate` | Hard stop | **No change — hard** | Always |
+| Unrecoverable `error` | Hard stop | **No change — hard** | Always |
+| Critical `missing_input` | Hard stop | **No change — hard** | Always |
+| Transient `missing_input` (recoverable) | Hard stop | **Relaxable** — bounded block-retry | Notify on cap |
+| `pause_request` | Hard stop | **No change — hard** | Always |
+| `loop_max` | Hard stop | **No change — hard** | Always |
+| `blocked` — transient/sync | Hard stop | **Relaxable** when recoverable | Notify on cap |
+| `blocked` — isolation/strict-proof/ownership | Hard stop | **No change — hard** | Always |
+| UAT/QA fail | Hard stop (operator) | **Relaxable** when `AUTO_IMPLEMENTATION_LOOP=1` | Notify on cap |
+| Segment complete + `AUTO_BACKLOG_DRAIN=1` | Advance (may need manual re-`/auto`) | **Drain-advance-without-pause** — immediate next item | Segment handoff notify |
+| `BACKLOG_MAX_STORIES_REACHED` | Hard stop | **No change — hard** | Always |
+| `AUTO_SCHEDULER_CONFLICT` | Hard stop | **No change — hard** | Always |
+| `RELEASE_PUBLISH_MODE=auto` | Explicit opt-in | **No change — hard default-off** | Always on publish |
+| Security deny (`.env`, intake mutation) | Hard deny | **No change — hard** | Always |
+
+**Drain-advance-without-pause**: outer driver schedules next OPEN story/bug immediately;
+paired **`resume_brief`** + **`state.md`** refresh per **DEC-0069** at every boundary.
+
+### Block-retry ledger + cap interaction (US-0092)
+
+Append-only **`handoffs/auto_block_retry/<orchestrator_run_id>.jsonl`** — names-only;
+no secrets. Cap interaction:
+
+| Cap | Scope |
+|-----|-------|
+| `AUTO_LOOP_MAX_CYCLES` | Outer-driver `/auto` invocations (incl. drain advances) |
+| `AUTO_IMPLEMENTATION_LOOP` | Inner `execute`↔`qa`↔`verify-work` when `1` |
+| `AUTO_BLOCK_RETRY_MAX` | Per `(story_id, stop_reason)` recoverable retries |
+| `AUTO_BACKLOG_MAX_STORIES` | Drain breadth — outer driver exit **4** |
+
+Cap exhaustion → exit **6** `BLOCK_RETRY_CAP_EXHAUSTED`. Ordering: outer driver checks
+`AUTO_LOOP_MAX_CYCLES` first; orchestrator checks `AUTO_IMPLEMENTATION_LOOP` +
+`AUTO_BLOCK_RETRY_MAX` before scheduling remediation.
+
 ### `AUTO_QUIET` vs `TOKEN_PROFILE` (US-0088 / AC-2)
 
 | Key | Values | Role |
 |-----|--------|------|
 | `AUTO_QUIET` | `0` \| `1` (default `0`) | `1` = suppress routine per-phase success chatter; must **not** suppress `decision_gate`, errors, pause, `loop_max`, `blocked`, or missing inputs. |
-| `TOKEN_PROFILE` | `lean` \| `balanced` \| `full` | Unchanged — **DEC-0035** / **US-0080**; **orthogonal** to `AUTO_QUIET`. |
+| `TOKEN_PROFILE` | `lean` \| `balanced` \| `full` | **TOKEN_PROFILE controls context breadth / token cost only** — **DEC-0035** / **US-0080** / **US-0092**; **orthogonal** to `AUTO_QUIET`, drain, and outer-driver invocation. |
 
 ### `TOKEN_PROFILE` × `CAVEMAN_MODE` non-substitution (US-0089 / DEC-0072 §1)
 

package/template/docs/engineering/context/installer-owned-paths.manifest

@@ -32,6 +32,12 @@ scripts/remote_config_summary.py
 scripts/guard_installer_publish.py
 scripts/enforce-triad-hot-surface.py
 scripts/caveman_compress_input.py
+scripts/readme_feature_coverage_lib.py
+scripts/validate_readme_feature_coverage.py
+scripts/check_downstream_ci_guard.py
+scripts/downstream_ci_guard_lib.py
+scripts/auto_outer_driver.py
+scripts/uat_probe_lib.py
 .github/workflows
 README.md
 its_magic
@@ -59,6 +65,12 @@ scripts/remote_config_summary.py
 scripts/guard_installer_publish.py
 scripts/enforce-triad-hot-surface.py
 scripts/caveman_compress_input.py
+scripts/readme_feature_coverage_lib.py
+scripts/validate_readme_feature_coverage.py
+scripts/check_downstream_ci_guard.py
+scripts/downstream_ci_guard_lib.py
+scripts/auto_outer_driver.py
+scripts/uat_probe_lib.py
 .github/workflows/ci.yml
 .github/workflows/deploy.yml
 its_magic

package/template/docs/engineering/context/readme-section-affinity.json

@@ -0,0 +1,30 @@
+{
+  "affinity_version": 1,
+  "rules": [
+    {
+      "dev_h2": "Workflow",
+      "root_h2": "Commands and workflow",
+      "tag": "slash_command"
+    },
+    {
+      "dev_h2": "Quality gates",
+      "root_h2": "Other useful capabilities",
+      "tag": "scratchpad_mode"
+    },
+    {
+      "dev_h2": "Architecture notes",
+      "root_h2": "Features",
+      "tag": "distribution"
+    },
+    {
+      "dev_h2": "Quality gates",
+      "root_h2": "Commands and workflow",
+      "tag": "release_gate"
+    },
+    {
+      "dev_h2": "Engineering decisions",
+      "root_h2": "Other useful capabilities",
+      "tag": "governance"
+    }
+  ]
+}

package/template/docs/engineering/runbook.md

@@ -125,6 +125,48 @@ after template upgrades if needed.
 
 Normative H2 titles and matrix: `docs/engineering/architecture.md` (`# US-0077`).
 
+## README feature coverage validation (US-0091 / DEC-0074)
+
+**Goal:** ensure every DONE user-visible backlog item (`US-xxxx` / `BUG-xxxx` with
+`user_visible: true`) has operator blurbs in root `README.md` and traceability rows in
+`docs/developer/README.md`, without inventing new `USER_*` / `DEV_*` H2 literals
+(**DEC-0059** composes; **US-0030** delta gate unchanged).
+
+### Delta vs static doc gates
+
+| Gate | Question | Remediation |
+|------|----------|-------------|
+| **US-0030** (delta) | Did this sprint change commands/flags without README/runbook updates? | Update command docs for changed surfaces; agent checklist in `/release` step 3 family. |
+| **US-0091** (static) | Is every DONE user-visible item documented in the README family? | Backfill root + DEV shard; set `user_visible:` marker; run validator `--report`. |
+
+### Scratchpad key
+
+- `README_FEATURE_COVERAGE_ENFORCE`: `0` \| `1` (default `0` until backfill completes).
+- When `0`: `/release` step **3f** records `skipped` evidence; migration heuristic H1–H8
+  may classify unset `user_visible` during backfill.
+- When `1`: explicit `user_visible:` required on all DONE items; heuristic disabled;
+  `/release` runs blocking validator.
+
+**Activation (same commit as backfill):** complete audit + three-file backfill → explicit
+`user_visible:` markers → verify `--report` shows `coverage_missing: []` → flip `0` → `1`.
+
+### Commands
+
+```bash
+python scripts/validate_readme_feature_coverage.py --self-test
+python scripts/validate_readme_feature_coverage.py --repo . --report
+python scripts/validate_readme_feature_coverage.py --repo . --audit-out docs/engineering/context/readme-feature-coverage-audit.json
+python scripts/validate_readme_feature_coverage.py --repo . --enforce
+python scripts/check_intake_template_parity.py --scope=readme-feature-coverage
+```
+
+Reason codes: `README_FEATURE_COVERAGE_BLOCKED`, `README_FEATURE_COVERAGE_GAP:<id>`,
+`README_FEATURE_COVERAGE_PARITY_FAIL`, `README_FEATURE_COVERAGE_INPUT_INVALID`,
+`README_FEATURE_COVERAGE_PROFILE_VIOLATION`.
+
+Normative predicate + affinity manifest: `decisions/DEC-0074.md`,
+`docs/engineering/context/readme-section-affinity.json`.
+
 ## User-visible internal metadata guard (US-0071 / DEC-0053)
 
 **Goal:** keep planning-shaped identifiers out of **operator-visible software
@@ -380,11 +422,10 @@ Tiered token-cost control is explicit and defaulted in `.cursor/scratchpad.md`:
 
 Deterministic profile semantics:
 
-- `lean`: reduce non-critical overhead defaults (for example aggressive research,
-  autonomous loops, broad-context retrieval), while preserving mandatory
+- `lean`: lowest context breadth / token cost defaults while preserving mandatory
   quality/release gates.
-- `balanced`: preserve current capability profile with moderate overhead.
-- `full`: maximize context breadth and autonomy for complex/high-uncertainty work.
+- `balanced`: moderate context breadth / token cost.
+- `full`: highest context breadth / token cost for complex/high-uncertainty work.
 
 Manual override precedence:
 
@@ -399,7 +440,8 @@ Manual override precedence:
   reasoning as phase input.
 - **`start-from`**: use **`/auto start-from=<canonical_phase_id>`** when resuming so the
   schedule intersection matches materialized **`resolved_phase_plan`** (**`DEC-0052`**).
-- **`TOKEN_PROFILE`**: `lean` lowers default automation breadth; does **not** remove
+- **`TOKEN_PROFILE`**: **TOKEN_PROFILE controls context breadth / token cost only**;
+  does **not** change automation level, drain, outer-driver invocation, or remove
   isolation, strict-proof, role, or release gates.
 - **Metrics**: append-only **`handoffs/token_cost_runs/<orchestrator_run_id>.md`** (or
   **`.jsonl`**); copy path into **`token_cost_evidence_ref`** on **`state.md`** checkpoints.
@@ -458,8 +500,15 @@ Rollover fail-safe reason codes:
 - `STATE_ARCHIVE_VERIFICATION_FAILED`
 - `STATE_ARCHIVE_REQUIRED`
 - `ARTIFACT_HOT_SURFACE_OVERSIZE`
+- `ARCH_STORY_HEADING_LEVEL_INVALID`
 - `CONTEXT_BUDGET_EXCEEDED`
 
+**Architecture file blocked on rollover?** If story sections use legacy H2 `## US-xxxx`
+headings, the archiver now recognizes them for rollover after **BUG-0010**. For new work,
+`/architecture` must append H1 `# US-xxxx` (or `# BUG-xxxx` for defects). To converge an
+existing repo, optionally normalize `## US-xxxx` → `# US-xxxx` manually (count decrease is
+allowed; adding new `## US-` story headings is blocked).
+
 ### Minimal-read defaults by phase (bounded escalation)
 
 Read `docs/engineering/phase-context.md` first, then the **required** paths for
@@ -1317,6 +1366,46 @@ success chatter. Non-suppressible notifications:
 `AUTO_QUIET` is **orthogonal** to `TOKEN_PROFILE` (**DEC-0035** / **US-0080**):
 `TOKEN_PROFILE` controls context breadth and token cost, not notification policy.
 
+### Full-autonomy outer driver (US-0092)
+
+Opt-in **`AUTO_FLOW_MODE=full_autonomy`** (exact literal, default-off) enables the
+shipped stdlib outer driver. Spawn-only preserved — the driver loops hook
+invocations; it never performs phase-role work.
+
+#### Enable and run (once per portfolio segment)
+
+1. Set in merged scratchpad (`.cursor/scratchpad.md` + optional local overrides):
+   - `AUTO_FLOW_MODE=full_autonomy`
+   - Optional: `AUTO_BACKLOG_DRAIN=1`, `AUTO_BUG_QUEUE=1` (scheduler mutex per US-0087)
+   - Caps: `AUTO_LOOP_MAX_CYCLES`, `AUTO_BACKLOG_MAX_STORIES`, `AUTO_BLOCK_RETRY_MAX` (default `3`)
+   - Optional: `AUTO_OUTER_DRIVER_TIMEOUT_SECONDS` (unset = no timeout)
+2. Run once: `python scripts/auto_outer_driver.py --repo .`
+3. Interpret exit code (driver prints reason tokens on stderr):
+
+| Exit | Meaning |
+|------|---------|
+| **0** | `completed` — segment/portfolio terminal per policy |
+| **1** | Hard stop — `decision_gate`, unrecoverable `error`, isolation/strict-proof, security deny |
+| **2** | Configuration — `AUTO_FLOW_MODE` not `full_autonomy` (`AUTO_FLOW_MODE_NOT_FULL_AUTONOMY`) |
+| **3** | `loop_max` — `AUTO_LOOP_MAX_CYCLES` exhausted |
+| **4** | `BACKLOG_MAX_STORIES_REACHED` / drain cap |
+| **5** | `pause_request` / `AUTO_PAUSE_REQUEST` |
+| **6** | `BLOCK_RETRY_CAP_EXHAUSTED` |
+| **124** | Hook/subprocess timeout |
+
+`--dry-run` emits planned `/auto` hook invocations and drain-advance scheduling
+without side effects. `--invoke-cmd` overrides the default normative `/auto …` line.
+
+#### Security (US-0092 / DEC-0078)
+
+- **No** auto-read **`.env`** or secret paths.
+- **No** intake evidence mutation under automation.
+- **No** publish without **`RELEASE_PUBLISH_MODE=auto`** (explicit opt-in; default-off).
+- Block-retry ledger **`handoffs/auto_block_retry/<orchestrator_run_id>.jsonl`** is
+  names-only — no secrets, no file contents.
+
+UAT self-verify: **`scripts/uat_probe_lib.py`** shared by **`/verify-work`** and **`/qa`**.
+
 ### Caveman mode (US-0089)
 
 Optional response-side terse / imperative assistant voice. **Default off.**
@@ -1371,6 +1460,19 @@ vocabulary inherited from **US-0088** (`decision_gate`, `error`, `pause`,
 `[INTAKE_EVIDENCE_VALIDATION_OK]`, `[SCRATCHPAD_PAIR_OK]`) also renders
 byte-literal even at `CAVEMAN_LEVEL=ultra`.
 
+#### Voice compression levels
+
+Compact before/after examples (full contract: `.cursor/rules/caveman.mdc`):
+
+| Scenario | Level | Before | After |
+|----------|-------|--------|-------|
+| Technical explain | `full` | "The spawn-only orchestrator must dispatch a fresh subagent for each phase." | "Spawn-only orchestrator dispatches fresh subagent per phase. Next: run `/execute`." |
+| Destructive warning (auto-clarity break) | (pause) | "I will run `git push --force` to fix the remote." | "Destructive: `git push --force` rewrites remote history. Confirm branch and remote before proceeding." |
+
+Normative voice-compression contract (precedence, drop rules, persistence,
+9-zone deferral): **`.cursor/rules/caveman.mdc`** — `## Voice compression
+(when CAVEMAN_MODE=1)`.
+
 ### Caveman input compression (US-0090)
 
 Optional **input-side** file compression. **Default off.** Operator-initiated,
@@ -1518,6 +1620,17 @@ Notify operator on segment handoff (non-routine, non-suppressible).
 | `AUTO_SCHEDULER_CONFLICT` | Both `AUTO_BACKLOG_DRAIN=1` and `AUTO_BUG_QUEUE=1` without `bug-target=` argv | Supply explicit `bug-target=` or disable one scheduler |
 | `BACKLOG_MAX_STORIES_REACHED` | Drain cap hit | Increase `AUTO_BACKLOG_MAX_STORIES` or run another `/auto` |
 
+### Downstream CI packaging job leak (BUG-0009 / DEC-0075)
+
+**CI still runs its-magic packaging jobs?** Your project received a pre-fix workflow.
+Run **`its-magic --target <repo> --mode upgrade`** (or **`--mode clean`** then reinstall)
+to refresh `.github/workflows/ci.yml` from the corrected template. After upgrade, GitHub
+Actions should show only **`checks`** and **`auto-fix`** jobs — not `npm-test`,
+`brew-test`, or `choco-test`.
+
+Scope reminder: fix applies to **new installs/upgrades**; stale repos heal on next upgrade
+(**US-0018**).
+
 ## Explicit bulk sprint planning mode (US-0046)
 
 `/sprint-plan` stays single-scope by default. Bulk planning is opt-in via