@dtlabs/ai-toolkit 0.1.4 → 0.1.6

package/.claude/agents/assessment-manager.md

@@ -1,16 +1,17 @@
 ---
 name: assessment-manager
-description: "Assessment Manager — intelligent orchestrator for the codebase assessment pipeline. Discovers available assessment agents, runs them in parallel, consolidates findings, gates on human approval, plans remediation, and dispatches developer agents to fix confirmed issues. Input: path to target codebase (or '.' for current directory) [--scope=<area1,area2>] [--force]"
+description: "Assessment Manager — intelligent orchestrator for the codebase assessment pipeline. Discovers available assessment agents, runs them in parallel, consolidates findings into intervention documents, gates on human approval, and reports effort/token estimates. Input: path to target codebase (or '.' for current directory) [--scope=<area1,area2>] [--force]"
 ---
 
 # Assessment Manager
 
-An intelligent orchestrator that **assesses before it plans, and plans before it executes**. Discovers available assessment agents, runs them against the target codebase, consolidates findings, gates on human approval, then drives remediation through existing developer agents.
+An intelligent orchestrator that **assesses before it plans, and plans before it executes**. Discovers available assessment agents, runs them against the target codebase, consolidates findings into structured intervention documents, gates on human approval, and produces effort and token estimates. Approved interventions are handed off to the feature delivery pipeline.
 
 Before starting, read these procedures from `docs/procedures/`:
 - `process-log.md` — log format and token tracking rules
 - `issues-register.md` — Issues Register format and severity rules
-- `assessment-approval-gate.md` — gate presentation, approvals file format, rules
+- `assessment-findings-gate.md` — gate presentation, approvals file format, rules
+- `token-estimation.md` — Token-Estimate.md format, estimation model, and assessment pipeline input size estimates
 
 Also read `docs/pricing.md` — model pricing table and blended cost formula (80/20 input/output split).
 
@@ -26,7 +27,7 @@ Scan `.claude/agents/` and read each file's `description` frontmatter. Classify
 - **Documentation** — produces structured documents (keywords: "documentation standard", "intervention")
 - **Orchestrator** — skip self-invocation
 
-Build two registries: `assessment_agents` and `remediation_agents`.
+Build an `assessment_agents` registry.
 
 ### 1b. Determine assessment prefix
 
@@ -59,15 +60,13 @@ Target codebase
                 └── intervention-documentation-standard
                           │
                           ├── {PREFIX}-INT-NNN-*.md (one per finding)
-                          └── {PREFIX}-Interventions-Index.md
+                          ├── {PREFIX}-Interventions-Index.md
+                          ├── {PREFIX}-Effort-Estimate.md (finalised)
+                          └── {PREFIX}-Token-Estimate.md (updated)
                                     │
                           ══ REMEDIATION GATE ══  →  {PREFIX}-Approvals.md
                                     │
-                          Remediation loop (approved interventions, parallel where possible)
-                                    │
-                          review-solution per intervention → commit on pass
-                                    │
-                          Pull Request  (feature/{PREFIX}-remediation → develop)
+                          Pipeline ends → Summary
 ```
 
 ### Planning rules
@@ -75,8 +74,6 @@ Target codebase
 1. All assessment agents run in **parallel** — read-only, no mutual dependencies
 2. `intervention-documentation-standard` runs **after** all assessments complete
 3. Skip agents with fresh output unless `--force`
-4. Remediation agents dispatch **only after** the Remediation Gate is approved
-5. Parallelize remediation agents where interventions have no dependency on each other
 
 ### Show plan to user before executing
 
@@ -89,9 +86,8 @@ Target codebase
    concurrency-safety-assessment    → ASSESS-001-Concurrency-Assessment.md
 
 ⏳ QUEUE: intervention-documentation-standard → ASSESS-001-INT-*.md + Interventions-Index.md
-⏳ GATE:  Remediation approval
-⏳ IMPL:  Approved interventions (parallel where no dependency)
-⏳ PR:    feature/ASSESS-001-remediation → develop
+⏳ WRITE: ASSESS-001-Effort-Estimate.md + ASSESS-001-Token-Estimate.md
+⏳ GATE:  Review findings → acknowledge + flag interventions
 ─────────────────────────────────────────────────────
 ```
 
@@ -105,6 +101,178 @@ After all complete:
 - Verify each expected output file exists and is non-empty
 - If an agent produced no output, log the failure and continue — partial assessments are better than none
 
+### Write initial Token Estimate file
+
+After verifying outputs and before moving to Phase 4, accumulate token usage from every completed assessment agent and write `{PREFIX}-Token-Estimate.md` to `docs/assessments/{PREFIX}/`. Create the directory if it does not exist.
+
+**Step 1 — Check estimation model (mandatory).** Confirm `docs/procedures/token-estimation.md` is present and readable. If it is missing, log an error and halt — token estimation is non-negotiable. Parse the file to extract the canonical parameters:
+
+| Parameter | Value |
+|-----------|-------|
+| Avg chars per token | 4 |
+| Haiku system prompt | ~2,000 tokens |
+| Sonnet system prompt | ~3,000 tokens |
+| Base overhead per call | ~5,000 tokens |
+
+Store these parameters in memory and reuse them for all estimation calculations in Phases 3–4. If the file is present but a parameter is missing, use the defaults above and log a warning: `"Using default token estimation parameter: {parameter}; consider updating docs/procedures/token-estimation.md"`.
+
+**Step 2 — Check pricing data (graceful).** Confirm `docs/pricing.md` is present and readable. If it is missing or malformed, log a warning: `"docs/pricing.md missing/malformed; cost columns will show N/A"` — then set all cost columns (est_cost, actual_cost) to `N/A` for all rows and continue. Token counts (estimated and actual) are still recorded with full precision. Phase subtotals and grand total cost rows show `N/A`. The pipeline does not halt. If the file is available, read the **Blended unit cost reference** table and look up the blended rate for each agent's model. Default to `sonnet` for any agent whose model cannot be determined from its frontmatter.
+
+**Step 3 — Estimate tokens per assessment agent.** For each agent that ran in Phase 3, apply the estimation formula from `docs/procedures/token-estimation.md` (Assessment pipeline usage section):
+
+```
+est_tokens = base_overhead + system_prompt_weight + (input_size_chars / 4)
+           = 5,000        + 3,000 (sonnet)        + (input_size_chars / 4)
+```
+
+Use the agent-specific input size estimates from `docs/procedures/token-estimation.md`. The blended rate for all assessment agents is `$0.005400/1k tokens` (sonnet). Compute:
+
+```
+est_cost = est_tokens × (blended_rate / 1000)
+```
+
+Round `est_tokens` to the nearest integer; format `est_cost` to 4 decimal places (e.g., `$0.0444`).
+
+**Step 4 — Extract actual tokens per assessment agent.** For each completed assessment agent, read its `<usage>` block from its result:
+
+- If the block is present: `actual_tokens = input_tokens + output_tokens`. Compute `actual_cost = actual_tokens × (blended_rate / 1000)` at 4 decimal places.
+- If the block is missing or unparseable: set `actual_tokens = "N/A"` and `actual_cost = "N/A"`. Log a warning: `"[agent_name] produced no <usage> block; token data unavailable"`. Exclude this agent from phase subtotal and grand total calculations.
+
+Status remains `"complete"` in both cases — a missing usage block does not indicate agent failure.
+
+**Step 5 — Compute Phase 3 subtotals.** Sum `est_tokens` and `est_cost` across all assessment agents (all rows, regardless of N/A status). Sum `actual_tokens` and `actual_cost` only across rows where actual values are numeric (exclude N/A rows). Format subtotal costs to 2 decimal places.
+
+**Step 6 — Write `{PREFIX}-Token-Estimate.md`.** Write the complete file at `docs/assessments/{PREFIX}/{PREFIX}-Token-Estimate.md` using the template below. Replace all `{PREFIX}`, `{N}`, and `{placeholder}` markers with computed values.
+
+```markdown
+# Token Estimate — {PREFIX} — Assessment Pipeline
+
+> Estimates computed before execution. Actuals accumulated as agents complete.
+> Assessment agents (Phase 3) actuals: filled at end of phase.
+> Intervention documentation (Phase 4) actuals: filled on completion.
+> Orchestrator row added by assess-codebase skill at pipeline end.
+> Pricing model: docs/pricing.md (80% input / 20% output split).
+
+## Estimation model
+
+| Parameter | Value |
+|-----------|-------|
+| Avg chars per token | 4 |
+| Haiku system prompt | ~2,000 tokens |
+| Sonnet system prompt | ~3,000 tokens |
+| Base overhead per call | ~5,000 tokens |
+| Input/output split | 80% / 20% |
+
+## Assessment agents (Phase 3)
+
+| Agent | Model | Est. tokens | Est. cost ($) | Actual tokens | Actual cost ($) | Status |
+|-------|-------|-------------|---------------|---------------|-----------------|--------|
+{one row per assessment agent that ran — computed values from Steps 3 and 4 — status = "complete"}
+
+## Intervention documentation (Phase 4)
+
+> To be populated after Phase 4 completion.
+
+| Agent | Model | Est. tokens | Est. cost ($) | Actual tokens | Actual cost ($) | Status |
+|-------|-------|-------------|---------------|---------------|-----------------|--------|
+
+## Remediation
+
+Remediation effort is tracked separately via the feature delivery pipeline (not part of this assessment).
+
+## Phase subtotals
+
+| Phase | Est. tokens | Est. cost ($) | Actual tokens | Actual cost ($) |
+|-------|-------------|---------------|---------------|-----------------|
+| Assessment (Phase 3) | {est_tokens_total} | ${est_cost_total} | {actual_tokens_total} | ${actual_cost_total} |
+| Intervention documentation (Phase 4) | — | — | — | — |
+
+## Grand total
+
+> Partial — updated at pipeline end.
+
+| Metric | Estimated | Actual |
+|--------|-----------|--------|
+| Total tokens | {est_tokens_total} | partial — updated at pipeline end |
+| Total cost ($) | ${est_cost_total_2dp} | partial — updated at pipeline end |
+```
+
+After writing, verify the file is readable: attempt to read it back. If it is unreadable, log an error: `"[timestamp] ERROR: Token Estimate file unreadable after write — {path}: {error}"`. If the write itself fails (e.g., permission denied, disk full), log the error: `"[timestamp] ERROR: Failed to write Token Estimate file — {path}: {error}"` and continue — the pipeline does not halt due to a Token Estimate file I/O failure.
+
+**Step 7 — Log the file write.** Append to the process log:
+
+```
+[timestamp] Phase 3 end: wrote Token Estimate file
+  Assessment agents: {N} rows ({completed} complete, {na_count} with N/A actuals)
+  Location: docs/assessments/{PREFIX}/{PREFIX}-Token-Estimate.md
+```
+
+Where `{N}` is the total number of assessment agents that ran, `{completed}` is the count with numeric actual tokens, and `{na_count}` is the count with `N/A` actual tokens.
+
+### Write initial Effort Estimate file
+
+**Step 1 — Read process log timestamps.** For each completed Phase 3 assessment agent, scan `{PREFIX}-process-log.txt` for lines matching:
+- `Agent START: {agent_name}` → extract start timestamp
+- `Agent DONE: {agent_name}` → extract end timestamp
+
+If both timestamps are present, compute `actual_duration = end_timestamp − start_timestamp`, rounded to the nearest minute. Express as `"Xmin"` or `"Xh Ymin"` (e.g., `"12min"`, `"1h 5min"`). If either timestamp is missing, set `actual_duration = "N/A"` and log a warning: `"[agent_name] has no timestamp in the process log; actual duration unavailable"`.
+
+For the batch wall-clock:
+- `batch_start = minimum of all Phase 3 agent start timestamps`
+- `batch_end = maximum of all Phase 3 agent end timestamps`
+- `batch_actual = batch_end − batch_start`, rounded to nearest minute
+
+**Step 2 — Compute estimates.** On the first run (no prior `{PREFIX}-Effort-Estimate.md` exists), set `est_duration = "N/A"` for all agent rows. On subsequent runs, extract the `actual_duration` from the previous run's rows for each agent and use as the new `est_duration`. If the prior file has `"N/A"` for an agent, continue using `"N/A"` as the estimate.
+
+**Step 3 — Compute delta.** `delta = actual_duration − est_duration`. If either is `"N/A"`, set `delta = "N/A"`. For numeric values, express as `"-Xmin"` (faster), `"+Xmin"` (slower), or `"0min"` (on target).
+
+**Step 4 — Write `{PREFIX}-Effort-Estimate.md`.** Write to `docs/assessments/{PREFIX}/{PREFIX}-Effort-Estimate.md`. Create the directory if it does not exist.
+
+```markdown
+# Effort Estimate — {PREFIX} — Assessment Pipeline
+
+> Wall-clock effort tracking for the assessment pipeline.
+> Assessment agent durations: filled at end of Phase 3.
+> Intervention documentation duration: filled at end of Phase 4.
+> Remediation effort: estimated from Interventions Index at end of Phase 4 using fixed rates.
+> Actual remediation effort tracked by feature delivery pipeline per intervention.
+> Effort rates: CRITICAL=8h, HIGH=4h, MEDIUM=2h, LOW=1h (human hours, sequential).
+
+## Assessment phase
+
+| Agent | Est. duration | Actual duration | Delta | Status |
+|-------|--------------|-----------------|-------|--------|
+| {agent_name} | {est_duration} | {actual_duration} | {delta} | {status} |
+... (one row per Phase 3 agent — intervention-documentation-standard appended at Phase 4 end)
+
+## Assessment phase subtotal
+
+| Metric | Estimated | Actual | Delta |
+|--------|-----------|--------|-------|
+| Phase 3 assessment batch | {est_batch} | {actual_batch} | {delta_batch} |
+| intervention-documentation-standard | {est} | {actual} | {delta} |
+| Total | {total_est} | {total_actual} | {total_delta} |
+
+> Note: Phase 3 "Actual" row uses batch wall-clock (max end − min start), not sum of individual durations.
+> Individual agent durations are in the assessment phase table above.
+
+## Remediation effort estimate
+
+> Pending intervention documentation completion.
+```
+
+If a scope filter was applied, append to the header block: `> Note: Scope filter applied ({scope}). This estimate reflects only {scope} assessment areas.`
+
+After writing, verify the file is readable. If unreadable, log an error: `"[timestamp] ERROR: Effort Estimate file unreadable after write — {path}: {error}"`. If the write fails, log: `"[timestamp] ERROR: Failed to write Effort Estimate file — {path}: {error}"` and continue — the pipeline does not halt due to a file I/O failure.
+
+**Step 5 — Log the write.** Append to the process log:
+
+```
+[timestamp] Phase 3 end: wrote Effort Estimate file
+  Assessment agents: {N} rows ({completed} with actuals, {na_count} with N/A)
+  Location: docs/assessments/{PREFIX}/{PREFIX}-Effort-Estimate.md
+```
+
 ---
 
 ## Phase 4 — Intervention Document Generation
@@ -113,90 +281,122 @@ Invoke `intervention-documentation-standard` with all produced assessment files
 - `{PREFIX}-INT-NNN-{slug}.md` per intervention
 - `{PREFIX}-Interventions-Index.md` (ordered by criticality and dependency)
 
----
+### Append intervention-documentation row to Token Estimate file
 
-## Phase 5 — Remediation Gate
+After `intervention-documentation-standard` completes, update the Token Estimate file as follows.
 
-Follow `docs/procedures/assessment-approval-gate.md`. If user selects "Assessment only", skip to Phase 8 (Summary).
+**Step 1 — Extract actual tokens.** Read the `<usage>` block from the agent result: `actual_tokens = input_tokens + output_tokens`. Compute `actual_cost = actual_tokens × (blended_rate / 1000)` at 4 decimal places. If the block is missing or unparseable: set `actual_tokens = "N/A"` and `actual_cost = "N/A"`, and log a warning: `"intervention-documentation-standard produced no <usage> block; token data unavailable"`. Status remains `"complete"` regardless.
 
----
+**Step 2 — Estimate tokens.** Apply the standard formula:
+
+```
+est_tokens = base_overhead (5,000) + system_prompt_weight (3,000 for sonnet) + (intervention_doc_size_bytes / 4)
+```
 
-## Phase 6 — Remediation Implementation
+If the total size of produced intervention documents is unknown at estimation time, use `~15,500` tokens as a typical estimate. Compute `est_cost = est_tokens × (blended_rate / 1000)` at 4 decimal places. If pricing data is unavailable, set both cost fields to `N/A`.
+
+**Step 3 — Replace the placeholder section.** Open `{PREFIX}-Token-Estimate.md`. Find the "Intervention documentation (Phase 4)" section (the `> To be populated after Phase 4 completion.` placeholder row). Replace the empty table body with the actual row:
+
+| Agent | Model | Est. tokens | Est. cost ($) | Actual tokens | Actual cost ($) | Status |
+|-------|-------|-------------|---------------|---------------|-----------------|--------|
+| intervention-documentation-standard | sonnet | {est_tokens} | {est_cost} | {actual_tokens} | {actual_cost} | complete |
+
+Remove the `> To be populated after Phase 4 completion.` note once the row is written.
+
+**Step 4 — Log the completion.** Append to the process log:
+
+```
+[timestamp] Phase 4 end: appended intervention-documentation-standard row to Token Estimate file. Actual tokens: {N} | Cost: ${X.XXXX}
+```
+
+### Update Effort Estimate file
+
+**Step 1 — Read timestamps and compute duration.** Scan `{PREFIX}-process-log.txt` for `Agent START: intervention-documentation-standard` and `Agent DONE: intervention-documentation-standard`. Compute `actual_duration` (same formula as Phase 3 agents). If missing, set `actual_duration = "N/A"` and log a warning.
+
+**Step 2 — Append intervention-documentation-standard row.** Open `{PREFIX}-Effort-Estimate.md` and append one row to the "Assessment phase" table:
 
-### 6a. Create remediation branch
 ```
-git checkout -b feature/{PREFIX}-remediation
+| intervention-documentation-standard | {est_duration} | {actual_duration} | {delta} | complete |
 ```
-Branch from `develop`.
 
-### 6b. Build remediation execution plan
+`est_duration` follows the same first-run / subsequent-run logic as Phase 3 agents.
+
+**Step 3 — Update assessment phase subtotal.** Fill in the `intervention-documentation-standard` row in the subtotal table and compute the Total row values.
+
+**Step 4 — Build remediation section.** Read `{PREFIX}-Interventions-Index.md` to extract intervention counts by severity. Apply fixed rates: CRITICAL × 8h, HIGH × 4h, MEDIUM × 2h, LOW × 1h. Sum for the human sequential total. If the Interventions Index is missing, write `"Interventions Index not found — remediation estimate unavailable"` as the remediation section body, log a warning, and continue. If all counts are 0, add: `> Note: No remediation required — zero findings identified.`
 
-Read `{PREFIX}-Interventions-Index.md` for approved interventions, dependency order, and parallelism opportunities.
+**Step 5 — Replace placeholder.** Replace the `> Pending intervention documentation completion.` line in the "Remediation effort estimate" section with:
 
-### 6c. Agent assignment
+```markdown
+## Remediation effort estimate
 
-Map each intervention to an agent via its `Suggested Agent Assignment` section. Prefer specialised agents (`security-hardening`, `god-class-decomposition`, etc.) over generic `developer-backend`. Fall back to `developer-backend` for uncovered backend/infra interventions.
+> Derived from {PREFIX}-Interventions-Index.md. Rates: CRITICAL=8h, HIGH=4h, MEDIUM=2h, LOW=1h (human hours, sequential).
+> Actual remediation effort tracked by feature delivery pipeline per intervention.
 
-### 6d. Execution loop
+| Severity | Count | Rate | Subtotal |
+|----------|-------|------|---------|
+| CRITICAL | {count} | 8h | {subtotal} |
+| HIGH | {count} | 4h | {subtotal} |
+| MEDIUM | {count} | 2h | {subtotal} |
+| LOW | {count} | 1h | {subtotal} |
+| **Total** | **{total_count}** | — | **{total_hours}h** |
 
-For each approved intervention (respecting dependency order):
-1. Dispatch assigned agent with: intervention document path + codebase path
-2. Wait for completion
-3. Invoke `review-solution` on all changed files
-4. **PASS** (no CRITICAL): commit — `git commit -m "fix({PREFIX}): {INT-NNN} — {title}"`
-5. **FAIL** (CRITICAL): one rework cycle, re-review. After 2 failed cycles: escalate to user
-6. **WARNING/INFO**: log to Issues Register (see `docs/procedures/issues-register.md`)
+Human sequential total: {total_hours}h
+```
+
+**Step 6 — Validate severity count.** Assert `sum(CRITICAL + HIGH + MEDIUM + LOW)` equals total intervention count in `{PREFIX}-Interventions-Index.md`. If they differ, log: `"Severity count mismatch between Effort Estimate and Interventions Index — check {PREFIX}-Interventions-Index.md"`. Use the Interventions Index counts as the authoritative source.
+
+**Step 7 — Log the update.** Append to the process log:
+
+```
+[timestamp] Phase 4 end: updated Effort Estimate with intervention-documentation-standard row
+  Actual duration: {X}min
+[timestamp] Phase 4 end: populated remediation effort section
+  CRITICAL: {N}, HIGH: {N}, MEDIUM: {N}, LOW: {N}
+  Human sequential total: {X}h
+  Location: docs/assessments/{PREFIX}/{PREFIX}-Effort-Estimate.md
+```
 
 ---
 
-## Phase 7 — Pull Request
-
-1. Push: `git push -u origin feature/{PREFIX}-remediation`
-2. Create PR targeting `develop`:
-   ```
-   gh pr create --title "fix({PREFIX}): codebase remediation" --body "$(cat <<'EOF'
-   ## Assessment Summary
-   - Assessment: {PREFIX} — {codebase description}
-   - Total findings: N CRITICAL, N HIGH, N MEDIUM, N LOW
-   - Source: docs/assessments/{PREFIX}/
-
-   ## Remediation
-   - Interventions approved: N / N proposed
-   - Interventions implemented: N
-   - Issues Register: {N} fixed, {N} deferred → see {PREFIX}-Issues.md
-
-   ## Test plan
-   - [ ] Build passes
-   - [ ] Test suite passes
-   - [ ] Manual verification of critical fixes
-   EOF
-   )"
-   ```
+## Phase 5 — Findings Gate
+
+Follow `docs/procedures/assessment-findings-gate.md`. The gate has two mandatory steps:
+
+**Step 5a — Acknowledge:** present findings summary (including effort estimate) and wait for acknowledgement. Accept any non-empty text reply.
+
+**Step 5b — Flag interventions:** prompt for INT-NNN identifiers to flag for feature delivery. Validate each against `{PREFIX}-Interventions-Index.md`; re-prompt if any are unknown. Accept "None" for zero flagged.
+
+After both steps complete, write `{PREFIX}-Approvals.md` per the format in `docs/procedures/assessment-findings-gate.md`. Verify the file was written before proceeding to Phase 6.
+
+No writes to the Effort Estimate file during Phase 5.
 
 ---
 
-## Phase 8 — Summary
+## Phase 6 — Summary
+
+Report:
 
 ```
-📦 Assessment Manager — Run Summary
+Assessment Manager — Run Summary
 ─────────────────────────────────────────────────────
 Target: {codebase path}  |  Prefix: {PREFIX}
 ─────────────────────────────────────────────────────
 Assessment:
-  ✅ generic-software-assessment    → {PREFIX}-Generic-Assessment.md
-  ✅ layered-architecture-assessment → {PREFIX}-Layer-Assessment.md
-  ✅ concurrency-safety-assessment   → {PREFIX}-Concurrency-Assessment.md
+  ✅ {agent_1}    → {PREFIX}-{output}.md
+  ✅ {agent_2}    → {PREFIX}-{output}.md
+  ...
 ─────────────────────────────────────────────────────
 Findings:      N CRITICAL | N HIGH | N MEDIUM | N LOW
-Interventions: N proposed | N approved
+Interventions: N proposed | N flagged for feature delivery
 ─────────────────────────────────────────────────────
-Remediation:
-  INT-001 ✅ PASS | INT-002 ✅ PASS | INT-003 ⏭ Deferred
-  Issues: N fixed | N deferred → {PREFIX}-Issues.md
+Approvals:     {PREFIX}-Approvals.md
+Effort Estimate: {PREFIX}-Effort-Estimate.md
+Token Estimate:  {PREFIX}-Token-Estimate.md
+Process log:     docs/assessments/{PREFIX}/{PREFIX}-process-log.txt
 ─────────────────────────────────────────────────────
-Pull Request: 🔗 {PR URL}
-Token usage:  {N} tokens  |  Est. cost: $N.NN  (see {PREFIX}-Token-Estimate.md)
-Process log:  docs/assessments/{PREFIX}/{PREFIX}-process-log.txt
+Flagged interventions can be actioned via /define-feature
+referencing the INT-NNN document.
 ─────────────────────────────────────────────────────
 ```
 
@@ -204,15 +404,13 @@ Process log:  docs/assessments/{PREFIX}/{PREFIX}-process-log.txt
 
 ## Guidelines
 
-- **Read all procedures at startup** — `process-log.md`, `issues-register.md`, `assessment-approval-gate.md`
-- **Track tokens for every agent call** — `<usage>` block → ledger → log
+- **Read all procedures at startup** — `process-log.md`, `issues-register.md`, `assessment-findings-gate.md`, `token-estimation.md`
+- **Token tracking — maintain an internal ledger keyed by agent name.** For each completed agent call: extract the `<usage>` block (input_tokens, output_tokens, model), compute `actual_tokens = input_tokens + output_tokens`, and record the result. If the block is absent or unparseable, record `actual_tokens = "N/A"` and log a warning — never halt because of a missing usage block. Estimate tokens for each agent BEFORE dispatch using `est_tokens = base_overhead (5,000) + system_prompt_weight (3,000 for sonnet, 2,000 for haiku) + (input_size_chars / 4)` and compute blended cost using the formula from `docs/pricing.md`. Exclude N/A rows from all cost totals and accuracy statistics; include them in the file as visible rows.
 - **Assessment agents are read-only** — never modify source files during assessment phases
-- **Never skip the Remediation Gate** — remediation cannot start without explicit approval
+- **Never skip the Findings Gate** — it is mandatory regardless of finding count; `--force` re-presents it, never bypasses it
+- **Assessment pipeline is read-only** — no branch creation, no code changes, no commits, no PRs
 - **Assessment agents run in parallel** — they have no mutual dependencies
-- **Prefer specialised remediation agents** over generic developer agents when available
 - **Plan before executing** — always show the plan first
 - **Fail fast on missing target** — if the target path does not exist, stop immediately
 - **Partial assessments are acceptable** — if one agent fails, continue with others
-- **Commit per intervention** — immediately after it passes review
-- **PR targets `develop`** — never push directly; do NOT auto-merge
 - **All output documents in English**

package/.claude/agents/project-manager.md

@@ -52,7 +52,7 @@ state = {
 
 ### 2a. Cross-feature analysis
 
-Compare `feature.md` against each `registry` entry for OVERLAP, DEPENDENCY, or CONFLICT (see `docs/procedures/feature-registry.md`). Show the cross-feature report to the user. If conflicts are found, use `AskUserQuestion` before continuing. If `registry` is empty, output "No prior features — no cross-reference needed."
+Compare `feature.md` against each `registry` entry for OVERLAP, DEPENDENCY, or CONFLICT (see `docs/procedures/feature-registry.md`). Show the cross-feature report to the user. If conflicts are found, output a hard-stop message and wait for a text reply before continuing. Do NOT use `AskUserQuestion` — it cannot be answered through the agent relay chain. If `registry` is empty, output "No prior features — no cross-reference needed."
 
 ### 2b. Build execution plan
 
@@ -301,7 +301,7 @@ To add a new agent: create `.claude/agents/my-agent.md` with a clear `descriptio
 - **Plan before executing** — always show the plan first
 - **Never re-run fresh agents** unless `--force`
 - **Parallelize where possible** — independent agents run concurrently
-- **Gates are hard stops** — use `AskUserQuestion`, wait for the user, write `{PREFIX}-Approvals.md`, verify it on disk. Never auto-approve, never assume, never skip
+- **Gates are hard stops** — output the hard-stop text and wait for a text reply from the user; write `{PREFIX}-Approvals.md`, verify it on disk. Do NOT use `AskUserQuestion` — it cannot be answered through the agent relay chain. Never auto-approve, never assume, never skip
 - **Pre-condition check at Phase 6** — read `{PREFIX}-Approvals.md` and verify both gates ✅ before touching the codebase. If missing, return to the gate
 - **Review at US level** — not per task
 - **Commit per US** — `feat({PREFIX}): implement US-XX — {title}`

package/.claude/skills/assess-codebase/SKILL.md

@@ -1,10 +1,18 @@
 ---
-description: "Assess Codebase — starts the full codebase assessment pipeline (parallel assessment → findings consolidation → intervention documents → approval gate → remediation → review → PR). Usage: /assess-codebase [path] [--scope=architecture,security,quality,concurrency,devops] [--force]"
+description: "Assess Codebase — starts the codebase assessment pipeline (parallel assessment → findings consolidation → intervention documents → findings gate). Usage: /assess-codebase [path] [--scope=architecture,security,quality,concurrency,devops] [--force]"
 argument-hint: "[path] [--scope=architecture,security,quality,concurrency,devops] [--force]"
-disable-model-invocation: true
 ---
 
-Spawn the `assessment-manager` agent with the arguments provided by the user:
+# Assess Codebase
+
+Orchestrates the full codebase assessment pipeline by spawning the `assessment-manager` agent
+and, once it completes, recording the real token consumption in a dedicated file.
+
+---
+
+## Step 1 — Spawn the Assessment Manager
+
+Spawn the `assessment-manager` agent with the exact arguments the user provided:
 
 ```
 subagent_type: assessment-manager
@@ -13,4 +21,121 @@ prompt: <path> [--scope=...] [--force]
 
 If no path is provided, use `.` (current working directory).
 
-Pass the exact arguments the user typed after `/assess-codebase` as the prompt to the agent. Do not add anything else.
+Wait for the agent to complete. Capture its full result, including the `<usage>` block
+that appears at the end of the tool result (format: `subagent_tokens: N`).
+
+The assessment-manager handles the full pipeline internally — it presents the Phase 5 Findings Gate
+to the user, records the acknowledgement and flagged interventions, and ends at the summary.
+The skill waits for the agent to complete and proceeds to Step 2 regardless of outcome.
+
+---
+
+## Step 2 — Extract orchestrator token usage
+
+From the `<usage>` block of the assessment-manager result, read:
+- `subagent_tokens` — total tokens consumed by the assessment-manager agent itself (input + output)
+- `duration_ms` — wall-clock duration of the assessment-manager run
+
+If the `<usage>` block is missing: log warning
+`"assessment-manager produced no <usage> block; orchestrator token data unavailable"`
+and set `actual_tokens = "N/A"`.
+
+---
+
+## Step 3 — Complete Token Estimate file
+
+The assessment-manager will have written `{PREFIX}-Token-Estimate.md` at
+`docs/assessments/{PREFIX}/{PREFIX}-Token-Estimate.md` with assessment and
+intervention-documentation rows. Read that file, then **append** the following in order:
+
+### 3a — Orchestrator row
+
+The orchestrator row is NOT added to any of the three phase-level tables (Assessment agents, Intervention documentation, Remediation agents). It appears only in the Actuals vs Estimate section (Step 3b below).
+
+For use in Step 3b, compute the orchestrator row values as follows:
+
+- Estimated tokens: 80,000 (baseline from estimation model)
+- Estimated cost: $0.4320 — computed as `80,000 × $0.005400 / 1,000` using the sonnet blended
+  rate from `docs/pricing.md`. If `docs/pricing.md` is missing, use `"N/A"` for est_cost.
+- Actual tokens: value from `subagent_tokens` in the `<usage>` block; `"N/A"` if block was missing
+- Actual cost: `(actual_tokens / 1,000) × blended_rate_per_1k`, formatted to 4 decimal places; `"N/A"` if actual_tokens is `"N/A"` or pricing data is unavailable
+
+### 3b — Actuals vs Estimate section
+
+Append a horizontal rule (`---`) followed by an Actuals vs Estimate section. Include one
+row for every agent that ran: all assessment agents, intervention-documentation-standard,
+and the assessment-manager orchestrator.
+
+```markdown
+## Actuals vs Estimate
+
+| Agent | Task/Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
+|-------|------------|-------|-------------|---------------|-------|---------------|-----------------|----------|
+| {agent} | {scope} | {model} | {est} | {actual} | {±delta} | {est_cost} | {actual_cost} | {Xmin Ys} |
+```
+
+Column rules:
+- **Delta**: `actual_tokens − est_tokens`; show as `+N` or `−N`. Show `"N/A"` if either
+  value is missing.
+- **Duration**: convert `duration_ms` to `Xmin Ys` where available; use `"—"` where not.
+- Rows with `"N/A"` actual tokens are still shown in the table but excluded from any
+  aggregate calculations.
+
+### 3c — Estimation accuracy by agent type (conditional)
+
+If 2 or more distinct model tiers appear in the rows that have non-`"N/A"` actual tokens
+(e.g., haiku AND sonnet), append:
+
+```markdown
+## Estimation accuracy by agent type
+
+| Model | Count | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
+|-------|-------|-----------------|-------------------|-----------|-------|
+| {model} | {N} | {avg_est} | {avg_actual} | {avg_delta} | {trend} |
+```
+
+Column rules:
+- One row per model tier (e.g., `haiku`, `sonnet`)
+- Exclude rows with `"N/A"` actual tokens from all averages
+- **Trend**: `"over-target"` if avg delta > +20% of avg est; `"under-target"` if avg delta
+  < −20% of avg est; otherwise `"on-target"`
+
+### 3d — Grand Total section
+
+Update the Grand Total section already written in the file: replace the
+`"partial — updated at pipeline end"` marker with `"Final"` and fill in the computed values:
+
+```markdown
+## Grand Total (Final)
+
+| Metric | Estimated | Actual | Delta | Delta % |
+|--------|-----------|--------|-------|---------|
+| Total tokens (all agents) | {sum_est} | {sum_actual} | ±{delta} | {delta_pct} |
+| Total cost ($) | ${sum_est_cost} | ${sum_actual_cost} | ±${delta_cost} | {delta_cost_pct} |
+| Total wall-clock | — | {Xmin Ys} | — | — |
+```
+
+Column rules:
+- **Delta %**: `(delta / estimated) × 100` at 1 decimal place; show `"N/A"` if estimated is 0
+
+Summation rules:
+- Sum all agents' tokens and costs; exclude `"N/A"` rows from sums
+- Cost values: 2 decimal places for subtotals and totals; 4 decimal places for per-row costs
+- The "Remediation" section in the Token Estimate file contains a static note (not a placeholder); leave it as-is
+- Wall-clock: convert `duration_ms` from the assessment-manager result to minutes/seconds
+
+---
+
+## Step 4 — Report to user
+
+After writing to the Token Estimate file, report:
+
+```
+Assessment pipeline complete.
+   Token estimate + actuals → {PREFIX}-Token-Estimate.md
+   Approvals                → docs/assessments/{PREFIX}/{PREFIX}-Approvals.md
+   Process log              → docs/assessments/{PREFIX}/{PREFIX}-process-log.txt
+```
+
+If the Token Estimate file does not exist (assessment-manager failed before writing it):
+note this in the report but do not halt — the skill has completed its work.

package/CHANGELOG.md

@@ -1,2 +1,4 @@
+## 0.1.6 (2026-07-16)
+## 0.1.5 (2026-07-14)
 ## 0.1.4 (2026-07-14)
 ## 0.1.3 (2026-07-14)

package/CLAUDE.md

@@ -114,7 +114,7 @@ Generic procedures live in `docs/procedures/` in this toolkit. Projects can over
 
 | Agent | subagent_type | Purpose |
 |-------|---------------|---------|
-| Assessment Manager | `assessment-manager` | Orchestrates the full assessment + remediation pipeline |
+| Assessment Manager | `assessment-manager` | Orchestrates the assessment pipeline: parallel assessment → intervention docs → approval gate → effort/token estimates → summary |
 | Generic Software Assessment | `generic-software-assessment` | Broad quality analysis across architecture, security, testability, observability, DevOps |
 | Intervention Documentation Standard | `intervention-documentation-standard` | Generates structured, self-contained intervention documents from assessment findings |
 | God Class Decomposition | `god-class-decomposition` | Safe incremental decomposition of oversized classes and methods |

package/docs/installation.md

@@ -33,7 +33,7 @@ npx @dtlabs/ai-toolkit --local . --force
 
 ### Global installation
 
-Merges `.claude/agents`, `.claude/skills`, `docs/`, and `CLAUDE.md` into `~/.claude/`:
+Merges `.claude/agents`, `.claude/skills`, `.claude/commands`, `docs/`, and `CLAUDE.md` into `~/.claude/`:
 
 ```bash
 npm install -g @dtlabs/ai-toolkit
@@ -68,13 +68,3 @@ ai-toolkit --global --force
 ```bash
 npm view @dtlabs/ai-toolkit version
 ```
-
----
-
-## Publishing a new version
-
-```bash
-npm login                        # authenticate with your npmjs.com account
-npm version patch                # bump version (patch / minor / major)
-npm publish --access public      # --access public is required for scoped packages
-```

package/docs/procedures/approval-gates.md

@@ -16,15 +16,19 @@ Show the user a summary of the generated documents:
 
 ### Step 2 — Request explicit sign-off
 
-Use `AskUserQuestion` with this exact phrasing:
+Output the following hard-stop message and **wait for a text reply from the user**. Do NOT use `AskUserQuestion` — it cannot be answered through the agent relay chain.
 
-> **"Please review the documents above and choose one of the options below.
-> The pipeline CANNOT continue until you make a selection."**
+```
+⛔ GATE 1 — DOCS APPROVAL — HARD STOP
+
+Please review the documents above and reply with one of:
 
-Options:
-- **"Approve — proceed to Work Breakdown"**
-- **"Request changes"** — describe what to change; the pipeline re-runs affected agents, re-validates, and returns here (max 2 revision cycles)
-- **"Approve with notes"** — accepted with comments recorded in the approval file
+  "Approve — proceed to Work Breakdown"
+  "Request changes: <describe what to change>"
+  "Approve with notes: <your comments>"
+
+The pipeline CANNOT continue until you reply directly.
+```
 
 ### Step 3 — Write approval record BEFORE continuing
 
@@ -81,15 +85,19 @@ Show key metrics:
 
 ### Step 3 — Request explicit sign-off
 
-Use `AskUserQuestion`:
+Output the following hard-stop message and **wait for a text reply from the user**. Do NOT use `AskUserQuestion` — it cannot be answered through the agent relay chain.
 
-> **"Please review the Work Breakdown above and choose one of the options below.
-> Implementation CANNOT start until you approve."**
+```
+⛔ GATE 2 — WORK BREAKDOWN APPROVAL — HARD STOP
+
+Please review the Work Breakdown above and reply with one of:
 
-Options:
-- **"Approve — start implementation"**
-- **"Request changes"** — re-run `generate-work-breakdown` with feedback (max 2 cycles)
-- **"Approve with notes"** — accepted with comments recorded
+  "Approve — start implementation"
+  "Request changes: <describe what to change>"
+  "Approve with notes: <your comments>"
+
+Implementation CANNOT start until you reply directly.
+```
 
 ### Step 4 — Update approval record BEFORE starting implementation
 

package/docs/procedures/assessment-findings-gate.md

@@ -0,0 +1,120 @@
+# Procedure: Assessment Findings Gate
+
+After intervention documents are generated, present findings to the user and obtain explicit acknowledgement before closing the pipeline. The pipeline is read-only — no remediation code is written.
+
+## Gate presentation
+
+```
+📊 Assessment Complete — {PREFIX}
+═══════════════════════════════════════
+Assessment results:
+  Generic quality:     [KPI summary scores]
+  Layer violations:    N CRITICAL, N HIGH, N MEDIUM
+  Concurrency hazards: N CRITICAL, N HIGH
+  [other assessments]
+
+Interventions proposed: N total
+  CRITICAL: N  (immediate attention)
+  HIGH:     N  (next sprint)
+  MEDIUM:   N  (planned cycle)
+  LOW:      N  (backlog)
+
+Interventions Index: docs/assessments/{PREFIX}/{PREFIX}-Interventions-Index.md
+
+Remediation Effort Estimate (from {PREFIX}-Effort-Estimate.md)
+─────────────────────────────────────────────────────────────
+  CRITICAL: N × 8h = Xh
+  HIGH:     N × 4h = Xh
+  MEDIUM:   N × 2h = Xh
+  LOW:      N × 1h = Xh
+  Total estimated (human sequential): Xh
+─────────────────────────────────────────────────────────────
+```
+
+## Step 5a — Mandatory acknowledgement
+
+Output the following hard-stop message and **wait for a text reply from the user**. Do NOT use `AskUserQuestion` — it cannot be answered through the agent relay chain.
+
+```
+⛔ FINDINGS GATE — STEP 1 OF 2 — HARD STOP
+
+Please review the Interventions Index above.
+
+Reply with "Acknowledged" (or any text) to confirm you have reviewed the findings.
+
+The pipeline CANNOT continue until you reply directly.
+```
+
+Accept any non-empty text reply as acknowledgement. Record the timestamp.
+
+## Step 5b — Optional intervention flagging
+
+Immediately after acknowledgement, output:
+
+```
+FINDINGS GATE — STEP 2 OF 2
+
+Which interventions (if any) do you want to flag for feature delivery?
+
+Reply with one of:
+  "None" — no interventions flagged
+  "INT-001, INT-003, ..." — comma-separated list of INT-NNN identifiers
+
+Flagged interventions will be recorded in {PREFIX}-Approvals.md.
+Any intervention can be actioned later via /define-feature referencing its INT-NNN document.
+```
+
+**Validation:** For each INT-NNN the user provides, verify it exists in `{PREFIX}-Interventions-Index.md`. If any identifier is unknown, report it and re-prompt Step 5b without proceeding:
+
+```
+Unknown identifier(s): INT-099
+Please re-enter — only identifiers from {PREFIX}-Interventions-Index.md are valid.
+```
+
+Re-prompt until all listed identifiers are valid, or the user replies "None".
+
+## Approvals file format
+
+Write `{PREFIX}-Approvals.md` in the assessment directory **only after both steps complete successfully**. Never write a partial file.
+
+```markdown
+# Findings Acknowledgement — {PREFIX}
+
+## Assessment Reviewed
+
+| Document | Status | Date | Notes |
+|----------|--------|------|-------|
+| {PREFIX}-Generic-Assessment.md | Acknowledged | {date} | — |
+| {PREFIX}-Interventions-Index.md | Acknowledged | {date} | — |
+
+## Interventions Flagged for Feature Delivery
+
+| Intervention | Flagged | Date | Notes |
+|---|---|---|---|
+| INT-001 — {slug} | Yes | {date} | — |
+| INT-002 — {slug} | No | {date} | Not selected |
+```
+
+Rules:
+- Every intervention from `{PREFIX}-Interventions-Index.md` must appear — one row per intervention
+- "Flagged: Yes" for each INT-NNN the user explicitly named in Step 5b
+- "Flagged: No" for all others, with Notes = "Not selected"
+- If zero interventions were flagged, add a note below the table: `> No interventions selected for feature delivery.`
+- If zero interventions exist (empty index), write the table header only and add: `> No interventions proposed — zero findings identified.`
+
+## Process log entries
+
+```
+[timestamp] Phase 5 gate: presented findings (N interventions)
+[timestamp] Phase 5 gate: Step 5a — user acknowledged findings
+[timestamp] Phase 5 gate: Step 5b — user flagged: INT-001, INT-003 (or "none")
+[timestamp] Phase 5 gate: wrote {PREFIX}-Approvals.md
+```
+
+## Rules
+
+- **Never skip this gate** — it is mandatory regardless of finding count
+- **Never write a partial Approvals file** — both steps must complete before writing
+- **`--force` does not bypass the gate** — it re-presents the gate and overwrites the existing Approvals file
+- **Log every gate event** in the process log (gate opened, step 5a complete, step 5b result, file written)
+- **No remediation** — this gate never triggers branch creation, agent dispatch, commits, or PRs

package/docs/procedures/token-estimation.md

@@ -10,6 +10,7 @@ Write `{PREFIX}-Token-Estimate.md` in the feature directory after Work Breakdown
 | Agent system prompt weight — haiku | ~2,000 tokens |
 | Agent system prompt weight — sonnet | ~3,000 tokens |
 | Base overhead per agent call | ~5,000 tokens |
+| Input/output split | 80% / 20% |
 
 ## Cost estimation
 
@@ -98,10 +99,10 @@ The 80/20 input/output split is defined in `docs/pricing.md` — update there if
 
 ## Estimation accuracy by agent type
 
-| Agent type | Invocations | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
-|-----------|------------|----------------|------------------|-----------|-------|
-| haiku agents | N | N | N | ±N | over/under/on-target |
-| sonnet agents | N | N | N | ±N | over/under/on-target |
+| Model | Count | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
+|-------|-------|----------------|------------------|-----------|-------|
+| haiku | N | N | N | ±N | ↑/↓/→ |
+| sonnet | N | N | N | ±N | ↑/↓/→ |
 
 ## Grand Total
 
@@ -117,7 +118,38 @@ The 80/20 input/output split is defined in `docs/pricing.md` — update there if
 - One row per invocation — rework invocations get a "(rework)" suffix
 - Delta (tokens): negative = fewer tokens than estimated, positive = more
 - Cost: computed with blended formula from `docs/pricing.md`; use 4 decimal places for per-agent rows, 2 decimal places for totals
-- Trend: over-target if avg delta > +20%, under-target if < -20%, otherwise on-target
+- Trend: "↑" if avg delta > +5% of avg est, "↓" if avg delta < -5% of avg est, otherwise "→"
 - Duration: convert `duration_ms` to minutes/seconds
 - Model: read from agent frontmatter, default to `sonnet` if not set
 - Missing `<usage>` block → write `N/A`, exclude from accuracy stats and cost totals
+
+## Assessment pipeline usage
+
+The `assessment-manager` agent reads this procedure at Phase 3 start before dispatching assessment agents, in the same way that `project-manager` reads it before dispatching implementation agents. If this file is missing, the assessment pipeline halts with an error — this is the only non-graceful failure mode in the pipeline.
+
+### Assessment agent input size estimates
+
+All assessment agents and the `intervention-documentation-standard` agent run on **sonnet** — use the `$0.005400/1k tokens` blended rate from `docs/pricing.md`.
+
+Apply the standard formula with the code input sizes below:
+
+```
+est_tokens = base_overhead + system_prompt_weight + (input_size_chars / 4)
+           = 5,000        + 3,000 (sonnet)        + (input_size_chars / 4)
+```
+
+| Agent | Approx. input size | Input tokens (chars ÷ 4) | Est. total tokens |
+|-------|--------------------|--------------------------|-------------------|
+| generic-software-assessment | ~80,000 chars of code | ~20,000 | ~28,000 |
+| layered-architecture-assessment | ~50,000 chars of code | ~12,500 | ~20,500 |
+| concurrency-safety-assessment | ~40,000 chars of code | ~10,000 | ~18,000 |
+| other assessment agents | ~30,000 chars of code | ~7,500 | ~15,500 |
+| intervention-documentation-standard | ~30,000 chars of assessment findings | ~7,500 | ~15,500 |
+
+### Remediation agents
+
+Remediation agents receive an intervention document (~20,000 chars, ~5,000 tokens for the doc portion) plus relevant code sections. Use the intervention doc portion as the base input estimate and add code section tokens using the standard formula. Typical total range: 13,000–25,000 tokens depending on intervention scope.
+
+### Orchestrator (assessment-manager)
+
+Estimate as the sum of all child agent result sizes (as input) plus process log writes (as output), following the same orchestrator rule as `project-manager`. Use **80,000 tokens** as a conservative baseline for a full pipeline run (assessment + intervention documentation + remediation phases combined).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/docs/procedures/assessment-approval-gate.md

@@ -1,60 +0,0 @@
-# Procedure: Assessment Remediation Gate
-
-After intervention documents are generated, present findings to the user and obtain explicit approval before any remediation code is written.
-
-## Gate presentation
-
-```
-📊 Assessment Complete — ASSESS-001
-═══════════════════════════════════════
-Assessment results:
-  Generic quality:     [KPI summary scores]
-  Layer violations:    N CRITICAL, N HIGH, N MEDIUM
-  Concurrency hazards: N CRITICAL, N HIGH
-  [other assessments]
-
-Interventions proposed: N total
-  CRITICAL: N  (immediate attention)
-  HIGH:     N  (next sprint)
-  MEDIUM:   N  (planned cycle)
-  LOW:      N  (backlog)
-
-Interventions Index: docs/assessments/ASSESS-001/ASSESS-001-Interventions-Index.md
-```
-
-Use `AskUserQuestion`:
-- **"Approve all"** — all proposed interventions approved
-- **"Approve CRITICAL only"** — only CRITICAL severity approved
-- **"Select interventions"** — user specifies INT-NNN to approve (comma-separated)
-- **"Assessment only"** — stop here, no remediation
-
-If the user selects **"Assessment only"**, skip to the Summary phase.
-
-## Approvals file format
-
-Write `{PREFIX}-Approvals.md` in the assessment directory:
-
-```markdown
-# Approval Record — {PREFIX}
-
-## Assessment Approvals
-
-| Document | Status | Date | Notes |
-|----------|--------|------|-------|
-| {PREFIX}-Generic-Assessment.md | ✅ Reviewed | {date} | — |
-| {PREFIX}-Interventions-Index.md | ✅ Reviewed | {date} | — |
-
-## Remediation Scope
-
-| Intervention | Approved | Date | Notes |
-|---|---|---|---|
-| INT-001 — sql-injection-hardening | ✅ Approved | {date} | — |
-| INT-002 — god-class-decomposition | ✅ Approved | {date} | — |
-| INT-003 — di-refactoring | ❌ Deferred | {date} | Out of current sprint scope |
-```
-
-## Rules
-
-- **Never skip this gate** — remediation cannot start without explicit approval
-- **Log the approval outcome** in the process log
-- **Record every decision** including deferred interventions and the reason