@dtlabs/ai-toolkit 0.1.7 → 0.2.0

package/.claude/agents/define-feature.md

@@ -1,6 +1,7 @@
 ---
 name: define-feature
 description: "Define Feature — grills the user with targeted questions to define a new feature, then writes feature.md in docs/features/FTR-XXX-slug/. Output: feature.md ready for /implement-feature"
+model: sonnet
 ---
 
 # Define Feature

package/.claude/agents/dependency-injection-refactoring.md

@@ -1,6 +1,7 @@
 ---
 name: dependency-injection-refactoring
 description: "Dependency Injection Refactoring — guides the incremental conversion of tightly coupled or statically accessed dependencies to constructor-injected services, preserving build integrity at every step. Language-agnostic; reads AGENTS.md for framework-specific DI patterns. Input: target classes from intervention document"
+model: sonnet
 ---
 
 # Dependency Injection Refactoring

package/.claude/agents/dependency-supply-chain-security.md

@@ -1,6 +1,7 @@
 ---
 name: dependency-supply-chain-security
 description: "Dependency Supply Chain Security — guides the implementation of dependency integrity controls: trusted package sources, deterministic restore via lock files, unused dependency audit, and SCA integration in CI/CD pipelines. Works with npm, pip, NuGet, Maven, and other package managers; reads AGENTS.md for project stack. Output: remediated configuration files + CI/CD pipeline changes"
+model: sonnet
 ---
 
 # Dependency Supply Chain Security

package/.claude/agents/developer-backend.md

@@ -1,6 +1,7 @@
 ---
 name: developer-backend
 description: "Senior Backend Developer — implements backend tasks (DB, BE, INFRA domains) from the Work Breakdown following project conventions. Input: path to feature.md + task IDs"
+model: sonnet
 ---
 
 # Backend Developer Agent

package/.claude/agents/developer-frontend.md

@@ -1,6 +1,7 @@
 ---
 name: developer-frontend
 description: "Senior Frontend Developer — implements frontend tasks (FE domain) from the Work Breakdown following project conventions. Input: path to feature.md + task IDs"
+model: sonnet
 ---
 
 # Frontend Developer Agent

package/.claude/agents/developer-testing.md

@@ -1,6 +1,7 @@
 ---
 name: developer-testing
 description: "Senior Test Engineer — creates unit/integration tests for implemented features (TEST domain). Input: path to feature.md + task IDs"
+model: sonnet
 ---
 
 # Testing Agent

package/.claude/agents/domain-model-refactoring.md

@@ -1,6 +1,7 @@
 ---
 name: domain-model-refactoring
 description: "Domain Model Refactoring — guides the decomposition of monolithic domain model files, introduction of type hierarchies for structurally similar types, and alignment of model names with domain ubiquitous language. Language-agnostic; reads AGENTS.md for project conventions. Input: target model directory from intervention document"
+model: sonnet
 ---
 
 # Domain Model Refactoring

package/.claude/agents/god-class-decomposition.md

@@ -1,6 +1,7 @@
 ---
 name: god-class-decomposition
 description: "God Class Decomposition — guides the safe, incremental decomposition of oversized classes and methods using responsibility cluster analysis, extract-method, extract-class, and parameter object refactoring. Language-agnostic; reads AGENTS.md for project conventions. Input: target class(es) from intervention document"
+model: sonnet
 ---
 
 # God Class Decomposition

package/.claude/agents/init-agents-md.md

@@ -1,6 +1,7 @@
 ---
 name: init-agents-md
 description: "Analyzes a project codebase and generates a complete AGENTS.md file with tech stack, conventions, real code patterns, build/test commands, and hard constraints. Input: (optional) path to project root — defaults to current working directory."
+model: sonnet
 tools: Read, Glob, Grep, Bash, Write
 ---
 

package/.claude/agents/install-toolkit.md

@@ -1,6 +1,7 @@
 ---
 name: install-toolkit
 description: "Installs the ai-toolkit into a destination project by copying agents, skills, commands, and procedures. Input: [path-to-destination] [--force] — defaults to current working directory"
+model: sonnet
 ---
 
 # Install Toolkit
@@ -43,13 +44,14 @@ The user provides:
 
 ## Step 2 — Plan what to copy
 
-Four source directories to install:
+Five source directories to install:
 
 | Source (toolkit) | Destination | Purpose |
 |------------------|-------------|---------|
 | `.claude/agents/` | `{dest}/.claude/agents/` | All spawnable subagents |
 | `.claude/skills/` | `{dest}/.claude/skills/` | All user-invocable skills (except `install-toolkit/`) |
 | `.claude/commands/` | `{dest}/.claude/commands/` | All slash commands |
+| `.claude/workflows/` | `{dest}/.claude/workflows/` | Claude Code Workflow scripts for orchestrated pipelines |
 | `docs/procedures/` | `{dest}/docs/procedures/` | Generic procedures (only if destination has no override) |
 
 For each file, compare source content against destination using an MD5/hash check and determine status:
@@ -63,7 +65,6 @@ Build and display the plan before executing:
 📦 Install Plan  →  {destination}
 ──────────────────────────────────────────────────
 .claude/agents/
-  ✅ NEW       project-manager.md
   ✅ NEW       generate-requirements.md
   ⚠️  MODIFIED  developer-backend.md    ← content differs
   ⏭  SAME      review-solution.md
@@ -72,6 +73,13 @@ Build and display the plan before executing:
   ✅ NEW       implement-feature/SKILL.md
   ⏭  SAME      init-agents/SKILL.md
 
+.claude/workflows/
+  ✅ NEW       pm-phase1.js
+  ✅ NEW       pm-phase2.js
+  ✅ NEW       pm-phase3.js
+  ✅ NEW       am-phase1.js
+  ✅ NEW       am-phase2.js
+
 docs/procedures/
   ✅ NEW       code-generation.md
   ⏭  SAME      testing.md
@@ -106,6 +114,8 @@ cp "{source_file}" "{dest_file}"
 
 **Never copy the `install-toolkit/` skill directory** — this skill is toolkit-internal and has no use in a destination project.
 
+**Never copy `.claude/settings.json` or `.claude/settings.local.json`** — these are user-owned configuration. Copying them would clobber the destination's existing settings. The toolkit's own `settings.json` exists only to configure this repo; it is verified and advised on (Step 4b), never installed.
+
 **For `docs/procedures/`**: copy only files that don't already exist in the destination (regardless of `--force`) — project-specific procedure overrides must never be clobbered.
 
 ---
@@ -123,6 +133,44 @@ After copying:
 
 ---
 
+## Step 4b — Verify subagent spawn depth (verify & advise ONLY — never write)
+
+The orchestrated pipelines (`/implement-feature`, `/assess-codebase`) require the
+environment variable `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` to be set to `2` or higher.
+Without it (Claude Code default is `1`), an orchestrator running as a subagent cannot
+spawn its worker subagents, so it executes every task inline on its own model —
+per-agent model assignment, context isolation, and per-agent token telemetry are all lost.
+
+**This is a check, not a change. Do NOT create or edit any settings file** — merging user
+configuration is out of scope and risks clobbering the user's existing settings.
+
+1. Look for the variable in the destination's settings, checking in order:
+   - `{dest}/.claude/settings.local.json`
+   - `{dest}/.claude/settings.json`
+   - `~/.claude/settings.json` (user-global)
+   Read each with a tolerant JSON parse; a value of `2` or higher in `env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` satisfies the requirement.
+2. **If satisfied** → report a one-line confirmation and continue.
+3. **If missing / below 2** → print a warning and the exact snippet the user must add themselves:
+   ```
+   ⚠️  CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH is not set to 2+.
+       Without it, orchestrated pipelines run every worker inline on the
+       orchestrator model (per-agent models, context isolation, and token
+       telemetry are lost).
+
+       Add this to .claude/settings.json (this project) or ~/.claude/settings.json
+       (all projects) — the installer does NOT edit it for you:
+
+         {
+           "env": {
+             "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
+           }
+         }
+
+       Then restart Claude Code so the variable is loaded.
+   ```
+
+---
+
 ## Step 5 — Matt Pocock Skills (version check + optional install/update)
 
 After copying the toolkit files, check the state of Matt Pocock's skills:
@@ -167,7 +215,87 @@ After copying the toolkit files, check the state of Matt Pocock's skills:
 
 ---
 
-## Step 6 — Report
+## Step 6 — Compact Instructions opt-in
+
+The toolkit includes a `# Compact instructions` section for `~/.claude/CLAUDE.md` that guides Claude's auto-compaction (what to keep, what to drop) and enables proactive topic-change suggestions.
+
+1. **Offer the opt-in** — inform the user and ask:
+
+   > "Would you like to add a `# Compact instructions` section to your global `~/.claude/CLAUDE.md`?
+   > It guides auto-compaction to preserve decision-critical information and suggests running `/compact` when you switch topics."
+   >
+   > Options: "Yes — add it" / "No — skip"
+
+2. If the user selects **No**: skip silently; set `compact_instructions_status = "skipped (user said No)"`.
+
+3. If the user selects **Yes**:
+
+   a. **Resolve path**: `CLAUDE_MD="$HOME/.claude/CLAUDE.md"` (Windows bash: `$USERPROFILE/.claude/CLAUDE.md` if `$HOME` is not set).
+
+   b. **Idempotency check**: search the file for the exact heading `# Compact instructions`:
+      ```bash
+      grep -q "^# Compact instructions" "$CLAUDE_MD" 2>/dev/null && echo "exists" || echo "absent"
+      ```
+      - If **exists**: display skip notice and set `compact_instructions_status = "skipped (already present)"`. Do **not** modify the file.
+      - If **absent** (or file does not exist): continue to step (c).
+
+   c. **Request confirmation** — display exactly:
+      > "I am about to append a `# Compact instructions` section to your global `~/.claude/CLAUDE.md`. Confirm to proceed."
+
+      - If the user **declines**: skip silently; set `compact_instructions_status = "skipped (declined)"`.
+      - If the user **confirms**: continue to step (d).
+
+   d. **Write the section** — append verbatim to `~/.claude/CLAUDE.md` (create the file if it does not exist):
+
+      ```bash
+      mkdir -p "$(dirname "$CLAUDE_MD")"
+      cat >> "$CLAUDE_MD" << 'COMPACT_SECTION'
+
+# Compact instructions
+
+## What to preserve
+When compacting, always keep:
+- Current objective and active task
+- Confirmed decisions and user approvals
+- User answers to questions asked during the session
+- Paths of files created or modified
+- Open errors and unresolved blockers
+- Finding IDs, artifact IDs, FTR/ASSESS/INT reference numbers
+
+## What to discard
+When compacting, drop:
+- Raw grep and search results
+- Successful tool outputs (file reads, bash commands that completed without error)
+- Repeated or superseded explanations
+- Superseded plans and intermediate reasoning steps
+
+## Topic-change notification
+When the user sends a message containing any of the following phrases (case-insensitive):
+"passiamo a", "ora facciamo", "prossimo punto", "prossimo argomento", "cambiamo argomento",
+"nuovo argomento", "let's move on to", "next topic", "switching to", "now let's do",
+"moving on to", "next up" —
+
+— pause before answering and send exactly this message:
+
+> **Context compaction suggested**
+>
+> You are about to switch to a new topic. Compacting the context now will keep the next session clean and focused.
+>
+> Reply **Approve - Compact context** to run `/compact` now, or continue to proceed without compacting.
+
+If the user replies "Approve - Compact context", run `/compact`. Otherwise proceed normally.
+COMPACT_SECTION
+      ```
+
+      Report success: "✅ `# Compact instructions` section added to `~/.claude/CLAUDE.md`."
+      Set `compact_instructions_status = "✅ added to ~/.claude/CLAUDE.md"`.
+
+**Skip notice** (displayed when section already exists):
+> "A `# Compact instructions` section already exists in `~/.claude/CLAUDE.md`. No changes were made. Review and update it manually if needed."
+
+---
+
+## Step 7 — Report
 
 ```
 ✅ Toolkit installed at {destination}
@@ -177,6 +305,8 @@ Modified/overwritten: N
 Modified/kept:        N  (user chose to keep existing version)
 Unchanged (same):    N  (skipped silently)
 Matt Pocock skills: ✅ installed v{X} / ⬆️ updated v{old}→v{new} / ⏭ skipped / ✅ already up to date v{X}
+Spawn depth: ✅ CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2+ present / ⚠️ MISSING — see action above
+Compact instructions: {compact_instructions_status}
 ──────────────────────────────────────────────────
 Next steps:
   1. Run /init-agents to generate AGENTS.md for this project
@@ -192,5 +322,6 @@ If any modified files were kept by the user (not overwritten), list them so they
 
 - **Never overwrite `docs/procedures/` files** regardless of `--force` — project overrides take priority
 - **Never copy `install-toolkit.md`** — it's a toolkit-internal utility
+- **Never copy or edit `settings.json` / `settings.local.json`** — user-owned config; only verify and advise (Step 4b)
 - **Create directories as needed** — destination may not have `.claude/` yet
 - **Abort cleanly** if destination path is invalid — do not create partial installs

package/.claude/agents/intervention-documentation-standard.md

@@ -1,6 +1,7 @@
 ---
 name: intervention-documentation-standard
 description: "Intervention Documentation Standard — generates structured, self-contained intervention documents from assessment findings. Each document is independently actionable by an architect or developer agent. Input: assessment findings; Output: {ASSESS_PREFIX}-INT-NNN-{slug}.md per finding + Interventions-Index.md"
+model: sonnet
 tools: Read, Grep, Glob, Bash, Write
 ---
 

package/.claude/agents/review-solution.md

@@ -1,6 +1,7 @@
 ---
 name: review-solution
 description: "Senior Architect — full solution review across quality, reuse, architecture, and security dimensions. Reports findings without auto-fixing. Input: scope (files, US-XX, or git diff)"
+model: opus
 tools: Read, Grep, Glob, Bash
 ---
 

package/.claude/agents/security-hardening.md

@@ -1,6 +1,7 @@
 ---
 name: security-hardening
 description: "Security Hardening — guides the implementation of targeted security fixes: input validation at system boundaries, parameterised queries, secret management, log sanitisation, and TLS/transport configuration. Language-agnostic; reads AGENTS.md for project-specific patterns. Input: security findings from assessment"
+model: sonnet
 ---
 
 # Security Hardening

package/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
+  }
+}

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

@@ -5,66 +5,150 @@ argument-hint: "[path] [--scope=architecture,security,quality,concurrency,devops
 
 # 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.
+Orchestrates the full codebase assessment pipeline by invoking two sequential workflow phases
+(`am-phase1`, `am-phase2`), handling the Findings Gate in the main loop between the phases,
+and recording the real token consumption at the end.
+
+Each workflow phase runs as a real subagent boundary, ensuring assessment agents are dispatched
+with accurate per-agent `usage` data and their declared `model:` frontmatter honoured.
+
+---
+
+## Step 1 — Determine assessment prefix
+
+Scan `docs/assessments/` for folders matching `ASSESS-[0-9]+*`. Increment the highest number
+found, or start at `ASSESS-001`. This prefix is used for all output files in this run.
 
 ---
 
-## Step 1 — Spawn the Assessment Manager
+## Step 2 — Invoke am-phase1 (Assessment Phase)
 
-Spawn the `assessment-manager` agent with the exact arguments the user provided:
+Invoke the `am-phase1` workflow:
 
 ```
-subagent_type: assessment-manager
-prompt: <path> [--scope=...] [--force]
+subagent_type: am-phase1
+prompt: <path> [--scope=<areas>] --prefix ASSESS-NNN [--force]
 ```
 
-If no path is provided, use `.` (current working directory).
+If no path was provided by the user, use `.` (current working directory).
+Always pass `--prefix ASSESS-NNN` with the prefix determined in Step 1.
+
+Wait for the workflow to complete. Capture its full result, including the `<usage>` block
+(format: `subagent_tokens: N`). Extract from the result:
+- `prefix` — confirmed assessment prefix
+- `output_dir` — path to `docs/assessments/ASSESS-NNN/`
+- `assessment_summaries` — list of `{ agent, output_file }` for each completed assessment
+- `interventions_index_path` — path to `{PREFIX}-Interventions-Index.md`
+- `severity_counts` — `{ CRITICAL, HIGH, MEDIUM, LOW }`
+- `total_interventions` — total intervention count
+- `remediation_hours_est` — estimated remediation hours
+- `effort_estimate_path` — path to `{PREFIX}-Effort-Estimate.md`
+- `token_estimate_path` — path to `{PREFIX}-Token-Estimate.md`
+- `errors` — any agent failures during phase 1
+
+If `errors` is non-empty, report them to the user before presenting the Findings Gate.
+Partial assessments are acceptable — present the Findings Gate with available data.
+
+---
+
+## Step 3 — Present Findings Gate (HARD STOP — present in main loop)
+
+The Findings Gate has two mandatory steps.
+
+### Step 3a — Acknowledge
+
+Present the findings summary to the user:
+
+```
+Assessment complete for {prefix} — {output_dir}
+────────────────────────────────────────────────────────────
+Findings:      {CRITICAL} CRITICAL | {HIGH} HIGH | {MEDIUM} MEDIUM | {LOW} LOW
+Interventions: {total_interventions} proposed
+────────────────────────────────────────────────────────────
+Estimated remediation effort: {remediation_hours_est}h (human sequential)
+Reference: {effort_estimate_path} for full breakdown
+────────────────────────────────────────────────────────────
+{list each assessment agent and its output file}
+────────────────────────────────────────────────────────────
+```
+
+Then output this hard-stop message and **wait for any non-empty text reply from the user**:
+
+```
+⛔ FINDINGS GATE — ASSESSMENT ACKNOWLEDGEMENT — HARD STOP
+
+Please review the assessment findings above.
+
+Reply with any text to acknowledge (e.g. "Acknowledged", "OK", "Proceed").
+You will then be asked which interventions to flag for feature delivery.
+
+The pipeline CANNOT continue until you reply directly.
+```
 
-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`).
+Capture the acknowledgement text.
 
-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 3b — Flag interventions
+
+After acknowledgement, read `{PREFIX}-Interventions-Index.md` and list all INT-NNN identifiers.
+Present them to the user and prompt:
+
+```
+Which interventions do you want to flag for feature delivery?
+
+{list of INT-NNN — title — criticality}
+
+Reply with a comma-separated list of INT-NNN identifiers (e.g. "INT-001, INT-003"),
+or reply "None" to flag nothing.
+```
+
+Wait for a text reply. Validate each supplied identifier against the Interventions Index.
+If any are unknown, list them and re-prompt once. Accept "None" for zero flagged.
+
+Capture the flagged identifiers (as a comma-separated string, or "none").
 
 ---
 
-## Step 2 — Extract orchestrator token usage
+## Step 4 — Invoke am-phase2 (Approvals and Registry Phase)
 
-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
+Invoke the `am-phase2` workflow:
 
-If the `<usage>` block is missing: log warning
-`"assessment-manager produced no <usage> block; orchestrator token data unavailable"`
-and set `actual_tokens = "N/A"`.
+```
+subagent_type: am-phase2
+prompt: --prefix {prefix} --output-dir {output_dir} --flagged {flagged_ids} --ack "{acknowledgement_text}"
+```
+
+Where `{flagged_ids}` is the comma-separated list of INT-NNN identifiers (or "none").
+
+Wait for the workflow to complete. Extract from the result:
+- `approvals_path` — path to `{PREFIX}-Approvals.md`
+- `registry_updated` — registry write result string
+- `summary` — full assessment summary text
 
 ---
 
-## Step 3 — Complete Token Estimate file
+## Step 5 — 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:
+From the `<usage>` block of the am-phase1 result, read:
+- `subagent_tokens` — total tokens consumed by the am-phase1 workflow
+- `duration_ms` — wall-clock duration of am-phase1
 
-### 3a — Orchestrator row
+If the `<usage>` block is missing: log warning
+`"am-phase1 produced no <usage> block; orchestrator token data unavailable"`
+and set `actual_tokens = "N/A"`.
 
-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).
+Read `{token_estimate_path}`. Append the following in order:
 
-For use in Step 3b, compute the orchestrator row values as follows:
+### 5a — Orchestrator row (for use in 5b only)
 
+Compute values:
 - 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
+- Estimated cost: $0.4320 — `80,000 × $0.005400 / 1,000` using sonnet blended rate
+- Actual tokens: `subagent_tokens` from `<usage>` block; `"N/A"` if missing
+- Actual cost: `(actual_tokens / 1,000) × 0.005400` at 4 decimal places; `"N/A"` if unavailable
 
-### 3b — Actuals vs Estimate section
+### 5b — 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.
+Append a horizontal rule (`---`) followed by:
 
 ```markdown
 ## Actuals vs Estimate
@@ -72,19 +156,18 @@ and the assessment-manager orchestrator.
 | 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} |
+...
+| assessment-manager/am-phase1 (orchestrator) | — | sonnet | 80,000 | {actual} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
 ```
 
 Column rules:
-- **Delta**: `actual_tokens − est_tokens`; show as `+N` or `−N`. Show `"N/A"` if either
-  value is missing.
+- **Delta**: `actual_tokens − est_tokens`; show as `+N` or `−N`. Show `"N/A"` if either 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.
+- Rows with `"N/A"` actual tokens are still shown but excluded from aggregate calculations.
 
-### 3c — Estimation accuracy by agent type (conditional)
+### 5c — 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:
+If 2+ distinct model tiers appear with non-N/A actuals, append:
 
 ```markdown
 ## Estimation accuracy by agent type
@@ -94,16 +177,13 @@ If 2 or more distinct model tiers appear in the rows that have non-`"N/A"` actua
 | {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"`
+- Exclude N/A rows from averages
+- **Trend**: `"over-target"` if avg delta > +20% of avg est; `"under-target"` if < −20%; else `"on-target"`
 
-### 3d — Grand Total section
+### 5d — 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:
+Update the Grand Total section: replace `"partial — updated at pipeline end"` with Final values:
 
 ```markdown
 ## Grand Total (Final)
@@ -115,27 +195,26 @@ Update the Grand Total section already written in the file: replace the
 | Total wall-clock | — | {Xmin Ys} | — | — |
 ```
 
-Column rules:
-- **Delta %**: `(delta / estimated) × 100` at 1 decimal place; show `"N/A"` if estimated is 0
-
-Summation rules:
+- **Delta %**: `(delta / estimated) × 100` at 1 decimal place; `"N/A"` if estimated is 0
 - 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
+- Cost: 2 decimal places for totals; 4 decimal places for per-row costs
+- The "Remediation" section contains a static note — leave it as-is
+- Wall-clock: convert `duration_ms` from am-phase1 `<usage>` to minutes/seconds
 
 ---
 
-## Step 4 — Report to user
+## Step 6 — 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
+   Token estimate + actuals → {token_estimate_path}
+   Approvals                → {approvals_path}
+   Process log              → {output_dir}/{prefix}-process-log.txt
+
+{summary from am-phase2}
 ```
 
-If the Token Estimate file does not exist (assessment-manager failed before writing it):
+If the Token Estimate file does not exist (am-phase1 failed before writing it):
 note this in the report but do not halt — the skill has completed its work.