@dtlabs/ai-toolkit 0.1.5 → 0.1.7

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

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

package/docs/procedures/token-estimation.md

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

package/package.json

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

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

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