pi-aia-asf 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-25
+
+### Added
+
+- (describe changes for 0.3.0)
+
+
 ## [0.2.2] - 2026-08-14
 
 ### Added

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 {
@@ -225,18 +300,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,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.2.2",
+  "version": "0.3.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, and pi-aia-browser.",
   "keywords": [
     "pi-package",

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.
 
@@ -188,9 +190,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 +204,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
@@ -241,14 +247,19 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - ❌ Shipping a module that cannot run/test standalone outside the host
 - ❌ Refactoring without the architecture writeup (see `references/06c-code-quality.md`)
 - ❌ 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/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.