@dtlabs/ai-toolkit 0.1.5 → 0.1.7

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
 
@@ -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,8 +300,8 @@ 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
-- **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
+- **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
 - **Commit per US** — `feat({PREFIX}): implement US-XX — {title}`

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/.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,3 +1,81 @@
-## 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/`)
 
@@ -114,7 +148,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/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