pi-aia-asf 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-28
+
+### Added
+
+- **Delegation reference `references/06d-delegation.md`** — codifies the two
+  delegation mechanisms available to ASF work: **intercom** (message another
+  live pi session that owns relevant context — `list` first, say what you want
+  back, treat peer findings as evidence, not proof) and **subagents** (spawn an
+  isolated `pi -p` process when the OUTCOME matters more than the trace — scoped
+  codebase research, independent parallel fixes, fresh-perspective review).
+- **Two verified hard limits, backed by experiment** (both documented as
+  anti-patterns in SKILL.md):
+  - **Never run parallel subagents against the same file.** Tested: 4 concurrent
+    whole-file writers left only 1 of 4 edits, silently, all exiting 0 — the
+    no-mutual-dependencies rule is enforced by physics, not preference.
+  - **Exit code 0 does not mean success.** Tested: a subagent asked to read a
+    non-existent file exited 0. Always validate the returned output.
+- **`pi-intercom` as a declared dependency** (`dependencies` in package.json,
+  `^0.10.1`) — `npm install` pulls it in. Intentionally **not bundled**: a
+  bundled copy conflicts with a top-level `pi install npm:pi-intercom`
+  (tool-name collision, verified), so the tool must be installed top-level to
+  register. Added to the ASF runtime dependency check (`/asf` summary now lists
+  all five: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser,
+  pi-intercom).
+- **SKILL.md wiring** — Phase 6 delegation note, reference index entry, and
+  three new anti-patterns (same-file parallel subagents, trusting subagent exit
+  codes/self-reports, re-deriving context another live session already has).
+
+### Changed
+
+- README dependencies table now lists pi-intercom with the not-bundled rationale.
+
+## [0.3.0] - 2026-08-25
+
+### Added
+
+- **Mechanical spec-to-code traceability gate in `/asf verify`** (large work
+  only) — reads the shared spec-memory task and validates every `met` spec's
+  trace (`outcome → codePath → testFile + assertion`); `testFile` must exist
+  and `assertion` must appear in it. Outputs a traceability matrix with
+  PASS/FAIL rows and refuses delivery on FAIL (`GATE NOT PASSED`). Small work
+  keeps the checklist only — no mechanical gate (scale proportionality).
+- **New QA rules (06b-testing-qa.md)**: Rule 12 — test the operator-facing
+  outcome, not the machinery (Betamaxx dead-code failure); Rule 13 — nothing
+  is delivered until consumed by a surface (UI or API); Rule 14 — every
+  feature spec ships an E2E behavioral test through the real entry point.
+  Rule 9 extended for silent async paths; Rule 10 DoD extended (traceability,
+  consumed-by-surface, E2E).
+- **M4 — challenge approved designs during implementation** (06-implementation.md):
+  product tension → resolve with the user before implementing.
+- **M5 — the delivery log is a claim; the code is the evidence**: trace the
+  actual code path before marking anything delivered.
+- **M6 — external planning docs are specs, not ground truth** (01-intake.md +
+  SKILL.md Phase 1/3): locate IMPROVEMENT-PLAN.md / PLAN.md / requirements
+  docs / delivery logs / tickets, ingest every actionable item as a captured
+  spec; their ✅ markers are claims, not evidence.
+- **Adversarial traceability lens** (04-adversarial.md): operator-facing
+  outcome + code path + where dead wiring hides.
+- **PLAN.md traceability matrix** (05-plan.md): spec → outcome → code path →
+  test.
+- DoD checklist extended; anti-patterns added (delivery-log trust, machinery
+  without a surface, unit tests as wiring proof, external plan checkmarks,
+  literal implementation of tension-creating specs).
+
+### Changed
+
+- `/asf verify` output now shows scale and, for large work, the mechanical
+  traceability matrix before the DoD checklist.
+
+### Requires
+
+- pi-vigilant 0.1.3+ (provides the `trace` field on specs).
+
+
 ## [0.2.2] - 2026-08-14
 
 ### Added

package/README.md

@@ -41,6 +41,9 @@ You can also force/start a session explicitly:
 | **pi-smart-web-search** | `web_search` | `pi install npm:pi-smart-web-search` |
 | **pi-smart-fetch** | `web_fetch`, `batch_web_fetch` | `pi install npm:pi-smart-fetch` |
 | **pi-aia-browser** | `browser_init`, `browser_navigate`, … (Playwright + Chromium, auto-installed) | `pi install npm:pi-aia-browser` |
+| **pi-intercom** | `intercom` — message other live pi sessions directly (delegation, cross-session verification) | `pi install npm:pi-intercom` |
+
+`pi-intercom` is also declared in `dependencies` in `package.json`, so `npm install` of this package pulls it in. It is intentionally **not bundled** into the tarball: bundling it would conflict with a top-level `pi install npm:pi-intercom` (tool name collision), so the tool must be installed at top level to register.
 
 The extension warns at startup (and on `/asf` with no args) when any dependency is missing.
 

package/index.ts

@@ -13,7 +13,7 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
@@ -51,9 +51,29 @@ const QA_CHECKLIST: Array<{ key: string; label: string }> = [
   { key: "observable", label: "Observable end state verified as a user would experience it" },
   { key: "browser", label: "Web surfaces exercised through a real browser (n/a if none)" },
   { key: "specs", label: "Every MUST spec 'met' with concrete evidence" },
+  { key: "trace", label: "Spec-to-code traceability: every met spec has outcome → codePath → test" },
+  { key: "surface", label: "Every delivered feature is consumed by a surface (UI or API) — nothing dead" },
+  { key: "e2e", label: "Feature specs have an end-to-end behavioral test through the real entry point" },
   { key: "honest", label: "Skipped/inconclusive checks reported explicitly" },
 ];
 
+/** Spec-to-code traceability (M1) — mirrors pi-vigilant's Trace. */
+interface Trace {
+  outcome: string;
+  codePath: string;
+  testFile?: string;
+  assertion?: string;
+}
+
+interface SpecItem {
+  id: string;
+  requirement: string;
+  area: string;
+  priority: string;
+  status: string;
+  trace?: Trace;
+}
+
 interface ProjectStateFile {
   current: AsfState | null;
   history: Array<{ workType: string; phase: AsfPhase; startedAt: string; endedAt: string }>;
@@ -94,6 +114,61 @@ async function saveState(project: string, data: ProjectStateFile): Promise<void>
   await writeFile(file, JSON.stringify(data, null, 2), "utf-8");
 }
 
+// ─── Spec-memory read (shared with pi-vigilant) ────────────────────────────
+
+const SPEC_DIR = join(SKILLS_DIR, "spec-memory", "projects");
+
+function specTaskFileFor(project: string): string {
+  return join(SPEC_DIR, project, "current-task.json");
+}
+
+async function loadSpecs(project: string): Promise<SpecItem[] | null> {
+  const file = specTaskFileFor(project);
+  if (!existsSync(file)) return null;
+  try {
+    const task = JSON.parse(await readFile(file, "utf-8")) as {
+      areas?: Record<string, SpecItem[]>;
+    };
+    return Object.values(task.areas || {}).flat();
+  } catch {
+    return null;
+  }
+}
+
+/** Mechanical M1 validation of a met spec's trace. */
+function validateTrace(spec: SpecItem): { ok: boolean; reason: string } {
+  const t = spec.trace;
+  if (!t || !t.outcome || !t.codePath) {
+    return {
+      ok: false,
+      reason: "met but trace incomplete — outcome + codePath required (add via update_spec_status trace)",
+    };
+  }
+  if (t.testFile) {
+    const abs = join(process.cwd(), t.testFile);
+    if (!existsSync(abs)) {
+      return { ok: false, reason: `testFile not found: ${t.testFile}` };
+    }
+    if (t.assertion) {
+      let content = "";
+      try {
+        content = readFileSync(abs, "utf-8");
+      } catch {
+        /* unreadable → treat as missing */
+      }
+      if (!content.includes(t.assertion)) {
+        return { ok: false, reason: `assertion not found in ${t.testFile}: "${t.assertion}"` };
+      }
+    }
+  }
+  return {
+    ok: true,
+    reason: !t.testFile
+      ? "trace complete (no testFile — ensure this is verifiable by inspection, or add an E2E test per 06b Rule 14)"
+      : "trace complete",
+  };
+}
+
 // ─── Dependency check ──────────────────────────────────────────────────────
 
 interface DependencyCheck {
@@ -140,6 +215,12 @@ function checkDependencies(): DependencyCheck[] {
         existsSync(join(gitDir, "github.com", "brunoj", "pi-aia-browser")),
       hint: "pi install npm:pi-aia-browser (installs Playwright + Chromium)",
     },
+    {
+      name: "pi-intercom (intercom: message other pi sessions)",
+      package: "pi-intercom",
+      present: existsSync(join(npmDir, "pi-intercom")),
+      hint: "pi install npm:pi-intercom",
+    },
   ];
 
   return checks;
@@ -149,7 +230,7 @@ function dependencySummary(): string {
   const checks = checkDependencies();
   const missing = checks.filter((c) => !c.present);
   if (missing.length === 0) {
-    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser ✓";
+    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser, pi-intercom ✓";
   }
   return (
     "⚠️ ASF dependencies missing — install before starting a project:\n" +
@@ -225,18 +306,79 @@ export default function register(pi: ExtensionAPI): void {
       }
       case "verify": {
         // Gate 7: force an explicit, itemised QA pass before delivery.
+        // Large work: mechanical spec-to-code traceability gate (M1).
         const project = projectName();
         const state = await loadState(project);
         if (!state.current) return "No active ASF session — nothing to verify.";
         await setPhase(ctx, "verification");
-        return (
-          `ASF verification gate (${project}) — Definition of Done.\n` +
-          `Read references/06b-testing-qa.md. Confirm EACH item with concrete evidence\n` +
-          `(command output, file list, screenshot). Do not tick anything you did not run.\n\n` +
-          QA_CHECKLIST.map((c, i) => `  ${i + 1}. [ ] ${c.label}`).join("\n") +
-          `\n\nThen run get_task_specs and close every spec with update_spec_status.\n` +
-          `Unverifiable → 'partial' + ask the user. Never self-certify.`
+        const scale = state.current.scale;
+        const lines: string[] = [
+          `ASF verification gate (${project}) — Definition of Done.`,
+          `Scale: ${scale || "unset"}${
+            scale === "large"
+              ? " — mechanical traceability gate ACTIVE"
+              : scale === "small"
+                ? " (automatic — no mechanical gate)"
+                : ""
+          }`,
+        ];
+
+        if (scale === "large") {
+          const specs = await loadSpecs(project);
+          lines.push("\nSPEC-TO-CODE TRACEABILITY (M1 — large work):");
+          if (!specs || specs.length === 0) {
+            lines.push(
+              "  (no spec-memory task found — capture specs with capture_spec, incl. items from external planning docs)",
+            );
+          } else {
+            const metSpecs = specs.filter((s) => s.status === "met");
+            if (metSpecs.length === 0) {
+              lines.push(
+                "  (no specs marked met yet — traceability applies when closing specs)",
+              );
+            } else {
+              let allOk = true;
+              for (const spec of metSpecs) {
+                const check = validateTrace(spec);
+                if (!check.ok) allOk = false;
+                lines.push(`  [${check.ok ? "PASS" : "FAIL"}] ${spec.id}: ${check.reason}`);
+                if (check.ok && spec.trace) {
+                  lines.push(`       outcome: ${spec.trace.outcome}`);
+                  lines.push(`       code path: ${spec.trace.codePath}`);
+                  if (spec.trace.testFile) {
+                    lines.push(
+                      `       test: ${spec.trace.testFile}${spec.trace.assertion ? ` (asserts "${spec.trace.assertion}")` : ""}`,
+                    );
+                  }
+                }
+              }
+              lines.push(
+                allOk
+                  ? "\n  ✓ All met specs have complete traces."
+                  : "\n  ✗ GATE NOT PASSED — resolve FAIL rows before delivery (attach trace via update_spec_status).",
+              );
+            }
+          }
+        }
+
+        lines.push(
+          "\nDefinition of Done checklist (references/06b-testing-qa.md Rule 10):",
+        );
+        lines.push(
+          "Read references/06b-testing-qa.md. Confirm EACH item with concrete evidence",
+        );
+        lines.push(
+          "(command output, file list, screenshot). Do not tick anything you did not run.",
+        );
+        lines.push("");
+        QA_CHECKLIST.forEach((c, i) => lines.push(`  ${i + 1}. [ ] ${c.label}`));
+        lines.push(
+          "\nThen run get_task_specs and close every spec with update_spec_status.",
+        );
+        lines.push(
+          "Unverifiable → 'partial' + ask the user. Never self-certify.",
         );
+        return lines.join("\n");
       }
       case "abort":
         return await setPhase(ctx, "none");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.2.2",
-  "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
+  "version": "0.4.0",
+  "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser, and pi-intercom.",
   "keywords": [
     "pi-package",
     "software-factory",
@@ -48,6 +48,9 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "pi-intercom": "^0.10.1"
+  },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
       "optional": false

package/skills/aia-asf/SKILL.md

@@ -70,6 +70,7 @@ Minimum intake checklist (ask anything not yet known, one question at a time or
 - **Constraints** — musts, must-nots, boundaries, budget, timeline
 - **Preferences** — stack, language, platform, style (only if the user has them)
 - **Definition of done** — tests? deploy? release? docs?
+- **External planning docs** — are there IMPROVEMENT-PLAN.md / PLAN.md / requirements docs / delivery logs / ticket lists? Locate them (repo root, `docs/`, referenced by the user); they are inputs to spec capture, not ground truth.
 
 For each answer, **capture hard requirements immediately with `capture_spec`** (requirement, area, priority). Specs are the shared contract with pi-vigilant — it will re-verify them at the end.
 
@@ -105,9 +106,10 @@ Turn the intake answers + research into the authoritative spec set.
 
 1. Run `get_task_specs` to see what's already captured.
 2. Fill gaps: for every requirement the user stated or approved, ensure a spec exists (`capture_spec`).
-3. Decompose broad specs with `parentId` (e.g. "must be secure" → auth + encryption sub-specs).
-4. Default priority is `must`; use `should` only when the user says "nice to have".
-5. Areas: functionality, ui-ux, performance, security, error-handling, testing, documentation, compatibility, constraints, format, data, deployment, other.
+3. **Ingest external planning docs (M6):** every actionable item in an external planning doc (IMPROVEMENT-PLAN.md, PLAN.md, requirements docs, delivery logs, ticket lists) becomes a captured spec with `sourceQuote` pointing at the doc + item id. The doc's own ✅/delivered markers are **claims, not evidence** — each item gets traced and verified like any other spec.
+4. Decompose broad specs with `parentId` (e.g. "must be secure" → auth + encryption sub-specs).
+5. Default priority is `must`; use `should` only when the user says "nice to have".
+6. Areas: functionality, ui-ux, performance, security, error-handling, testing, documentation, compatibility, constraints, format, data, deployment, other.
 
 **Gate 3** (large only): show the full spec tree (`get_task_specs`) and get user sign-off: "specs correct — proceed to adversarial analysis?" Small work: capture specs silently, no sign-off needed.
 
@@ -180,6 +182,15 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > understand; layered with clear boundaries and an architecture writeup; full I/O debug
 > logging with replay; nothing breaks existing functionality.
 
+> **Read `references/06d-delegation.md` before delegating.** Work may be delegated two ways:
+> **intercom** (message another live pi session that owns relevant context — always `list`
+> first, say what you want back, and treat their findings as evidence, not proof), and
+> **subagents** (spawn an isolated `pi -p` process when the OUTCOME matters more than the
+> trace — scoped codebase research, independent parallel fixes, fresh-perspective review).
+> Two verified hard limits: **never run parallel subagents against the same file** — tested,
+> 4 concurrent writers left only 1 of 4 edits, silently, all exiting 0 — and **exit code 0
+> does not mean success**, so always validate the returned output against what you asked for.
+
 Execute the task list milestone by milestone. Discipline rules:
 
 1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
@@ -188,9 +199,11 @@ Execute the task list milestone by milestone. Discipline rules:
 2. **Codebase isolation**: work strictly inside the project's own codebase. Do NOT edit files in other repos, global config, or unrelated directories — **unless the user explicitly instructs otherwise**. If a change would touch another codebase, stop and ask.
 3. **No scope creep**: if something new is discovered that changes specs, capture it, ask the user, and update the plan before implementing.
 4. **Descriptive commits**: `git commit -m "type: specific description of what and why"` (e.g. `fix: verify specs before rotation`). No vague messages, no placeholders.
-5. **Browser testing — MANDATORY for any web interface**: if the deliverable has a UI/website/web app, test it through `pi-aia-browser` (`browser_init`, `browser_navigate`, `browser_click`, `browser_type`, `browser_screenshot`, `browser_dom`, …) to replicate the user's real experience — not just curl/API checks. Verify: loads, key user journeys, responsive behavior, console errors.
+5. **Browser testing — MANDATORY for any web interface**: if the deliverable has a UI/website/web app, test it through `pi-aia-browser` (`browser_init`, `browser_navigate`, `browser_click`, `browser_type`, `browser_screenshot`, `browser_dom`, …) to replicate the user's real experience — not just curl/API checks. Verify: loads, key user journeys, responsive behavior, console errors. **Silent async paths included**: ingest through the real flow and wait for the enrichment to land (06b Rule 9).
 6. **Let pi-vigilant do its job**: it will auto-continue after premature stops and verify specs at settle. When it asks for `update_spec_status` with evidence, do it.
 7. **CHANGELOG discipline**: every user-visible change gets a CHANGELOG entry describing exactly what changed (no placeholder text).
+8. **Challenge approved designs (M4)**: if a spec's literal reading creates product tension (e.g. feedback clusters under "Plan" when "Plan = plans"), stop and resolve it with the user before implementing — never implement blindly and call it delivered.
+9. **Trace before claiming delivered (M5)**: the delivery log is a claim; the code is the evidence. Before marking anything ✅, trace the actual code path, confirm the output is consumed by a surface, and confirm the operator-facing outcome test passes.
 
 ---
 
@@ -200,6 +213,8 @@ Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule
 
 Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green.
 
+**Large work:** run `/asf verify` — it mechanically validates the **spec-to-code traceability matrix** (M1): every `met` spec must carry `trace` (outcome → codePath → testFile + assertion), testFile must exist, assertion must appear in it. FAIL rows block delivery. **Verify ingested specs from external planning docs too** — the doc's ✅ markers are claims, not evidence.
+
 1. Run the full test suite (all of it, not a subset); fix failures; re-run until green.
 2. **Verify the artifact a user would actually get**: inspect the packaged file list
    (`npm pack` → `tar tzf`), install/load it clean-room in a fresh dir with caches
@@ -240,15 +255,24 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - ❌ Escalation/fallback logic re-implemented per caller instead of one shared escalation path
 - ❌ Shipping a module that cannot run/test standalone outside the host
 - ❌ Refactoring without the architecture writeup (see `references/06c-code-quality.md`)
+- ❌ Running parallel subagents that touch the same file — edits are silently lost (see `references/06d-delegation.md`)
+- ❌ Trusting a subagent's exit code or self-report instead of verifying the actual code/test result
+- ❌ Re-deriving context another live session already has instead of asking it over intercom
 - ❌ Breaking existing functionality during a refactor — refactoring preserves behavior
+- ❌ Marking a spec delivered from the delivery log instead of tracing the code — the log is a claim
+- ❌ Shipping machinery no surface consumes — delivered = visible in the product (UI or API)
+- ❌ Trusting unit tests as proof of wiring — assert the operator-facing outcome end-to-end
+- ❌ Trusting an external plan's ✅ (IMPROVEMENT-PLAN / delivery log) — ingest its items as specs and verify them
+- ❌ Implementing a spec literally when it creates product tension — challenge it and resolve with the user
 
 ## References
 
-- `references/01-intake.md` — question bank and probing techniques
+- `references/01-intake.md` — question bank and probing techniques (incl. external planning docs, M6)
 - `references/02-research.md` — research playbook with search templates
 - `references/04-adversarial.md` — adversarial checklist per area
-- `references/05-plan.md` — PLAN.md template with examples
-- `references/06-implementation.md` — coding discipline details
-- `references/06b-testing-qa.md` — **mandatory testing & QA standard** (11 rules + definition of done)
+- `references/05-plan.md` — PLAN.md template with examples (incl. spec-to-code traceability matrix)
+- `references/06-implementation.md` — coding discipline details (incl. M4 challenge designs, M5 trace before claiming)
+- `references/06b-testing-qa.md` — **mandatory testing & QA standard** (14 rules + definition of done)
 - `references/06c-code-quality.md` — **mandatory modularity & maintainability standard** (8 rules, SSOT, testable-standalone, single escalation path)
+- `references/06d-delegation.md` — **intercom & subagents**: when to message another session, when to spawn isolated workers, the no-mutual-dependencies rule, and why exit codes lie
 - `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

package/skills/aia-asf/references/01-intake.md

@@ -13,6 +13,24 @@ Keep asking until the user confirms. One question at a time is fine; short batch
 - "What exists today?" (blank slate / existing repo / replaces something)
 - "How will we know it's done and correct?" (concrete success criteria)
 - "Any hard constraints?" (stack, platform, budget, timeline, must-nots)
+- "**Are there external planning docs?**" (IMPROVEMENT-PLAN.md, PLAN.md, requirements docs, delivery logs, ticket lists — in the repo, `docs/`, or referenced by the user)
+
+## External planning docs (M6) — locate and ingest
+
+When a task references or contains external planning documents, **realize they
+exist**: look in the repo root, `docs/`, and anything the user points at. Then
+**treat them like own captured specs**:
+
+1. Read the doc(s) and list every actionable item (e.g. `IMP-002/006 — service agent titles`).
+2. `capture_spec` each item with `sourceQuote` pointing at the doc + item id.
+3. **The doc's own ✅ / "delivered" markers are claims, not evidence** — each
+   item gets traced (outcome → codePath → test) and verified like any other spec.
+4. If the doc is large, ingest by section and decompose with `parentId`.
+
+> **Why this matters (betamaxx audit):** the IMPROVEMENT-PLAN's delivery log said
+> "IMP-006+P-A delivered ✅" and that was trusted as ground truth — the code was
+> never traced. `intelligenceBudget.analyze()` shipped as dead code. Ingesting
+> the plan's items as specs forces each one to be traced and verified.
 
 ## Probing techniques
 

package/skills/aia-asf/references/04-adversarial.md

@@ -14,6 +14,12 @@ Challenge every spec and design decision like a hostile reviewer. For each item,
 > testable standalone with the same calls? Any hardcoded values that belong in
 > config?
 
+> **Traceability lens (always applied):** for every spec, ask — *what is the
+> operator-facing outcome, and what code path delivers it?* Trace the path in
+> your head: where could **dead wiring** hide (a function defined but never
+> called, an async enrichment that never lands, a surface that never renders)?
+> If the outcome has no concrete path, the spec is not yet real.
+
 - **Edge cases**: empty input, zero data, max load, missing fields, concurrent access, duplicate input, unicode, huge payloads
 - **Failure modes**: what breaks first? Is failure loud or silent? Can we recover automatically?
 - **Security**: authentication, authorization, injection (SQL/XSS), data exposure, secrets, abuse/rate-limiting, supply chain

package/skills/aia-asf/references/05-plan.md

@@ -29,6 +29,14 @@ Decided approach with rationale. Cite the research (package names, URLs).
 - **Layering**: one-way dependency rules between layers; what each layer may/may not import
 - **Standalone testability**: how each module is exercised outside the host with the same calls
 
+## Spec-to-code traceability matrix
+For every spec, the operator-facing outcome, the code path that delivers it, and the test that asserts it. This is what `/asf verify` checks mechanically at delivery (M1).
+
+| Spec | Operator-facing outcome | Code path | Test (asserts outcome) |
+|------|------------------------|-----------|------------------------|
+| spc-… | e.g. "ingested report has an agent_title on the card" | ingest → analyze() → persist → render | tests/e2e-ingest.test.ts (`agent_title`) |
+| … | | | |
+
 ## Milestones
 | # | Milestone | Exit criteria |
 |---|-----------|---------------|

package/skills/aia-asf/references/06-implementation.md

@@ -60,3 +60,26 @@ Every user-visible change gets an entry under `## [Unreleased]` or the released
 - New hard requirement discovered → `capture_spec` immediately
 - Requirement changed → capture superseding spec (old → obsolete)
 - When pi-vigilant injects its verification checklist → respond with `update_spec_status` + evidence
+
+## Challenge approved designs during implementation (M4)
+
+A plan was approved, but that does not make it correct. When a spec's literal
+reading creates **product tension** (e.g. feedback clusters rendered under the
+"Plan" tab when "Plan = plans"), **stop and resolve it with the user before
+implementing** — do not implement blindly and call it delivered.
+
+- Tension detected → state it plainly, propose the fix, get a decision.
+- Implement the *sensible* version, not the literal-but-wrong one.
+- The user's words "implemented in a SENSIBLE way" are the acceptance bar.
+
+## The delivery log is a claim; the code is the evidence (M5)
+
+Before marking anything ✅ (a spec, a milestone, a delivery-log item):
+
+1. **Trace the actual code path** — the function is called, not just defined.
+2. Confirm the output is **consumed by a surface** (Rule 13).
+3. Confirm the **operator-facing outcome test** passes (Rule 12).
+
+A delivery log saying "IMP-006 delivered ✅" proves nothing. The code is the
+evidence. External planning docs (IMPROVEMENT-PLAN.md, PLAN.md, delivery logs)
+are inputs to spec capture — their ✅ markers are claims, never ground truth.

package/skills/aia-asf/references/06b-testing-qa.md

@@ -125,6 +125,13 @@ API/curl checks do not replicate what a human sees. Via `pi-aia-browser`:
 
 A 200 response with a blank or broken page is a **failure**.
 
+**Silent async paths are the priority.** Fire-and-forget enrichment (an async
+budgeted analysis that fills in a card title after render) fails silently — the
+page renders, nobody notices the enrichment never landed. For any async/silent
+surface: ingest through the real flow, then **wait for the enrichment to appear**
+and assert it (e.g. ingest a report, wait for `agent_title` on the card). If it
+never arrives, the wiring is dead — that is a failed test.
+
 ## Rule 10 — Definition of done (all must hold)
 
 - [ ] Typecheck/build passes
@@ -135,6 +142,9 @@ A 200 response with a blank or broken page is a **failure**.
 - [ ] Observable end state verified as a user would experience it
 - [ ] Web surfaces exercised through a real browser
 - [ ] Every MUST spec `met` with concrete evidence (`update_spec_status`)
+- [ ] **Spec-to-code traceability: every `met` spec carries `trace` (outcome → codePath → testFile + assertion); `/asf verify` mechanically validates it (large work)**
+- [ ] **Consumed by a surface: every delivered feature's output is visible in the product (UI or API) — nothing ships as dead machinery**
+- [ ] **E2E behavioral test: every feature spec has a test through the real entry point asserting the operator-facing outcome**
 - [ ] Unverifiable specs → `partial` + asked the user (never self-certified)
 
 ## Rule 11 — Report honestly
@@ -144,3 +154,43 @@ A 200 response with a blank or broken page is a **failure**.
 - If a check was skipped or inconclusive, **say so explicitly** and say why.
 - Distinguish "tests pass" from "feature works for the user" — Rule 2.
 - If you discover you shipped something broken, say it plainly and fix it first.
+
+## Rule 12 — Test the OPERATOR-FACING OUTCOME, not the machinery
+
+> **Real failure (betamaxx audit):** `intelligence-budget.test.ts` and
+> `service-session.test.ts` passed — they proved `analyze()` *works in
+> isolation*. Nobody tested "does ingest actually call `analyze()`?". The tests
+> proved the machinery, not the wiring. `intelligenceBudget.analyze()` shipped
+> as **dead code** while every unit test was green.
+
+Unit tests prove a component works in isolation. They do **not** prove the
+feature is wired. For every feature spec, the deciding test is the one that
+asserts the **operator-facing outcome** end-to-end:
+
+- ❌ "`analyze()` returns a budget verdict" (machinery)
+- ✅ "an ingested report eventually has an `agent_title` rendered on the card" (outcome)
+
+If a unit test is green but the outcome test is missing, the feature is **not**
+done — the wiring may be dead.
+
+## Rule 13 — Nothing is delivered until CONSUMED BY A SURFACE
+
+> **Real failure (betamaxx audit):** code commented *"Not yet consumed by a
+> surface"* shipped as "delivered". Machinery (budget, runner, verdict
+> contract) was built; the product behavior (cards titled by the agent) never
+> happened.
+
+- **Delivered = the output is visible in the product** (UI or API).
+- Code commented "not yet consumed by a surface" is, by definition, **not
+  delivered**.
+- Before marking a spec `met`, answer: *where does a user/operator see this?*
+  If nowhere — it is not done.
+
+## Rule 14 — Every feature spec ships an E2E behavioral test through the REAL entry point
+
+- The E2E test drives the **real entry point** (HTTP endpoint, CLI, UI) with a
+  mocked boundary (agent, DB), and asserts the operator-facing outcome.
+- This catches dead wiring in one test: ingest → `analyze()` → persist → render.
+- **Scale note:** mandatory for feature specs in **large/gated work**. For small
+  work, required only when the change touches a surface/wiring; otherwise the
+  standard test-first rules above suffice.

package/skills/aia-asf/references/06d-delegation.md

@@ -0,0 +1,130 @@
+# Delegation: Intercom & Subagents
+
+ASF work does not have to happen in one session, in one context window, or one task at a time. Two delegation mechanisms are available. They solve different problems and must not be confused.
+
+| | **Intercom** | **Subagents** |
+|---|---|---|
+| What it is | Messaging between *live pi sessions* | Spawning a *fresh, isolated pi process* |
+| Peer | A human-driven or long-running session with its own context and history | A stateless worker that exits when done |
+| You get back | A conversation (peer can push back, ask, disagree) | One result |
+| Use when | Another session owns the context/decision | You want the OUTCOME, not the trace |
+| Cost | Cheap (a message) | A whole context window + model spend |
+
+---
+
+## Part 1 — Intercom: passing messages to other sessions
+
+Other pi sessions on this machine are often working on directly relevant things: the same monorepo, an adjacent service, the package you depend on. **Use intercom to talk to them directly instead of guessing, duplicating their work, or routing everything through the user.**
+
+### When to use intercom
+
+- **Another session owns the context.** They have the repo loaded, the failure reproduced, the domain knowledge. Ask them rather than re-deriving it.
+- **Your change affects their work.** You changed a shared interface, published a version, moved a file they depend on. Tell them.
+- **You need independent verification.** A second session reproducing your result is stronger evidence than your own re-run (see 06b Rule 11).
+- **Cross-project coordination.** Your package is their dependency; sequencing matters.
+- **You found something they need to know.** A bug in shared code, a broken assumption, a security issue.
+
+### How
+
+```
+intercom({ action: "list" })                                  // who is live
+intercom({ action: "send", to: "<name-or-id>", message: "…" }) // fire-and-forget
+intercom({ action: "ask",  to: "<name-or-id>", message: "…" }) // wait for a reply
+```
+
+Target by session name, full ID, or the short id in parentheses from `list`. Use `cwd` to scope to a directory when two sessions share a name.
+
+### Rules
+
+1. **`list` before you send.** Don't message a session that isn't live.
+2. **Say what you want back.** "Please verify X and reply with the result" beats "FYI X."
+3. **Give them what they need to act** — file paths, repro commands, exact error text. Assume zero shared context.
+4. **`ask` blocks; `send` doesn't.** Use `ask` only when you genuinely need the answer before continuing.
+5. **Hand over your weak points, not just your conclusions.** If you want a peer to verify, tell them what you did *not* test and what you'd most like broken. A peer who only receives conclusions will rubber-stamp them.
+6. **Their findings are evidence, not proof.** An independent reproduction is strong; an unverified claim from a peer is still a claim (06b Rule 12, and M5: the log is a claim, the code is the evidence).
+7. **Don't leak the user's private context** across projects without reason.
+
+---
+
+## Part 2 — Subagents: delegating for the outcome
+
+A subagent is a **fresh `pi` process with its own context window**. It takes a task, works independently, returns a result, and exits. The parent context never sees its intermediate tool calls — only the answer.
+
+> **Core principle: subagents are context isolation, not role-play.** The point is to keep 5,000 lines of grep/read output out of the parent context, not to create "personas."
+
+### When to spawn a subagent
+
+Spawn when **the outcome matters more than the trace**:
+
+- **Scoped codebase research.** "Which module owns retry logic, and what's its interface?" The search noise is worthless once the answer exists. *Signal: gathering the answer means reading many files.*
+- **Independent small changes with NO MUTUAL DEPENDENCIES.** Three unrelated files each needing the same mechanical fix — run them in parallel.
+- **Fresh-perspective review.** A reviewer that never saw your reasoning catches what familiarity hides. Especially valuable for challenging an approved design (06-implementation M4).
+- **Bounded, noisy verification.** Running a long test matrix and reporting just the failures.
+
+**Rule of thumb:** if the task needs exploring many files, or there are 3+ genuinely independent pieces of work, delegate.
+
+### When NOT to spawn a subagent
+
+- **Sequential/dependent work.** If step 2 needs step 1's full output, one context is cleaner than a relay.
+- **Anything touching the same file.** See the hard evidence below.
+- **Small tasks.** Delegation overhead exceeds the benefit. Just do it.
+- **Work needing judgment you'd have to fully specify anyway.** If writing the task description costs more than doing the work, do the work.
+- **The core implementation of a gated (LARGE) change.** You own the specs and the traceability. Delegate research and isolated fixes around it, not the spec-carrying work itself.
+- **Nested delegation.** A subagent must not spawn subagents. Keep the tree one level deep.
+
+### ⚠️ The no-mutual-dependencies rule is not advisory — it is enforced by physics
+
+**Verified experimentally.** Four subagents were told to each change a different key in the *same* file, reading it and writing the complete file back:
+
+```
+before: { a: 1, b: 2, c: 3, d: 4 }   → 4 agents, one key each
+after:  { a: 1, b: 2, c: 3, d: 99 }  → 1 of 4 edits survived
+```
+
+**Three edits were silently lost.** Every agent reported success. Every process exited 0. There was no error, no conflict marker, no warning — just a file that quietly lost 75% of the intended work.
+
+Concurrent agents each read a snapshot and write back a whole file; last writer wins. Therefore:
+
+- **Never run parallel subagents against the same file.** Partition by file, and state the partition in each task.
+- If two tasks *might* touch the same file, they are dependent — **run them sequentially or do them yourself**.
+- Independence must be verified before spawning, not assumed. If you cannot name the disjoint file set, you do not have independence.
+
+### ⚠️ Exit code 0 does NOT mean the task succeeded
+
+**Verified:** a subagent asked to read a non-existent file explained the problem conversationally and **exited 0**.
+
+Never treat process exit status as the success signal. **Validate the returned output against what you asked for.** If a subagent was supposed to change code, verify the code changed — read the file, run the test. This is the delegation-shaped instance of M5: *the report is a claim; the code is the evidence.*
+
+### How to spawn
+
+There is **no built-in subagent tool in pi** — this is deliberate ("no sub-agents" is a stated design choice; you compose it yourself). Two supported routes:
+
+**1. Direct subprocess (always available, zero install):**
+
+```bash
+pi -p "<task>" --no-extensions --no-skills -t read,grep,find,ls
+```
+
+Run several in the background and `wait` for them to parallelize.
+
+**2. A subagent extension** (e.g. the `subagent/` example shipped with pi, or a package providing agent orchestration) — gives streaming output, parallel/chain modes, and usage tracking. Prefer this when available; fall back to `pi -p`.
+
+### Rules for spawning
+
+1. **Restrict tools to the job.** Research agents get read-only (`-t read,grep,find,ls`). Never hand write access to a task that only needs to look.
+2. **Use `--no-extensions --no-skills` for research.** Faster, cheaper, and it prevents a subagent from writing to shared state (specs, feedback) that belongs to the parent task.
+3. **Specify the output format.** "Return: file path, function name, and the 3-line interface — nothing else." Unspecified output returns an essay.
+4. **Bounded, stateless, single-responsibility.** A subagent that needs prior conversation is the wrong tool.
+5. **Partition writes by file** and say so explicitly in every parallel task.
+6. **Verify the result yourself** (see exit-code warning). For code changes: read the file or run the test.
+7. **Cap the fan-out.** A handful of parallel agents, not dozens; each costs a full context window.
+8. **One level deep.** No nesting.
+
+### Interaction with ASF gates
+
+Delegation changes **who does the work**, never **what must be proven**:
+
+- Specs, traceability, and the `/asf verify` gate remain the **parent's** responsibility. A subagent cannot discharge a spec.
+- The QA standard (06b) applies to delegated work identically. "A subagent did it" is not evidence.
+- Subagent findings enter the record as **claims** until verified against code or tests.
+- For LARGE work, the approval gate is unaffected: no subagent may start implementation before plan approval.