@dtlabs/ai-toolkit 0.1.6 → 0.1.7

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

@@ -95,7 +95,7 @@ Target codebase
 
 ## Phase 3 — Assessment Execution
 
-Dispatch all assessment agents in parallel (`run_in_background: true`). Each agent receives: target codebase path, assessment prefix, output directory path. Track tokens for every agent call (see `docs/procedures/process-log.md`).
+Dispatch all assessment agents in parallel by invoking multiple Agent tool calls in the same response. Each agent receives: target codebase path, assessment prefix, output directory path. Do NOT use `run_in_background: true` — background completion notifications are not delivered to sub-agent contexts and will cause the pipeline to block indefinitely. Track tokens for every agent call (see `docs/procedures/process-log.md`).
 
 After all complete:
 - Verify each expected output file exists and is non-empty
@@ -375,6 +375,261 @@ No writes to the Effort Estimate file during Phase 5.
 
 ## Phase 6 — Summary
 
+### Data Contract: Interventions Index
+
+The registry write logic depends on `{PREFIX}-Interventions-Index.md` produced by `intervention-documentation-standard` in Phase 4. The following contract defines the expected format that must be honoured before severity counts can be extracted.
+
+**Expected table structure:**
+
+```markdown
+| ID | Title | Area | Criticality | Depends on | Suggested Agent |
+|---|---|---|---|---|---|
+| INT-001 | ... | Security | CRITICAL | — | developer-backend |
+```
+
+**Criticality column contract:**
+
+| Attribute | Value |
+|-----------|-------|
+| Column name | `Criticality` (exact, case-sensitive) |
+| Valid values | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` (exact, case-sensitive) |
+| Type | String — one value per row |
+| Source | Produced by `intervention-documentation-standard` Phase 4 |
+
+**Counting algorithm:**
+
+1. Locate the main interventions table in the file
+2. For each data row, extract the value in the `Criticality` column
+3. Count rows where `Criticality = "CRITICAL"` → `critical_count`
+4. Count rows where `Criticality = "HIGH"` → `high_count`
+5. Count rows where `Criticality = "MEDIUM"` → `medium_count`
+6. Count rows where `Criticality = "LOW"` → `low_count`
+7. Compute `total_count = critical_count + high_count + medium_count + low_count`
+
+**Error handling:**
+
+| Condition | Action |
+|-----------|--------|
+| File not found | Log warning: `"[timestamp] WARNING: {PREFIX}-Interventions-Index.md not found; severity counts set to 0"` — return all counts as 0; continue |
+| `Criticality` column absent from table header | Log warning: `"[timestamp] WARNING: {PREFIX}-Interventions-Index.md missing Criticality column; severity counts set to 0"` — return all counts as 0; continue |
+| Row contains unrecognised Criticality value | Skip that row; log warning with row ID and value — count valid rows only; continue |
+| File present but table is empty | Return all counts as 0 — not an error; valid for zero-finding assessments |
+
+Severity count contract violations are **non-fatal** to the pipeline. The registry row is written with the counts available (defaulting to 0). The Phase 6 summary includes any warnings from this step.
+
+---
+
+### Data Contract: Approvals File
+
+The registry write logic depends on `{PREFIX}-Approvals.md` produced by the Findings Gate in Phase 5. The following contract defines the expected format that must be honoured before the flagged count can be extracted.
+
+**Expected section and table structure:**
+
+```markdown
+## Interventions Flagged for Feature Delivery
+
+| Intervention | Flagged | Date | Notes |
+|---|---|---|---|
+| INT-001 — ... | Yes | {date} | — |
+| INT-002 — ... | No | {date} | Not selected |
+```
+
+**Flagged column contract:**
+
+| Attribute | Value |
+|-----------|-------|
+| Section heading | `## Interventions Flagged for Feature Delivery` (exact, case-sensitive) |
+| Column name | `Flagged` (exact, case-sensitive) |
+| Valid values | `Yes` or `No` (exact, case-sensitive — `yes`, `YES`, `no`, `NO` are not valid) |
+| Type | String — one value per row |
+| Source | Produced by assessment-manager Phase 5 (Findings Gate) |
+
+**Counting algorithm:**
+
+1. Locate the `## Interventions Flagged for Feature Delivery` section in the file
+2. Parse the Markdown table within that section
+3. Count rows where the `Flagged` column value is exactly `"Yes"` (case-sensitive) → `flagged_count`
+4. If the table is present but empty, set `flagged_count = 0` — valid for zero-flagged runs
+
+**Error handling:**
+
+| Condition | Action |
+|-----------|--------|
+| File not found | Log error: `"[timestamp] ERROR: {PREFIX}-Approvals.md not found; cannot extract flagged count"` — **halt registry write**; report in Phase 6 summary |
+| `Interventions Flagged for Feature Delivery` section missing | Log error: `"[timestamp] ERROR: {PREFIX}-Approvals.md missing required section 'Interventions Flagged for Feature Delivery'; cannot extract flagged count"` — **halt registry write**; report in Phase 6 summary |
+| `Flagged` column absent from table header | Log error: `"[timestamp] ERROR: {PREFIX}-Approvals.md missing Flagged column; cannot extract flagged count"` — **halt registry write**; report in Phase 6 summary |
+| File present but section or table is malformed (unparseable) | Log error: `"[timestamp] ERROR: {PREFIX}-Approvals.md malformed; cannot extract flagged count"` — **halt registry write**; report in Phase 6 summary |
+
+Approvals file contract violations are **fatal to the registry write**. Do not create or modify the registry file. The Phase 6 summary reports: `Registry: docs/assessments/registry.md [ERROR — Approvals file contract violation; see process log]`. The pipeline itself does not halt.
+
+---
+
+### Registry Write Algorithm
+
+Execute the following steps in sequence at the start of Phase 6, before building the summary report. Log the start of registry write operations to the process log:
+
+```
+[timestamp] Phase 6 start: registry write
+```
+
+**Step 1 — Prerequisite check.** Before any registry write, verify that `{PREFIX}-Approvals.md` exists on disk. If the file is absent, log an error to the process log:
+
+```
+[timestamp] ERROR: Cannot write registry — {PREFIX}-Approvals.md not found. Ensure the Findings Gate completed successfully.
+```
+
+Record the outcome for the Phase 6 summary: `Registry: docs/assessments/registry.md [ERROR — Approvals file not found]`. Skip all remaining registry write steps. Do not create or modify the registry file. The pipeline does not halt.
+
+If the file exists but does not contain the `## Interventions Flagged for Feature Delivery` section, log an error to the process log:
+
+```
+[timestamp] Phase 6: registry write skipped — {PREFIX}-Approvals.md missing required section 'Interventions Flagged for Feature Delivery'
+```
+
+Record the outcome for the Phase 6 summary: `Registry: docs/assessments/registry.md [ERROR — Approvals file missing required section]`. Skip all remaining registry write steps. Do not create or modify the registry file. The pipeline does not halt.
+
+**Step 2 — Extract severity counts from Interventions Index (US-01-T01).** Using the data contract defined in the "Data Contract: Interventions Index" subsection above, parse `docs/assessments/{PREFIX}/{PREFIX}-Interventions-Index.md` and apply the counting algorithm:
+
+1. Locate the main interventions table
+2. Count rows where `Criticality = "CRITICAL"` → `critical_count`
+3. Count rows where `Criticality = "HIGH"` → `high_count`
+4. Count rows where `Criticality = "MEDIUM"` → `medium_count`
+5. Count rows where `Criticality = "LOW"` → `low_count`
+6. Compute `total_count = critical_count + high_count + medium_count + low_count`
+
+Apply the error handling rules defined in the data contract for all failure conditions (missing file, absent Criticality column, unrecognised values). Severity count failures are non-fatal; all counts default to 0.
+
+Log to process log on success:
+
+```
+[timestamp] Phase 6: extracted severity counts from {PREFIX}-Interventions-Index.md
+  CRITICAL: N, HIGH: N, MEDIUM: N, LOW: N, Total: N
+```
+
+**Step 3 — Extract flagged count from Approvals file (US-01-T02).** Using the data contract defined in the "Data Contract: Approvals File" subsection above, parse `docs/assessments/{PREFIX}/{PREFIX}-Approvals.md` and apply the counting algorithm:
+
+1. Locate the `## Interventions Flagged for Feature Delivery` section
+2. Parse the Markdown table in that section
+3. Count rows where `Flagged = "Yes"` (case-sensitive) → `flagged_count`
+4. If the table is present but empty, set `flagged_count = 0` — this is not an error
+
+Apply the error handling rules defined in the data contract. Approvals file contract violations are fatal to the registry write; if any fatal error condition is met, log the error, skip the remaining registry write steps, and report the error in the Phase 6 summary.
+
+Log to process log on success:
+
+```
+[timestamp] Phase 6: extracted flagged count from {PREFIX}-Approvals.md
+  Flagged for feature delivery: N
+```
+
+**Step 4 — Build registry row (US-01-T03).** Capture the current system date in YYYY-MM-DD format. Construct the Markdown table row:
+
+```
+| {YYYY-MM-DD} | [{PREFIX}]({PREFIX}/) | {total_count} | {critical_count} | {high_count} | {medium_count} | {low_count} | {flagged_count} |
+```
+
+The row must have exactly eight pipe-delimited columns. Numeric values for Total, CRITICAL, HIGH, MEDIUM, LOW, and Flagged must be non-negative integers with no decimal places. The Prefix column must use the relative Markdown link format `[{PREFIX}]({PREFIX}/)`.
+
+**Step 5 — Detect whether registry exists (US-02-T01).** Check for the presence of `docs/assessments/registry.md` in the assessed project directory. If the file system check raises an error (e.g., permission denied), log:
+
+```
+[timestamp] ERROR: Phase 6 — registry existence check failed: {error message}
+```
+
+Record the outcome for the Phase 6 summary as an error and skip the remaining write steps. The pipeline does not halt.
+
+**Step 6 — Create registry on first run (US-01-T04).** If `docs/assessments/registry.md` does not exist, create it with the following content (replacing `{row}` with the constructed row from Step 4):
+
+```markdown
+# Assessment Registry
+
+| Date | Prefix | Total | CRITICAL | HIGH | MEDIUM | LOW | Flagged |
+|------|--------|-------|----------|------|--------|-----|---------|
+{row}
+```
+
+If the write operation itself raises an I/O error (e.g., permission denied, disk full), log:
+
+```
+[timestamp] ERROR: Registry write failed — I/O error during file creation: docs/assessments/registry.md — {error message}
+```
+
+Record for the Phase 6 summary: `Registry: docs/assessments/registry.md [ERROR — I/O error during creation]`. Skip remaining steps. The pipeline does not halt.
+
+After a successful write, verify the file exists and is non-empty by reading it back. If verification fails, log:
+
+```
+[timestamp] ERROR: Registry write failed — file not readable after creation: docs/assessments/registry.md
+```
+
+Record for the Phase 6 summary: `Registry: docs/assessments/registry.md [ERROR — write verification failed]`. The pipeline does not halt.
+
+On success, log to process log (US-01-T05):
+
+```
+[timestamp] Phase 6: created registry.md with first row
+  Location: docs/assessments/registry.md
+  Row: | {date} | [{PREFIX}]({PREFIX}/) | {total} | {critical} | {high} | {medium} | {low} | {flagged} |
+```
+
+Record for the Phase 6 summary: `Registry: docs/assessments/registry.md [created]`.
+
+**Step 7 — Append row on subsequent runs (US-02-T02, US-02-T03).** If `docs/assessments/registry.md` already exists:
+
+1. Read the full file content (UTF-8). If the read fails (e.g., permission denied), log:
+
+   ```
+   [timestamp] ERROR: Registry append failed — cannot read existing file: docs/assessments/registry.md — {error message}
+   ```
+
+   Record for the Phase 6 summary: `Registry: docs/assessments/registry.md [ERROR — read failure; existing file unchanged]`. Skip to Step 8. The pipeline does not halt.
+
+2. Strip all trailing whitespace from the content
+3. Append a newline, the new row from Step 4, and a final trailing newline
+4. Write the assembled content back to the file as a full overwrite
+
+The write is atomic — either the complete updated content is written or the original file is left unchanged. Do not validate, repair, or modify any existing rows during this operation.
+
+If the write operation itself raises an I/O error (e.g., permission denied, disk full), log:
+
+```
+[timestamp] ERROR: Registry append failed — I/O error during write: docs/assessments/registry.md — {error message}
+```
+
+Record for the Phase 6 summary: `Registry: docs/assessments/registry.md [ERROR — I/O error during append]`. Skip remaining steps. The pipeline does not halt.
+
+After a successful write, verify the file exists and is non-empty by reading it back. If verification fails, log:
+
+```
+[timestamp] ERROR: Registry append failed — write verification failed: docs/assessments/registry.md
+```
+
+On success, count the data rows in the file after writing (all rows excluding the title line, the table header row, and the separator row) to determine the new row position N. Log to process log (US-02-T04):
+
+```
+[timestamp] Phase 6: appended row to registry.md
+  Location: docs/assessments/registry.md
+  Row: | {date} | [{PREFIX}]({PREFIX}/) | {total} | {critical} | {high} | {medium} | {low} | {flagged} |
+```
+
+Record for the Phase 6 summary: `Registry: docs/assessments/registry.md [updated — row N appended]`.
+
+**Step 8 — Phase 6 summary update (US-01-T06, US-02-T05).** After the registry write completes (regardless of outcome), include a registry confirmation line in the Phase 6 Report block between the `Approvals:` and `Effort Estimate:` entries. Select the line based on outcome:
+
+| Outcome | Summary line |
+|---------|-------------|
+| Registry created (first run) | `Registry:            docs/assessments/registry.md [created]` |
+| Registry updated (append) | `Registry:            docs/assessments/registry.md [updated — row N appended]` |
+| Write skipped or error | `Registry:            docs/assessments/registry.md [ERROR — {reason}]` |
+
+Log to process log:
+
+```
+[timestamp] Phase 6 end: registry write complete
+```
+
+---
+
 Report:
 
 ```
@@ -390,10 +645,11 @@ Assessment:
 Findings:      N CRITICAL | N HIGH | N MEDIUM | N LOW
 Interventions: N proposed | N flagged for feature delivery
 ─────────────────────────────────────────────────────
-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
+Approvals:           {PREFIX}-Approvals.md
+Registry:            docs/assessments/registry.md [created | updated — row N appended | ERROR — {reason}]
+Effort Estimate:     {PREFIX}-Effort-Estimate.md
+Token Estimate:      {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.

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

@@ -75,7 +75,7 @@ feature.md
 Planning rules:
 1. Skip agents whose output is fresh — unless `--force`
 2. Order by dependency — no agent starts until its inputs are fresh
-3. Parallelize independent agents — use `run_in_background: true`
+3. Parallelize independent agents — invoke multiple Agent tool calls in the same response (do NOT use `run_in_background: true` — background completion notifications are not delivered to sub-agent contexts)
 4. Re-run downstream agents when an upstream agent ran
 
 ### 2c. Show plan to user before executing
@@ -176,7 +176,7 @@ Read `{PREFIX}-Work-Breakdown.md` Section 4 to extract: phase order, tasks per p
 ### 6d. Execution loop (per phase)
 1. Identify ready tasks (all dependencies completed)
 2. Group by domain — batch independent tasks to the same agent
-3. Dispatch in parallel (`run_in_background: true`) where no inter-dependency
+3. Dispatch in parallel by invoking multiple Agent tool calls in the same response where no inter-dependency — do NOT use `run_in_background: true` from within a sub-agent context
 4. Wait for all agents in phase
 5. When ALL tasks of a User Story are done → trigger US review
 6. Proceed to next phase only when current phase is fully complete and all completed US reviews have passed
@@ -300,7 +300,7 @@ To add a new agent: create `.claude/agents/my-agent.md` with a clear `descriptio
 - **PR targets `develop`** — never push directly; do NOT auto-merge
 - **Plan before executing** — always show the plan first
 - **Never re-run fresh agents** unless `--force`
-- **Parallelize where possible** — independent agents run concurrently
+- **Parallelize where possible** — invoke multiple Agent tool calls in the same response for independent agents; never use `run_in_background: true` from within a sub-agent (background notifications are not delivered to sub-agent contexts)
 - **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

package/.claude/commands/check-interventions.md

@@ -0,0 +1,152 @@
+---
+description: "Check Interventions — full reconciliation view of all interventions from an assessment run: document presence, Approvals/Index consistency, and feature-actioning status. Usage: /check-interventions [prefix]"
+argument-hint: "[assessment-prefix]"
+allowed-tools: Read, Glob, Grep
+---
+
+Produce a full reconciliation table for all interventions from a completed assessment run.
+
+## Step 1 — Resolve prefix
+
+If `$ARGUMENTS` is empty:
+- Glob `docs/assessments/ASSESS-*/` to list available assessment folders.
+- Output the list and say: "Please specify a prefix from the list above (e.g. `/check-interventions ASSESS-001`)."
+- STOP.
+
+Otherwise:
+- If the argument is digits-only (e.g. `001`), prepend `ASSESS-` to form `ASSESS-001`.
+- Strip any trailing slash.
+- Use this as `{PREFIX}` for all subsequent steps.
+
+## Step 2 — Check assessment directory
+
+If `docs/assessments/{PREFIX}/` does not exist:
+```
+❌ Assessment directory not found: docs/assessments/{PREFIX}/
+   Run /assess-codebase to start a new assessment.
+```
+STOP.
+
+## Step 3 — Read Approvals file
+
+File path: `docs/assessments/{PREFIX}/{PREFIX}-Approvals.md`
+
+If the file does not exist:
+```
+❌ Approvals file not found: docs/assessments/{PREFIX}/{PREFIX}-Approvals.md
+   The assessment pipeline's Findings Gate must complete before this command can run.
+```
+STOP.
+
+Read the file. If it does NOT contain `## Interventions Flagged for Feature Delivery`:
+```
+❌ This Approvals file uses a pre-FTR-003 format (missing "Interventions Flagged for Feature Delivery" section).
+   This command requires the FTR-003 format produced by assessment-manager Phase 5.
+```
+STOP.
+
+Parse the Markdown table under `## Interventions Flagged for Feature Delivery`. Extract all rows (both `Yes` and `No`). Record:
+- `INT-NNN` identifier (normalise by stripping leading zeros for matching)
+- `Flagged` value (`Yes`, `No`, or malformed if any other value)
+- Full `Intervention` column value (e.g. `INT-001 — sql-injection-hardening`) to extract the slug — the slug is the part after ` — `
+
+## Step 4 — Read Interventions Index
+
+File path: `docs/assessments/{PREFIX}/{PREFIX}-Interventions-Index.md`
+
+If the file does not exist:
+- Set `index_available = false`
+- Note: Title, Criticality, and cross-file consistency checks will be skipped or shown as `—`.
+
+If the file exists:
+- Set `index_available = true`
+- Parse the Markdown table: extract columns `ID`, `Title`, `Criticality` for each row.
+
+## Step 5 — Build unified intervention list
+
+Collect all INT-NNN identifiers from:
+1. The Approvals file (all rows)
+2. The Interventions Index (all rows, if available)
+
+Union both sets (deduplicated). This is the full list to reconcile.
+
+For each entry, retain the **original padded identifier** from the source file (e.g., `INT-001`) as the canonical form — this is what is used in file-system glob operations. Stripping leading zeros is applied **only when comparing two identifiers from different sources** to determine whether they refer to the same intervention (e.g., `INT-001` and `INT-1` are treated as equal for deduplication only).
+
+## Step 6 — For each intervention, collect data
+
+For each INT-NNN in the unified list:
+
+**a. Doc file status:**
+- Glob `docs/assessments/{PREFIX}/{PREFIX}-{INT-NNN}-*.md`
+- If one or more files found: `✅ present`
+- If no files found: `❌ missing`
+
+**b. In Approvals:**
+- `Yes` if INT-NNN is in the Approvals table, `No` otherwise
+
+**c. Flagged value:**
+- From Approvals table: `Yes`, `No`, or `⚠️ malformed ({value})` if not exactly `Yes`/`No`
+- If INT-NNN not in Approvals: `n/a`
+
+**d. In Interventions Index:**
+- `Yes` if INT-NNN is in the Index, `No` otherwise (or `—` if index unavailable)
+
+**e. Title and Criticality:**
+- From Interventions Index if available; else `—`
+
+**f. Actioned status (only for interventions where Flagged = Yes):**
+- Glob `internal_docs/features/FTR-*/` and `docs/features/FTR-*/`
+- For each feature folder, apply the two-step heuristic:
+  1. **Slug match:** folder name contains the INT-NNN slug (case-insensitive substring)
+  2. **Body match (fallback):** read `feature.md`; body contains the INT-NNN identifier string (case-insensitive)
+- If a match is found: `✅ actioned → {matched-folder}`
+- If no match: `⏳ pending`
+- If Flagged is not `Yes`: `n/a`
+
+## Step 7 — Render reconciliation table
+
+```
+📊 Intervention Reconciliation — {PREFIX}
+════════════════════════════════════════════════════════════════
+
+| INT-NNN | Title          | Criticality | Flagged | Doc file    | Actioned         |
+|---------|----------------|-------------|---------|-------------|------------------|
+| INT-001 | {title}        | CRITICAL    | Yes     | ✅ present  | ✅ actioned → FTR-010-... |
+| INT-002 | {title}        | HIGH        | Yes     | ✅ present  | ⏳ pending       |
+| INT-003 | {title}        | MEDIUM      | No      | ❌ missing  | n/a              |
+| INT-004 | {title}        | LOW         | No      | ✅ present  | n/a              |
+
+Total: {N} interventions | {K} flagged | {A} actioned | {P} pending
+```
+
+If `index_available = false`, note above the table:
+```
+⚠️ Interventions Index not found — Title and Criticality columns not available.
+```
+
+## Step 8 — Render inconsistency list
+
+Collect all inconsistencies:
+
+- For each INT-NNN in Approvals that is NOT in the Interventions Index (when index available):
+  `INT-NNN: present in Approvals but not in Interventions Index`
+- For each INT-NNN in Interventions Index that is NOT in Approvals (when index available):
+  `INT-NNN: present in Interventions Index but missing from Approvals`
+- For each row in Approvals where `Flagged` is not exactly `Yes` or `No`:
+  `INT-NNN: malformed Flagged value '{value}' (expected 'Yes' or 'No')`
+
+If no inconsistencies:
+```
+────────────────────────────────────────
+✅ No inconsistencies found.
+════════════════════════════════════════════════════════════════
+```
+
+If inconsistencies exist:
+```
+────────────────────────────────────────
+⚠️ Inconsistencies ({N}):
+  • INT-NNN: present in Approvals but not in Interventions Index
+  • INT-NNN: malformed Flagged value 'Approved' (expected 'Yes' or 'No')
+════════════════════════════════════════════════════════════════
+```

package/.claude/commands/next-intervention.md

@@ -0,0 +1,113 @@
+---
+description: "Next Intervention — finds the next un-actioned flagged intervention from an assessment run and suggests the /define-feature invocation to start on it. Usage: /next-intervention [prefix]"
+argument-hint: "[assessment-prefix]"
+allowed-tools: Read, Glob, Grep
+---
+
+Find the next un-actioned flagged intervention from a completed assessment run.
+
+## Step 1 — Resolve prefix
+
+If `$ARGUMENTS` is empty:
+- Glob `docs/assessments/ASSESS-*/` to list available assessment folders.
+- Output the list and say: "Please specify a prefix from the list above (e.g. `/next-intervention ASSESS-001`)."
+- STOP.
+
+Otherwise:
+- If the argument is digits-only (e.g. `001`), prepend `ASSESS-` to form `ASSESS-001`.
+- Strip any trailing slash.
+- Use this as `{PREFIX}` for all subsequent steps.
+
+## Step 2 — Check assessment directory
+
+If `docs/assessments/{PREFIX}/` does not exist:
+```
+❌ Assessment directory not found: docs/assessments/{PREFIX}/
+   Run /assess-codebase to start a new assessment.
+```
+STOP.
+
+## Step 3 — Read Approvals file
+
+File path: `docs/assessments/{PREFIX}/{PREFIX}-Approvals.md`
+
+If the file does not exist:
+```
+❌ Approvals file not found: docs/assessments/{PREFIX}/{PREFIX}-Approvals.md
+   The assessment pipeline's Findings Gate must complete before this command can run.
+```
+STOP.
+
+Read the file. If it does NOT contain the section heading `## Interventions Flagged for Feature Delivery`:
+```
+❌ This Approvals file uses a pre-FTR-003 format (missing "Interventions Flagged for Feature Delivery" section).
+   This command requires the FTR-003 format produced by assessment-manager Phase 5.
+```
+STOP.
+
+## Step 4 — Extract flagged interventions
+
+Parse the Markdown table under `## Interventions Flagged for Feature Delivery`.
+- Extract all rows where the `Flagged` column value is exactly `Yes` (case-sensitive).
+- Preserve document order (top-to-bottom).
+
+If no rows are flagged:
+```
+ℹ️ No interventions were flagged for feature delivery in this assessment.
+```
+STOP.
+
+## Step 5 — Check for matching feature folders
+
+Glob both:
+- `internal_docs/features/FTR-*/`
+- `docs/features/FTR-*/`
+
+For each flagged intervention, determine whether it is "actioned" using this two-step heuristic (attempt slug match first, then body match as fallback):
+
+1. **Slug match:** Does any feature folder name contain the INT-NNN slug from the `Intervention` column (case-insensitive substring)?
+   - The `Intervention` column format is `INT-NNN — {slug}` (e.g. `INT-001 — sql-injection-hardening`). The slug is the part after ` — `.
+2. **Body match (fallback):** For any folder that did NOT match by slug, read its `feature.md` and check whether the INT-NNN identifier string (e.g. `INT-001`) appears anywhere in the body (case-insensitive).
+
+An intervention is "actioned" if either check returns true for at least one feature folder.
+
+Normalise INT-NNN identifiers by stripping leading zeros before comparison (e.g. `INT-001` and `INT-1` are the same).
+
+## Step 6 — Find the first un-actioned intervention
+
+Scan the flagged interventions in document order and find the first one that is NOT actioned.
+
+If all flagged interventions are actioned:
+```
+✅ All flagged interventions have been actioned. ({N} of {N} flagged)
+
+Actioned interventions:
+  • INT-001 — {slug} → {matched-feature-folder}
+  • INT-002 — {slug} → {matched-feature-folder}
+  ...
+```
+STOP.
+
+## Step 7 — Output the next un-actioned intervention
+
+Construct the document path:
+```
+docs/assessments/{PREFIX}/{PREFIX}-{INT-NNN}-{slug}.md
+```
+(Glob `docs/assessments/{PREFIX}/{PREFIX}-{INT-NNN}-*.md` to find the actual filename if the slug in the path differs from the Approvals column.)
+
+Output:
+
+```
+🔖 Next un-actioned intervention: {INT-NNN} — {slug}
+
+   Document path:    docs/assessments/{PREFIX}/{PREFIX}-{INT-NNN}-{slug}.md
+   Suggested command: /define-feature docs/assessments/{PREFIX}/{PREFIX}-{INT-NNN}-{slug}.md
+```
+
+If some interventions were already actioned, append:
+```
+Previously actioned ({K} of {N} flagged):
+  • INT-001 — {slug} → {matched-feature-folder}
+  ...
+```

package/CHANGELOG.md

@@ -1,4 +1,81 @@
-## 0.1.6 (2026-07-16)
-## 0.1.5 (2026-07-14)
-## 0.1.4 (2026-07-14)
+## 0.1.4 (2026-07-21)
+## 0.1.7 (2026-07-23)
+
+
+### Features
+
+* add effort estimation and actuals tracking to project manager workflow ([0b81915](https://github.com/dtlab-tech/ai-toolkit/commit/0b819154584c725ccca09a825888aee8f3f5f34f))
+* add effort estimation and actuals tracking to project manager workflow ([f9e74ef](https://github.com/dtlab-tech/ai-toolkit/commit/f9e74ef39972e3f0f3b0d3b6e4311d15fa9035cc))
+* add GitHub Actions workflow to auto-publish to npm on merge to main ([f8d89ea](https://github.com/dtlab-tech/ai-toolkit/commit/f8d89ea20364796ce699b8228041f7f436ff3bdd))
+* add GitHub Actions workflow to auto-publish to npm on merge to main ([abe2c45](https://github.com/dtlab-tech/ai-toolkit/commit/abe2c45336586794267d4ac7faf164cb82758fb6))
+* add option to install Matt Pocock's skills during toolkit installation ([441183d](https://github.com/dtlab-tech/ai-toolkit/commit/441183d30214ed6eb570ae41ddf858229276b6d5))
+* add option to install Matt Pocock's skills during toolkit installation ([f0d4fa3](https://github.com/dtlab-tech/ai-toolkit/commit/f0d4fa3ff783498d77e5b399d22d5828c8b157a6))
+* add pricing documentation for cost estimation and blended cost formula ([91f6392](https://github.com/dtlab-tech/ai-toolkit/commit/91f63926ef2eabd20ad09a186f323d00abba9963))
+* add pricing documentation for cost estimation and blended cost formula ([a9361ed](https://github.com/dtlab-tech/ai-toolkit/commit/a9361eda75b2c36d2515df976782af67bba1c4e4))
+* Add SWF AI Toolkit with agents, skills, commands, and procedures for software feature delivery ([327a282](https://github.com/dtlab-tech/ai-toolkit/commit/327a2826bf4a147bcf2f993bc3ea254eaa12b18b))
+* Add SWF AI Toolkit with agents, skills, commands, and procedures for software feature delivery ([97eb589](https://github.com/dtlab-tech/ai-toolkit/commit/97eb589a2b63a9ea45634c71aaae07d08bc1deaf))
+* add version check during toolkit installation and update installed version file ([0e0eeea](https://github.com/dtlab-tech/ai-toolkit/commit/0e0eeea1bafe78e4d5c4214efc1b7acab9799ac8))
+* add version check during toolkit installation and update installed version file ([4681ed4](https://github.com/dtlab-tech/ai-toolkit/commit/4681ed445a83c7f3bee5677bb773deaa7b0f86e2))
+* assessment pipeline enhancements — token/effort estimation, registry, intervention commands, and Gaia assistant ([0cb512c](https://github.com/dtlab-tech/ai-toolkit/commit/0cb512cfd6d18c38216584ca454ab2077e641762))
+* auto-generate CHANGELOG.md on publish via conventional-changelog ([6fdbd69](https://github.com/dtlab-tech/ai-toolkit/commit/6fdbd69c011ad3d568f3070f4c2dcd87092623e9))
+* auto-generate CHANGELOG.md on publish via conventional-changelog ([49df865](https://github.com/dtlab-tech/ai-toolkit/commit/49df865633ebcede49f6c879921e775f1945271b))
+* Enhance agent descriptions and add completion summaries ([a3aa811](https://github.com/dtlab-tech/ai-toolkit/commit/a3aa81169f102a09c95a46a98aa3b4f82bbb3b31))
+* Enhance agent descriptions and add completion summaries ([1b2fe4a](https://github.com/dtlab-tech/ai-toolkit/commit/1b2fe4a2bf1c52107c8605533f2a0cdd85d1afbf))
+* enhance file installation process with detailed status reporting and user prompts ([c12ca72](https://github.com/dtlab-tech/ai-toolkit/commit/c12ca72e111ead2f3c53b8846507f61fb572125b))
+* enhance file installation process with detailed status reporting and user prompts ([10b56a4](https://github.com/dtlab-tech/ai-toolkit/commit/10b56a4d10455366cfec0690b8e9e428399f845a))
+* enhance installation process with version checks and optional Matt Pocock skills installation ([16411e7](https://github.com/dtlab-tech/ai-toolkit/commit/16411e755c6586e8d33bd13b62402b3648e05b9c))
+* enhance installation process with version checks and optional Matt Pocock skills installation ([8c1f0ae](https://github.com/dtlab-tech/ai-toolkit/commit/8c1f0ae92828e27b8a7ffb110eb35e27094b7006))
+* enhance project manager with feature registry checks for cross-feature analysis ([30eb5e5](https://github.com/dtlab-tech/ai-toolkit/commit/30eb5e50fc16501e9cc38a5b4a8264e3eac96e5d))
+* enhance project manager with feature registry checks for cross-feature analysis ([0d44ec3](https://github.com/dtlab-tech/ai-toolkit/commit/0d44ec35caa0460203c7c55d7eacff9320ef681f))
+* enhance SWF AI Toolkit guide with detailed introduction and context awareness ([60bb2b8](https://github.com/dtlab-tech/ai-toolkit/commit/60bb2b86f3915f9844b58e7eeb44e88ce3877a4c))
+* enhance SWF AI Toolkit guide with detailed introduction and context awareness ([f4ca293](https://github.com/dtlab-tech/ai-toolkit/commit/f4ca2938f6b4103785274018376ac2997e28cfc2))
+* enhance token tracking and reporting in project manager and implement feature workflow ([fa873b8](https://github.com/dtlab-tech/ai-toolkit/commit/fa873b82b84bd3b332b44c0e2dd458820defd502))
+* enhance token tracking and reporting in project manager and implement feature workflow ([92336ed](https://github.com/dtlab-tech/ai-toolkit/commit/92336edb3b523a5f5ed40d21b6fe38f7024ba322))
+* **FTR-001:** add token estimation to assessment pipeline ([2f8a630](https://github.com/dtlab-tech/ai-toolkit/commit/2f8a63077e79c09ac25b2d60c74946fc7d229282))
+* **FTR-001:** add token estimation to assessment pipeline ([93879ad](https://github.com/dtlab-tech/ai-toolkit/commit/93879ad00c60e9985424f07c104fa332883a4921))
+* **FTR-002:** Add assessment pipeline effort estimation documentation and process log ([873c28f](https://github.com/dtlab-tech/ai-toolkit/commit/873c28f925a820292a1dc68600b1ebf991336903))
+* **FTR-002:** Add assessment pipeline effort estimation documentation and process log ([30c891b](https://github.com/dtlab-tech/ai-toolkit/commit/30c891be8e337c63064982413570c1c4ade4d08f))
+* **FTR-003:** reduce assessment pipeline to read-only — findings gate replaces remediation gate ([681f6fc](https://github.com/dtlab-tech/ai-toolkit/commit/681f6fc6500514c21f03ae61ee82e788ff65a6c6))
+* **FTR-003:** reduce assessment pipeline to read-only — findings gate replaces remediation gate ([918ca26](https://github.com/dtlab-tech/ai-toolkit/commit/918ca2608e25d0ee2aa91b9047d921b7eaa5c021))
+* **FTR-004:** generate requirements, tech-spec, validation, and work breakdown docs ([5ba2da7](https://github.com/dtlab-tech/ai-toolkit/commit/5ba2da7bee2e7bde5136874f277f19ad83be8464))
+* **FTR-004:** implement INFRA + US-01 through US-03 — assessment registry write logic ([1989e38](https://github.com/dtlab-tech/ai-toolkit/commit/1989e38fc1b0ef5b40ff2e54cc83a2cd49e5c5d3))
+* **FTR-004:** implement US-04 through US-06 — test specification ([baad095](https://github.com/dtlab-tech/ai-toolkit/commit/baad09524d8c352330a024fc7a80e89c635c0fc8))
+* **FTR-004:** update project-manager token estimates to complete status ([959cc99](https://github.com/dtlab-tech/ai-toolkit/commit/959cc9921d470bfa874c5108f320848718d97c9a))
+* **FTR-005:** add /next-intervention and /check-interventions commands ([f744ad2](https://github.com/dtlab-tech/ai-toolkit/commit/f744ad2032abe936feff9ae67ddd863ba86511a1))
+* **FTR-006:** add assessment-aware PR description command to enhance context for intervention branches ([3023729](https://github.com/dtlab-tech/ai-toolkit/commit/302372919a2c07de313175c61f51000fcb2c99bc))
+* refactor Matt Pocock skills installation checks and simplify version handling ([58d3efd](https://github.com/dtlab-tech/ai-toolkit/commit/58d3efddf35b453cf25de701ed5f4b829d0a1a34))
+* refactor Matt Pocock skills installation checks and simplify version handling ([7de059e](https://github.com/dtlab-tech/ai-toolkit/commit/7de059e01fe5d71b75331732a833e00acfbb2a98))
+* rename help skill to hi-gaia and introduce Gaia as toolkit assistant ([4c7c6f4](https://github.com/dtlab-tech/ai-toolkit/commit/4c7c6f422c8f97b9e79361faed4c95ed5001322c))
+* rename help skill to hi-gaia and introduce Gaia as toolkit assistant ([c45fef0](https://github.com/dtlab-tech/ai-toolkit/commit/c45fef09a475dc795dfbbc12485e1ea01f4776d4))
+* update Azure pipeline to dynamically resolve NPM registry URL ([2c6a817](https://github.com/dtlab-tech/ai-toolkit/commit/2c6a81777475f9ed6ad3f9f4b42fe7e7b2ada67e))
+* update Azure pipeline to dynamically resolve NPM registry URL ([0f4601f](https://github.com/dtlab-tech/ai-toolkit/commit/0f4601fabb4b885dadc28e3f868feacdb97e474b))
+* update Matt Pocock skills check to verify 'grilling' skill presence ([47b0592](https://github.com/dtlab-tech/ai-toolkit/commit/47b0592be0438c2d5152030e95674f0d0c23bf9a))
+* update Matt Pocock skills check to verify 'grilling' skill presence ([d92d729](https://github.com/dtlab-tech/ai-toolkit/commit/d92d72946920c1cd9bf29f470a7a95b7bd84a254))
+* update package name and installation instructions to reflect new organization ([b67193a](https://github.com/dtlab-tech/ai-toolkit/commit/b67193a630e3bb95cc5b58e4ead1b914cc74b9dc))
+* update package name and installation instructions to reflect new organization ([0b09994](https://github.com/dtlab-tech/ai-toolkit/commit/0b09994220a563f1d3d12e5286be4a884af34aab))
+
+
+### Bug Fixes
+
+* add git tag on publish so conventional-changelog can read commit range ([6d4e427](https://github.com/dtlab-tech/ai-toolkit/commit/6d4e427d068da80d607db6e356cc79ea6e6ded9d))
+* add git tag on publish so conventional-changelog can read commit range ([114f558](https://github.com/dtlab-tech/ai-toolkit/commit/114f55871c8e5892b36754cad3ba5d88b082706a))
+* correct shell syntax in version bump commit message ([f988609](https://github.com/dtlab-tech/ai-toolkit/commit/f98860994d1cd3c4ef3d9b86aade6155e0ec6408))
+* correct shell syntax in version bump commit message ([8e25e16](https://github.com/dtlab-tech/ai-toolkit/commit/8e25e160496125387e4a69707b04c24739008c5c))
+* enhance NPM registry resolution by adding ADO_FEED_SCOPE variable ([2ff13e4](https://github.com/dtlab-tech/ai-toolkit/commit/2ff13e44510f507453136b5840d9dfc5c2afc3c5))
+* enhance NPM registry resolution by adding ADO_FEED_SCOPE variable ([77b79c6](https://github.com/dtlab-tech/ai-toolkit/commit/77b79c6f1836b71bf96e1b7457d1c1ca28324253))
+* **FTR-005:** address review warnings + add gate protocol to CLAUDE.md ([2e64780](https://github.com/dtlab-tech/ai-toolkit/commit/2e647809ba5279c492060dde52ab8134490fc59d))
+* pull --rebase before pushing version bump to avoid rejection ([cf751d0](https://github.com/dtlab-tech/ai-toolkit/commit/cf751d0984bdddc683dfc67e378b4f563c6cfbe2))
+* pull --rebase before pushing version bump to avoid rejection ([b70c748](https://github.com/dtlab-tech/ai-toolkit/commit/b70c74832f48e9261fbe894542de5977c3bcafa4))
+* remove project-specific references and fix stale artifact filenames ([c272354](https://github.com/dtlab-tech/ai-toolkit/commit/c2723549f1a3de4f099b85b44c87603b9c601e72))
+* remove project-specific references and fix stale artifact filenames ([1861fb9](https://github.com/dtlab-tech/ai-toolkit/commit/1861fb98708ce8ff8fcae7f5947f4e9dc9ba6937))
+* remove run_in_background from PM and assessment-manager — background notifications not delivered to sub-agent contexts ([29a7b97](https://github.com/dtlab-tech/ai-toolkit/commit/29a7b97649ad5798eaf96c5a1acabb214c0c0c96))
+* update installation instructions in README for clarity and completeness ([293a2dd](https://github.com/dtlab-tech/ai-toolkit/commit/293a2ddf0bebd386ba799ee24f6465b317897495))
+* update installation instructions in README for clarity and completeness ([d682026](https://github.com/dtlab-tech/ai-toolkit/commit/d6820268dc1a60d99e80162e262adaba2974f9f7))
+* update package references from [@denistomada](https://github.com/denistomada) to [@fincantieri](https://github.com/fincantieri) in README and installation documentation ([32ad6ae](https://github.com/dtlab-tech/ai-toolkit/commit/32ad6ae24db1719ad3cb1f4eea02bc11494cacd6))
+* update package references from [@denistomada](https://github.com/denistomada) to [@fincantieri](https://github.com/fincantieri) in README and installation documentation ([5854119](https://github.com/dtlab-tech/ai-toolkit/commit/585411991604acc06a85ecf5b8a9beffe1ef82a2))
+* update package.json to correct author and package name ([53dae47](https://github.com/dtlab-tech/ai-toolkit/commit/53dae47132da53e4fce98fdd683eb7acb4678b5a))
+* update package.json to correct author and package name ([81a6b7c](https://github.com/dtlab-tech/ai-toolkit/commit/81a6b7c1ebfe6fab632eb44ddc48c962efc69997))
+* update repository URL in package.json and remove publishConfig ([7f3dc15](https://github.com/dtlab-tech/ai-toolkit/commit/7f3dc15df57653bed00b139123396d5d2ba24d3e))
+* update repository URL in package.json and remove publishConfig ([b912958](https://github.com/dtlab-tech/ai-toolkit/commit/b9129582804758128f3e9dffdd8cd9302d4e529f))
+
 ## 0.1.3 (2026-07-14)

package/CLAUDE.md

@@ -51,6 +51,38 @@ An `AGENTS.md` file in the project root with:
 
 Generic procedures live in `docs/procedures/` in this toolkit. Projects can override any procedure by placing a file with the same name at `docs/procedures/` in their own root. Agents check the project first, then fall back to the toolkit.
 
+## Gate Protocol — MANDATORY RULES
+
+These rules apply in every session, without exception.
+
+### Launching the Project Manager
+
+**Always pass `run_in_background: false` when spawning the `project-manager` agent.**
+
+Running the PM in the background leaves the main loop free to act independently. This creates two parallel execution paths that will conflict. The PM must block the main loop until it reaches a gate and returns.
+
+### While the PM is running
+
+**Do nothing.** No file reads "to prepare", no file writes "to accelerate", no implementation "because it seems stuck". The only permitted actions are:
+
+- Receiving gate notifications and presenting them to the user
+- Responding to the user's status questions ("still running")
+- Sending messages to the PM via SendMessage if it is genuinely blocked and the user asks to unblock it
+
+If the PM produces relay agents that appear to do nothing useful, that is noise — not a signal that the PM is stuck. Wait.
+
+### Gate notifications are hard stops
+
+When any gate notification arrives (Gate 1, Gate 2, Findings Gate, or any **HARD STOP** in any agent output):
+
+1. Stop immediately — even if mid-turn
+2. Present the full gate content to the user
+3. Wait for explicit written approval before touching any file or spawning any agent
+
+This applies even if the PM appears stuck, in a relay loop, or the gate arrives while another tool call is in progress.
+
+---
+
 ## Skills (user-invocable, in `.claude/skills/`)
 
 ### Feature Delivery
@@ -90,6 +122,8 @@ Generic procedures live in `docs/procedures/` in this toolkit. Projects can over
 | Command | Purpose |
 |---------|---------|
 | `/assessment-status <prefix>` | Reports presence/state of all assessment artifacts (assessments, interventions, approvals, issues register) |
+| `/next-intervention [prefix]` | Finds the next un-actioned flagged intervention and suggests the `/define-feature` invocation to start on it |
+| `/check-interventions [prefix]` | Full reconciliation table: every intervention cross-referenced against the Index, on-disk files, and existing feature folders |
 
 ## Agents (spawnable subagents, in `.claude/agents/`)
 

package/package.json

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