orbital-command 0.2.0 → 1.0.0

package/templates/settings-hooks.json

@@ -76,7 +76,7 @@
         ]
       },
       {
-        "matcher": "Write",
+        "matcher": "Write|Edit",
         "hooks": [
           { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scope-create-cleanup.sh", "_orbital": true }
         ]

package/templates/skills/git-commit/SKILL.md

@@ -20,7 +20,8 @@ BRANCHING_MODE=$(grep '^WORKFLOW_BRANCHING_MODE=' .claude/config/workflow-manife
 ### Step 0b: Record Session ID
 
 1. Run: `bash .claude/hooks/get-session-id.sh`
-2. For each scope in `scopes/review/` with a passing verdict:
+2. For each scope in `scopes/review/` with a passing verdict
+   (if BATCH_SCOPE_IDS is set, only record on those specific scopes):
    - Append session UUID to `sessions.commit` in frontmatter
 
 ### Step 1: Check Branch
@@ -39,9 +40,11 @@ Find scopes in `scopes/review/` that have a passing verdict:
 
 1. List files in `scopes/review/*.md`
 2. For each, extract the scope number and check `.claude/review-verdicts/{NNN}.json`
+
+If BATCH_SCOPE_IDS is set, only process those specific scopes (skip any not in the list).
+
 3. If verdict exists and `verdict === "PASS"`:
-   - `mv scopes/review/{file} scopes/completed/`
-   - Update frontmatter: `status: completed`
+   - Transition: `bash .claude/hooks/scope-transition.sh --from review --to completed --scope {NNN}`
    - Update DASHBOARD: `📦 **Status**: Committed`
 4. If scope is in `scopes/review/` with **no** passing verdict:
    - Warn: "Scope {NNN} is in review but hasn't passed the review gate."
@@ -50,23 +53,40 @@ Find scopes in `scopes/review/` that have a passing verdict:
 
 ### Step 3: Commit
 
+**Determine which files to stage** — scope-aware, not a blanket `git add .`:
+
+1. For each scope being committed (from Step 2), read its **Files Summary** table from the scope document (`scopes/review/{NNN}*.md` or `scopes/completed/{NNN}*.md`)
+2. Also check `.claude/review-findings/{NNN}.json` — each finding has a `file` field listing reviewed files
+3. Cross-reference against `git status` — only stage files that appear in the scope's Files Summary or review findings
+4. If files exist in `git status` that don't belong to any scope being committed, leave them unstaged
+
 ```bash
-git add <specific code files — scopes are gitignored>
+git add <files from scope Files Summary + review findings>
 git commit -m "type(scope): description"
 ```
 
-- Stage only code files (scopes/ is gitignored, no need to worry about them)
+- Stage only scope-owned code files (scopes/ is gitignored, no need to worry about them)
+- If multiple scopes are being committed (batch), include files from ALL scopes in the batch
 - Follow conventional commit format
 - Do NOT push or create PRs — those are separate skills
 
-### Step 4: Signal Completion
+### Step 4: Signal Completion (REQUIRED)
 
-If working on a dispatched scope, emit the agent completion event:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"save"}' --scope "{NNN}"
+
+# On success — without a scope (general commit):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"save"}'
+
+# On failure (commit failed, no files to stage, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"save"}' --scope "{NNN}"
 ```
 
+The `--scope` flag is optional. Omit it when committing work that isn't tied to a specific scope.
+
 ## Quick Reference
 
 | User Says | Action |

package/templates/skills/git-dev/SKILL.md

@@ -19,7 +19,8 @@ Direct merge from feature branch into dev. The review gate already provides the
 ### Step 0: Record Session ID
 
 1. Run: `bash .claude/hooks/get-session-id.sh`
-2. For each scope in `scopes/completed/`:
+2. For each scope in `scopes/completed/`
+   (if BATCH_SCOPE_IDS is set, only record on those specific scopes):
    - Append session UUID to `sessions.prDev` in frontmatter
 
 ### Step 1: Verify Ready State
@@ -42,8 +43,7 @@ git status --porcelain
 
 Find scopes in `scopes/completed/`:
 1. For each scope file in `scopes/completed/*.md`:
-   - `mv scopes/completed/{file} scopes/dev/`
-   - Update frontmatter: `status: dev`
+   - Transition: `bash .claude/hooks/scope-transition.sh --from completed --to dev --scope {NNN}`
    - Update DASHBOARD: `🔀 **Status**: Merged to Dev`
 
 If BATCH_SCOPE_IDS is set, only transition those specific scopes.
@@ -68,10 +68,19 @@ git checkout "$FEATURE_BRANCH"
 
 If merge conflicts occur, resolve them before continuing.
 
-### Step 4: Signal Completion
+### Step 4: Signal Completion (REQUIRED)
+
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}' --scope "{NNN}"
+
+# On success — without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}'
+
+# On failure (merge conflicts, push rejected, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_dev"}' --scope "{NNN}"
 ```
 
 ## Output

package/templates/skills/git-main/SKILL.md

@@ -20,7 +20,8 @@ BRANCHING_MODE=$(grep '^WORKFLOW_BRANCHING_MODE=' .claude/config/workflow-manife
 ### Step 1: Record Session ID
 
 1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
-2. For each scope in `scopes/completed/`:
+2. For each scope in `scopes/completed/`
+   (if BATCH_SCOPE_IDS is set, only record on those specific scopes):
    - Append session UUID to `sessions.pushToMain` in frontmatter
 
 ### Step 2: Check Current Branch
@@ -63,10 +64,19 @@ For each completed scope being pushed:
 bash .claude/hooks/scope-transition.sh --from completed --to main --scope NNN
 ```
 
-### Step 5: Signal Completion
+### Step 5: Signal Completion (REQUIRED)
+
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}' --scope "NNN"
+# On success — with a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}' --scope "{NNN}"
+
+# On success — without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}'
+
+# On failure (push rejected, PR failed, merge conflicts, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_main"}' --scope "{NNN}"
 ```
 
 ## Batch Support

package/templates/skills/git-production/SKILL.md

@@ -96,12 +96,19 @@ gh pr merge --merge
 # Your CI/CD pipeline auto-deploys main to production (if configured)
 ```
 
-### Step 6: Signal Completion
+### Step 6: Signal Completion (REQUIRED)
 
-After the merge succeeds, emit the agent completion event if working on a dispatched scope:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}' --scope "{NNN}"
+
+# On success — without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}'
+
+# On failure (PR failed, merge conflicts, health check failed, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_production"}' --scope "{NNN}"
 ```
 
 ### Step 7: Verify Production

package/templates/skills/git-staging/SKILL.md

@@ -20,8 +20,7 @@ Creates a GitHub PR from dev to staging. Staging is a release candidate — the
 
 Find scopes in `scopes/dev/`:
 1. For each scope file in `scopes/dev/*.md`:
-   - `mv scopes/dev/{file} scopes/staging/`
-   - Update frontmatter: `status: staging`
+   - Transition: `bash .claude/hooks/scope-transition.sh --from dev --to staging --scope {NNN}`
    - Update DASHBOARD: `🚀 **Status**: Staging PR Created`
 
 If BATCH_SCOPE_IDS is set, only transition those specific scopes.
@@ -59,10 +58,19 @@ gh pr create --base staging --head dev \
 - [ ] Files under 400 lines"
 ```
 
-### Step 4: Signal Completion
+### Step 4: Signal Completion (REQUIRED)
+
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
+# On success — with a scope:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}' --scope "{NNN}"
+
+# On success — without a scope:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}'
+
+# On failure (PR creation failed, push rejected, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"pr_staging"}' --scope "{NNN}"
 ```
 
 ### Step 5: Monitor CI

package/templates/skills/scope-create/SKILL.md

@@ -46,10 +46,24 @@ Then run:
 bash .claude/hooks/scope-prepare.sh --new --title "Feature Name" --desc "Description" --category "Backend"
 ```
 
-The script outputs JSON: `{"id", "path", "title", "description", "session_id", "category", "mode"}`.
+The script outputs JSON: `{"id", "path", "title", "description", "session_id", "category", "effort", "mode", "available_categories", "effort_buckets"}`.
 The scope file is fully scaffolded with template, frontmatter, dashboard, and process log.
 
-### Step 2: Fill Specification
+### Step 2: Categorize and Estimate
+
+Read the JSON output from Step 1. Using the title, description, and any preserved idea body
+in the scope file, update the frontmatter:
+
+1. **Category**: Select the best match from `available_categories` in the JSON output.
+   Match semantically — "feature" for new capabilities, "bugfix" for fixes, "refactor" for
+   restructuring, "infrastructure" for tooling/CI/config, "docs" for documentation.
+   If the category is still "TBD", update it in the scope file's frontmatter.
+
+2. **Effort**: Estimate using the bucket system from `effort_buckets` in the JSON output
+   (typically: `<1H`, `1-4H`, or `4H+`). Consider the scope of changes implied by the
+   title and description. If effort is still "TBD", update it in the scope file's frontmatter.
+
+### Step 3: Fill Specification
 
 Edit the scope file to replace the placeholder in **SPECIFICATION > Overview** with the
 actual problem statement and goal. If coming from a plan, also populate:
@@ -57,7 +71,7 @@ actual problem statement and goal. If coming from a plan, also populate:
 - **Technical Approach** and rationale
 - **Implementation Phases** with files, changes, and verification steps
 
-### Step 3: Report
+### Step 4: Report
 
 ```
 Created: scopes/planning/NNN-feature-name.md

package/templates/skills/scope-fix-review/SKILL.md

@@ -12,8 +12,8 @@ Takes ALL findings from the Phase 3 code review (`/test-code-review`) and execut
 
 ## Prerequisites
 
-- Phase 3 (`/test-code-review`) must have been run in the current post-review pipeline
-- Code review findings must exist in the conversation context
+- Phase 3 (`/test-code-review`) must have been run — either in the current pipeline or in a prior session
+- Code review findings must be available (conversation context OR `.claude/review-findings/NNN.json` on disk)
 - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` must be enabled (a hook will block this skill otherwise)
 
 ## Steps
@@ -42,7 +42,10 @@ Takes ALL findings from the Phase 3 code review (`/test-code-review`) and execut
 
 ### Step 2: Collect and Organize Findings
 
-1. Gather ALL findings from the Phase 3 code review (from conversation context)
+1. **Load findings** — check both sources in order:
+   - **Disk first:** Read `.claude/review-findings/NNN.json` (where NNN is the scope ID). This file is written by `/test-code-review` Phase 4 and enables standalone `/scope-fix-review` without re-running Phase 3.
+   - **Conversation fallback:** If the file doesn't exist, gather findings from the Phase 3 code review conversation context.
+   - If neither source has findings, report "No findings to fix" and **EXIT**.
 2. Deduplicate findings across the 6 review agents
 3. Group findings by **file ownership domain**:
 
@@ -142,12 +145,16 @@ Agent(
 ╚═══════════════════════════════════════════════════════════════╝
 ```
 
-### Step 8: Emit Completion Event
+### Step 8: Signal Completion (REQUIRED)
+
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-bash .claude/hooks/orbital-emit.sh REVIEW_FIXES_COMPLETED \
-  '{"scope_id":"NNN","findings_total":YY,"findings_fixed":XX,"agents_used":N}' \
-  --scope "NNN"
+# On success:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"fix_review","findings_total":YY,"findings_fixed":XX}' --scope "{NNN}"
+
+# On failure (agents couldn't resolve, verification failed, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"fix_review","findings_total":YY,"findings_fixed":XX}' --scope "{NNN}"
 ```
 
 ## Important Rules

package/templates/skills/scope-implement/SKILL.md

@@ -26,7 +26,14 @@ user-invocable: true
 
 ### 2. Implement
 
-**Before starting Phase 1**: Update scope frontmatter to `status: implementing` and DASHBOARD to `🔄 **Status**: Implementing`. Move file: `mv scopes/backlog/{file} scopes/implementing/`.
+**Before starting Phase 1**: Read the scope's frontmatter `status` field. If the scope is not already in `implementing`, transition it and update the DASHBOARD to `🔄 **Status**: Implementing`:
+
+```bash
+# Use the scope's CURRENT status as the source (backlog, planning, review, completed, etc.)
+bash .claude/hooks/scope-transition.sh --from <current-status> --to implementing --scope {NNN}
+```
+
+If the scope is already `status: implementing` (resuming), skip the transition.
 
 For each phase:
 
@@ -89,12 +96,16 @@ After Step 3, the scope remains in `scopes/implementing/` with `status: implemen
 
 **Do NOT proceed to review in this session.** The review gate enforces session separation to ensure the implementing agent doesn't approve its own work.
 
-### 4. Signal Completion
+### 4. Signal Completion (REQUIRED)
 
-Emit the agent completion event so the Orbital Command dashboard turns off the progress indicator:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
-bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success"}' --scope "{NNN}"
+# On success:
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"implement"}' --scope "{NNN}"
+
+# On failure (build errors, blocked, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"implement"}' --scope "{NNN}"
 ```
 
 ## Resuming After Compaction

package/templates/skills/scope-post-review/SKILL.md

@@ -2,7 +2,7 @@
 name: scope-post-review
 description: Orchestrates post-implementation review — runs quality gates, formal verification, code review, and optional agent-team fix execution. Use when a scope is ready to move from implementing to review.
 user-invocable: true
-orchestrates: [test-checks, scope-verify, test-code-review, scope-fix-review]
+orchestrates: [test-scaffold, test-checks, scope-verify, test-code-review, scope-fix-review]
 ---
 
 # /scope-post-review NNN — Post-Implementation Review
@@ -16,6 +16,11 @@ Orchestrates the full post-implementation review pipeline for a scope. Runs up t
 │                     /scope-post-review NNN                      │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
+│  Phase 0: Test infrastructure check                            │
+│  └── If commands.test is null → /test-scaffold                 │
+│      Analyzes project, installs framework, writes tests.       │
+│      SKIPPED if tests already configured.                      │
+│                                                                 │
 │  Phase 1: /test-checks                                         │
 │  └── 13 machine-verifiable quality gates                       │
 │      Types, lint, build, templates, docs, enforcement, etc.    │
@@ -41,10 +46,52 @@ Orchestrates the full post-implementation review pipeline for a scope. Runs up t
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-**Rationale**: Quality gates run first to catch obvious issues cheaply. Spec verification runs second to confirm the implementation is actually complete before spending tokens on AI code review. Code review runs third on verified, passing code. Fix execution runs last, using an agent team to address all findings in parallel across non-overlapping file domains.
+**Rationale**: Test infrastructure is checked first so that gate #13 (tests) has something to run. Quality gates run next to catch obvious issues cheaply. Spec verification runs third to confirm the implementation is actually complete before spending tokens on AI code review. Code review runs fourth on verified, passing code. Fix execution runs last, using an agent team to address all findings in parallel across non-overlapping file domains.
 
 ## Steps
 
+### Phase 0: Test Infrastructure Check
+
+Ensure the project has a test suite before running quality gates. This runs in a subagent to keep the main post-review context clean — the scaffolding work (codebase analysis, package installs, writing test files) can be extensive and is not relevant to the review phases that follow.
+
+1. Read `.claude/orbital.config.json`
+2. Check `commands.test`:
+   - **If non-null** → tests are configured. Print:
+     ```
+     Phase 0: Tests configured (commands.test = "<value>") — skipping.
+     ```
+     **Skip** to Phase 1.
+   - **If null** → no test suite configured. Print:
+     ```
+     Phase 0: No test suite configured — scaffolding tests via subagent...
+     ```
+     Launch a subagent to scaffold the test suite:
+     ```
+     Agent(
+       description: "Scaffold test infrastructure",
+       prompt: "Run the /test-scaffold skill for this project. The project has no test suite configured (commands.test is null in .claude/orbital.config.json). Follow the skill instructions to: detect the project stack, choose a test framework, install it, write real tests, verify they pass, and update commands.test in .claude/orbital.config.json. Report what you did when finished.",
+       mode: "auto"
+     )
+     ```
+3. After the subagent completes:
+   - Re-read `.claude/orbital.config.json` and confirm `commands.test` is now non-null
+   - Run the configured test command to verify tests actually pass:
+     ```bash
+     <commands.test value>   # e.g., npm run test
+     ```
+   - **If `commands.test` is still null or tests fail:**
+     ```
+     ╔═══════════════════════════════════════════════════════════════╗
+     ║  Phase 0 FAILED — Test scaffolding did not produce passing   ║
+     ║  tests. Fix manually and re-run: /scope-post-review NNN     ║
+     ╚═══════════════════════════════════════════════════════════════╝
+     ```
+     Emit failure and **STOP** — do not proceed to Phase 1 with broken tests:
+     ```bash
+     bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":0}' --scope "{NNN}"
+     ```
+   - **If tests pass** → continue to Phase 1.
+
 ### Phase 1: Quality Gates (`/test-checks`)
 
 Run the 13 quality gates. This is the cheapest and fastest check.
@@ -58,7 +105,10 @@ Run the 13 quality gates. This is the cheapest and fastest check.
    ║  Fix the failing gates and re-run: /scope-post-review NNN    ║
    ╚═══════════════════════════════════════════════════════════════╝
    ```
-   **STOP** — do not proceed to Phase 2.
+   Emit failure and **STOP** — do not proceed to Phase 2:
+   ```bash
+   bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":1}' --scope "{NNN}"
+   ```
 3. If all gates PASS → continue to Phase 2.
 
 ### Phase 2: Formal Verification (`/scope-verify NNN`)
@@ -74,7 +124,10 @@ Run the scope-specific formal review gate.
    ║  Fix the issues and re-run: /scope-post-review NNN           ║
    ╚═══════════════════════════════════════════════════════════════╝
    ```
-   **STOP** — do not proceed to Phase 3.
+   Emit failure and **STOP** — do not proceed to Phase 3:
+   ```bash
+   bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":2}' --scope "{NNN}"
+   ```
 3. If verdict is PASS → continue to Phase 3.
 
 ### Phase 3: AI Code Review (`/test-code-review`)
@@ -83,8 +136,12 @@ Run the 6 parallel code review agents on the verified code.
 
 1. Invoke: `Skill(skill: "test-code-review")`
 2. Collect all findings — count BLOCKERS, WARNINGS, and SUGGESTIONS.
-3. If there are **any findings** (blockers, warnings, or suggestions), proceed to Phase 4.
-4. If there are **zero findings**, skip Phase 4 and go to Final Report.
+3. **Persist findings** — write all findings to `.claude/review-findings/NNN.json` so Phase 4 can read them even if run standalone in a separate session:
+   ```json
+   { "scopeId": NNN, "timestamp": "<ISO>", "blockers": [...], "warnings": [...], "suggestions": [...] }
+   ```
+4. If there are **any findings** (blockers, warnings, or suggestions), proceed to Phase 4.
+5. If there are **zero findings**, skip Phase 4 and go to Final Report.
 
 ### Phase 4: Fix Review Findings (`/scope-fix-review NNN`)
 
@@ -95,9 +152,17 @@ Execute all Phase 3 findings using a coordinated agent team. **This phase requir
    echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not set}"
    ```
 2. If **enabled** (`1`) and Phase 3 produced findings:
+   - If `.claude/review-findings/NNN.json` exists, load findings from there (enables standalone `/scope-fix-review` without re-running Phase 3)
    - Invoke: `Skill(skill: "scope-fix-review", args: "NNN")`
    - This spawns an agent team that fixes all findings in parallel across non-overlapping file domains
-   - Includes a verification step (typecheck + build) at the end
+   - After fixes complete, **re-run quality gates** to catch regressions:
+     ```
+     Skill(skill: "test-checks")
+     ```
+     If any gate fails, report which gates regressed, emit failure and **STOP**:
+     ```bash
+     bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"post_review","phase":4}' --scope "{NNN}"
+     ```
 3. If **not enabled**:
    - Read `~/.claude/settings.json`
    - Merge `"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }` into the existing JSON (preserve all other settings)
@@ -120,6 +185,11 @@ Execute all Phase 3 findings using a coordinated agent team. **This phase requir
 
 ### Final Report
 
+Emit the completion event so the dispatch resolves and the dashboard card stops showing the active animation:
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"post_review"}' --scope "{NNN}"
+```
+
 ```
 ╔═══════════════════════════════════════════════════════════════╗
 ║  /scope-post-review COMPLETE — Scope NNN                     ║

package/templates/skills/scope-pre-review/SKILL.md

@@ -188,17 +188,24 @@ J items are implementation notes (no spec change).
 ### Step 8: Update Scope Status
 
 After applying spec fixes and writing the AGENT REVIEW:
-- Update frontmatter: `status: backlog`, `spec_locked: true`
-- Move file: `mv scopes/planning/{file} scopes/backlog/`
+- Transition the scope (handles frontmatter + file move atomically):
+  ```bash
+  bash .claude/hooks/scope-transition.sh --from planning --to backlog --scope {NNN}
+  ```
+- Update frontmatter: `spec_locked: true` (scope-transition.sh handles status, this is the extra field)
 - Update DASHBOARD Quick Status: `🟢 **Status**: Backlog | **Spec Locked**: Yes`
 - Add to Recent Activity: `Review completed — N blockers, M warnings. X items applied to spec, K clarifications resolved.`
 
-### Step 9: Signal Completion
+### Step 9: Signal Completion (REQUIRED)
 
-Emit the agent completion event so the Orbital Command dashboard turns off the progress indicator:
+**Always emit when finished** — this is not optional. Emit success or failure so the dispatch resolves immediately:
 
 ```bash
+# On success:
 bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"team_review"}' --scope "{NNN}"
+
+# On failure (agent launch failed, unrecoverable error, etc.):
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"failure","action":"team_review"}' --scope "{NNN}"
 ```
 
 ## Modes

package/templates/skills/scope-verify/SKILL.md

@@ -146,9 +146,11 @@ Overall verdict is PASS only if ALL 4 criteria are PASS.
 ### Step 6: Scope Transition (on PASS only)
 
 If all criteria passed:
-1. Move scope file: `mv scopes/implementing/{file} scopes/review/` (or leave in place if already in `scopes/review/`)
-2. Update frontmatter: `status: review`
-3. Update DASHBOARD: `✅ **Status**: Reviewed | Ready to Commit`
+1. Transition the scope (handles frontmatter + file move atomically):
+   ```bash
+   bash .claude/hooks/scope-transition.sh --from implementing --to review --scope {NNN}
+   ```
+2. Update DASHBOARD: `✅ **Status**: Reviewed | Ready to Commit`
 
 ### Step 7: Report & Next Steps
 

package/templates/skills/test-code-review/SKILL.md

@@ -21,9 +21,9 @@ Combines all validation layers into one comprehensive check:
 │                            /test-code-review                                        │
 ├─────────────────────────────────────────────────────────────────────────┤
 │                                                                         │
-│  Phase 1: /test-checks (8 checks)                                              │
-│  ├── TypeScript, ESLint, Build, Templates                               │
-│  └── Doc links, Doc freshness, Enforcement, Workarounds                 │
+│  Phase 1: /test-checks (13 quality gates)                               │
+│  ├── TypeScript, Lint, Build, Templates, Docs, Enforcement              │
+│  └── Placeholders, Mock data, Shortcuts, Secrets, Stale scopes, Tests   │
 │                                                                         │
 │  Phase 2: pre-push (3 checks)                                                  │
 │  ├── Documentation sync                                                 │
@@ -50,26 +50,13 @@ Combines all validation layers into one comprehensive check:
 
 ### Phase 1: Pre-Commit Checks
 
-Run all 8 quality gates. Read commands from `.claude/orbital.config.json` — skip any that are null:
+Run all 13 quality gates via `/test-checks`:
 
-```bash
-echo "═══ PHASE 1: PRE-COMMIT ═══"
-# Run commands.typeCheck from orbital.config.json (skip if null)
-echo "[1/8] TypeScript..."
-# Run commands.lint from orbital.config.json (skip if null)
-echo "[2/8] Lint..."
-# Run commands.build from orbital.config.json (skip if null)
-echo "[3/8] Build..."
-# Run commands.validateTemplates from orbital.config.json (skip if null)
-echo "[4/8] Templates..."
-# Run commands.validateDocs from orbital.config.json (skip if null)
-echo "[5/8] Doc links..."
-# Run commands.docFreshness from orbital.config.json (skip if null)
-echo "[6/8] Doc freshness..."
-# Run commands.checkRules from orbital.config.json (skip if null)
-echo "[7/8] Enforcement..."
-echo "[8/8] Workarounds..." && echo "✅ Check staged files manually"
 ```
+Skill(skill: "test-checks")
+```
+
+This runs the full pipeline: typecheck, lint, build, templates, docs, enforcement, placeholders, mock data, shortcuts, secrets, stale scopes, and tests (13 gates total). See `/test-checks` for details.
 
 **Stop here if any check fails. Fix before proceeding.**
 
@@ -120,21 +107,44 @@ Prompt: "Review type design quality"
 
 ### Phase 4: Synthesize Results
 
-Collect all findings and report:
+Collect all findings, categorize by severity, and **persist to disk** so `/scope-fix-review` can load them in a standalone session.
+
+**4a. Categorize findings** from all 6 agents into BLOCKERS, WARNINGS, and SUGGESTIONS.
+
+**4b. Write findings to disk** — if running in a scope context (scope NNN is known from the pipeline), write:
+
+```bash
+mkdir -p .claude/review-findings
+```
+
+Write `.claude/review-findings/NNN.json`:
+```json
+{
+  "scopeId": NNN,
+  "timestamp": "<ISO timestamp>",
+  "blockers": [{ "agent": "...", "file": "...", "line": N, "message": "...", "fix": "..." }],
+  "warnings": [{ "agent": "...", "file": "...", "line": N, "message": "...", "fix": "..." }],
+  "suggestions": [{ "agent": "...", "file": "...", "line": N, "message": "...", "fix": "..." }]
+}
+```
+
+If no scope context is available (standalone `/test-code-review` outside post-review), skip the file write — findings remain in conversation context only.
+
+**4c. Display summary:**
 
 ```
 ╔═══════════════════════════════════════════════════════════════════════╗
-║                         /test-code-review RESULTS                                 ║
+║                       /test-code-review RESULTS                       ║
 ╠═══════════════════════════════════════════════════════════════════════╣
 ║                                                                       ║
-║  PHASE 1: Pre-Commit          [8/8 passed]  ✅                        ║
-║  PHASE 2: Pre-Push            [3/3 passed]  ✅                        ║
+║  PHASE 1: Pre-Commit          [13/13 passed] ✅                       ║
+║  PHASE 2: Pre-Push            [3/3 passed]   ✅                       ║
 ║  PHASE 3: Code Review         [findings below]                        ║
 ║                                                                       ║
 ║  ─────────────────────────────────────────────────────────────────    ║
-║  🚫 BLOCKERS (must fix):       0                                      ║
-║  ⚠️  WARNINGS (should fix):     2                                      ║
-║  💡 SUGGESTIONS (consider):    5                                      ║
+║  BLOCKERS (must fix):       0                                         ║
+║  WARNINGS (should fix):     2                                         ║
+║  SUGGESTIONS (consider):    5                                         ║
 ║                                                                       ║
 ╚═══════════════════════════════════════════════════════════════════════╝
 ```
@@ -199,13 +209,11 @@ If matching scope files are found and all tests passed:
 #### Step 4: Move Completed Scopes (If User Confirms)
 
 ```bash
-# Only after user confirmation (scopes are gitignored, use plain mv)
-mv scopes/XXX-scope-name.md scopes/completed/
-echo "✅ Moved scope XXX to completed folder"
+# Only after user confirmation — uses atomic transition (frontmatter + move)
+bash .claude/hooks/scope-transition.sh --from review --to completed --scope XXX
+echo "✅ Moved scope XXX to completed"
 ```
 
-**Note:** Scopes are gitignored — use plain `mv`, not `git mv`.
-
 ## Modes
 
 | Command | What Runs |