pi-aia-asf 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ 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
+
+- **Mandatory modularity & maintainability standard** (`references/06c-code-quality.md`) — 8 rules distilled from Bruno's Tunnel-project philosophy (small well-readable modules plugged in where needed; one authoritative implementation for shared functionality with a single escalation path; no hardcoding — config-driven; fully testable outside the host then integrated verbatim, same modules in tests and production; refactor what is too complex to understand; layered with clear one-way boundaries and an architecture writeup; full I/O debug logging with replay of stored data; nothing may break existing functionality) and reinforced by external research (SSOT, testability as design property, ports-and-adapters seams).
+
+### Changed
+
+- **Phase 6** now requires reading `06c-code-quality.md` before structuring code; **Phase 7** verification includes the modularity DoD (no duplicated shared logic, no hardcoded config values, standalone-tested modules, architecture writeup, existing functionality green).
+- **Phase 4** adversarial analysis gains a code-quality lens (duplication, single escalation path, standalone testability, hardcoded values); **Phase 5** PLAN.md architecture section now requires the SSOT map, layering rules, and standalone-testability notes.
+- Anti-patterns extended: god-objects, copy-pasted shared logic, test copies of modules, hardcoding, per-caller escalation logic, untestable-standalone modules, behavior-breaking refactors.
+
+
 ## [0.2.1] - 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.1",
+  "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.
 
@@ -172,6 +174,14 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > **read the actual error before editing**; **verify clean-room** (caches serve stale
 > builds); **add a regression test for every bug fixed**.
 
+> **Read `references/06c-code-quality.md` before structuring code.** It is the mandatory
+> modularity & maintainability standard: small well-readable modules plugged in where
+> needed; **one implementation for shared functionality** (single escalation path,
+> SSOT); no hardcoding (config-driven); **testable outside the host then integrated
+> verbatim** (same modules in tests and production); refactor what is too complex to
+> understand; layered with clear boundaries and an architecture writeup; full I/O debug
+> logging with replay; nothing breaks existing functionality.
+
 Execute the task list milestone by milestone. Discipline rules:
 
 1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
@@ -180,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.
 
 ---
 
@@ -190,6 +202,10 @@ Execute the task list milestone by milestone. Discipline rules:
 
 Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule 10). Every box must hold.
 
+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
@@ -223,13 +239,27 @@ Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule
 - ❌ Asking a barrage of intake questions for small work — small runs automatically
 - ❌ Writing PLAN.md / demanding approval for small work — that's the large-work gate only
 - ❌ Waiting for sign-off when the work is small; when in doubt, default to small and start
+- ❌ One giant file / god-object that "does everything" — small well-readable modules, plugged in
+- ❌ Copy-pasting shared logic instead of importing the one authoritative module (SSOT)
+- ❌ A "test copy" of a module that differs from the production version — same modules everywhere
+- ❌ Hardcoding values (model names, thresholds, URLs) that config should drive
+- ❌ 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`)
+- ❌ 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

@@ -8,6 +8,18 @@ Challenge every spec and design decision like a hostile reviewer. For each item,
 
 ## Per-spec questions
 
+> **Code-quality lens (always applied):** for every module/design under review,
+> also ask the `references/06c-code-quality.md` questions — is shared logic
+> duplicated anywhere? Is the single escalation path identifiable? Is the module
+> 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

@@ -21,10 +21,21 @@ Existing system, repo layout, relevant prior work. Links to research sources.
 Decided approach with rationale. Cite the research (package names, URLs).
 
 ## Architecture / Design
-- Components and their responsibilities
+- Modules and their responsibilities (small, single-purpose — see `references/06c-code-quality.md`)
 - Data model / schema (if any)
 - Key flows (request lifecycle, event flow)
 - Interfaces / contracts between components
+- **Where shared truth lives** (single source of truth map: which module owns each shared capability)
+- **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

@@ -1,5 +1,11 @@
 # Phase 6 — Implementation Discipline
 
+> **Also read `references/06c-code-quality.md`** — the modularity & maintainability
+> standard. Structure code as small modules with one responsibility, keep shared
+> functionality in exactly one implementation (SSOT, single escalation path),
+> never hardcode what config should drive, and keep every module testable
+> standalone outside the host.
+
 ## Test-first
 
 1. Write the failing test for the next behavior
@@ -54,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/06c-code-quality.md

@@ -0,0 +1,170 @@
+# Modularity & Maintainability Standard (MANDATORY)
+
+Distilled from Bruno's own development philosophy — honed on the Tunnel project
+and its modules (smart-router, autoroute, feature-extractor, heuristic-engine) —
+and reinforced by established software-engineering research: **Single Source of
+Truth (SSOT)**, **testability as a design property**, and **ports-and-adapters
+(hexagonal) seams**.
+
+These rules exist because violating them caused real pain in those sessions:
+code "thrown on a heap", duplicated logic, hardcoded model attributes, modules
+that could not be tested outside the server, and regressions that broke
+existing functionality. Each rule below carries the lesson.
+
+---
+
+## Rule 1 — Small, well-readable modules, plugged in where needed
+
+> *"You throw a bunch of code and functionality on a heap, instead of making
+> smaller, well-readable modules and plugging them in where needed."* — Tunnel sessions
+
+- One module = one responsibility. If a file does two unrelated things, split it.
+- A module must be **readable top to bottom** by someone new: clear names,
+  short functions, no 500-line god-files.
+- **Plug in, don't embed**: the host system imports and wires modules; it does
+  not copy their logic inline.
+- Extraction triggers (any of these → extract a module):
+  - a function/concern exceeds ~100 lines or 3 levels of nesting
+  - the same logic is needed by two call sites
+  - you cannot explain what the file does in one sentence
+  - you are about to debug the same area a second time
+
+## Rule 2 — One implementation for shared functionality (single escalation path)
+
+> *"Make a separate module for ... communication and use IT instead of having
+> that function integrated in there."* — Tunnel sessions
+
+- **Every shared capability lives in exactly one authoritative module.**
+  Everything else imports it. No copies, no re-implementations, no
+  "parallel systems working side by side" (*"I want an integrated system, not a
+  dual system working side by side"*).
+- This is the **Single Source of Truth** (SSOT) principle: every piece of
+  knowledge exists in exactly one place; every other reference *points* to it.
+- SSOT checklist before shipping (from research on SSOT):
+  - Is any value/logic defined in more than one place?
+  - If this changes tomorrow, how many files do I touch? (Answer: **one**.)
+  - Would a new developer know where the authoritative version lives?
+- Escalation paths included: if a request can escalate (to a stronger model,
+  a fallback, a retry, an admin), there is **one** escalation path module that
+  every caller routes through — not ad-hoc escalation logic scattered per
+  caller.
+
+## Rule 3 — No hardcoding; config drives behavior
+
+> *"DO NOT hard-code attributes of models ... stuff in the brackets is specific
+> to opus, but not necessarily to any model we will add."* — Tunnel sessions
+
+- Model names, thresholds, limits, timeouts, URLs, feature flags: all load from
+  config, never literal in logic.
+- If you hardcode a value that another system (or a future system) might share,
+  you have created a second source of truth — see Rule 2.
+- The module must behave the same for any config input; its logic is
+  config-agnostic.
+
+## Rule 4 — Testable outside the host, then integrated verbatim
+
+> *"MAKE IT TIGHT AND MODULAR AND FULLY TESTABLE OUTSIDE OF THE SERVER. TEST
+> EVERYTHING 100% ANALOGOUS TO HOW IT WORKS ON THE SERVER ... THEN INTEGRATE
+> BACK INTO THE SERVER."* — Tunnel sessions
+
+- A module must run standalone: a test script imports and primes it **with the
+  exact same calls** the host would make.
+- **Same modules in tests and production** — never a "test copy" of logic.
+  Tests import the production module; the host imports the same module.
+  (*"It should be imported in [the host] and used there with no changes — a
+  separate test script importing and priming the module can be created for
+  testing."*)
+- **Testability is a design property, not a testing task** (research): if a
+  business rule needs a running server + real DB to validate, the architecture
+  is wrong. Core logic should run as plain functions with injected fakes.
+- Build **seams** (ports-and-adapters): core logic depends on interfaces
+  (clock, IDs, persistence, external calls, message publishing), not on
+  concrete infrastructure. Adapters live at the edge.
+- Verification flow: develop → test standalone (100% analogous) → **integrate
+  into the host verbatim** → re-test in place.
+
+## Rule 5 — Refactor what is too complex to understand
+
+> *"REFACTOR WHAT IS TOO COMPLEX FOR YOU TO UNDERSTAND!"* — Tunnel sessions
+
+- Complexity you cannot explain is a defect, not a badge of honor.
+- When you find yourself running "rounds like a moron" debugging something,
+  **stop and refactor the module** instead of patching blind.
+- Refactor gate (when to invest): only refactor when it makes debugging and
+  individual component testing easier and faster, with the data you already
+  have. Not refactoring for its own sake; refactoring for **testability and
+  clarity**.
+- Refactoring techniques that directly serve this (research-validated):
+  **Extract Method** (break long functions into named steps), **Extract Class/
+  Module** (group related logic), **Replace Conditional with Polymorphism**
+  (turn nested conditionals into modular dispatch), **Remove Duplication**
+  (collapse copies into one implementation).
+
+## Rule 6 — Layer with clear boundaries, and document them
+
+> *"Refactor the layering for readability completely, test everything in
+> detail, and do a writeup for the layered system."* — Tunnel sessions
+
+- Define layers (e.g., handler → router → modules → backends) with one-way
+  dependency rules. No layer reaches across another.
+- **Do a writeup**: a short architecture doc (in the repo) stating what each
+  module is, what it uses, how and why, and where truth lives (the SSOT map).
+  (*"Properly document the modules and the main scaffolding to always have a
+  clear idea what is happening where."*)
+- Research on architecture fitness: keep the "core" boring and deterministic
+  (no framework/IO inside); edges translate to and from infrastructure.
+
+## Rule 7 — Debug observability: full I/O logging, replayable
+
+> *"Shouldn't you also log somewhere the FULL input and outputs of the whole
+> chain (during debug only) including headers and bodies ... and then
+> comparing, since the lateral test just works?"* — Tunnel sessions
+
+- During debug: log the **full input and output of the whole chain** (headers,
+  bodies, intermediate steps) to disk — not just errors.
+- Side tests must log identically, so you can **compare** a passing lateral
+  test against a failing production call and see the divergence.
+- Keep captured real traffic and **replay it through the structure**
+  (*"using stored message data and replaying it through the structure"*) to
+  reproduce and fix without the live host.
+- Logging must be enough that long-term debugging works from log files and the
+  stored corpus alone.
+
+## Rule 8 — Nothing may break existing functionality
+
+> *"Nothing may break already existing functionality in the server."* — Tunnel sessions
+
+- Modularity changes and refactors are **behavior-preserving**: same inputs,
+  same outputs, same side effects.
+- After any restructuring, run the existing tests + a regression pass over the
+  previous behavior before declaring done.
+- This is the SSOT/refactor safety net: refactoring restructures *structure*,
+  never *behavior*.
+
+---
+
+## Where this applies in ASF
+
+- **Phase 4 (adversarial)**: challenge the design — is there duplication?
+  Where is the single source of truth? Is the module testable outside the
+  host? What breaks if a config value changes?
+- **Phase 5 (PLAN.md)**: the Architecture/Design section must name the modules,
+  their boundaries, the one-way dependencies, where shared truth lives, and
+  how each module is tested standalone.
+- **Phase 6 (implementation)**: apply Rules 1–8 as you build; extract modules
+  when triggers fire; write the architecture doc alongside the code.
+- **Phase 7 (verification)**: the DoD checklist includes: no duplicated shared
+  logic (Rule 2), no hardcoded config values (Rule 3), every module tested
+  standalone with the same calls (Rule 4), architecture doc written (Rule 6),
+  existing functionality still green (Rule 8).
+
+## Anti-patterns
+
+- ❌ One giant file / god-object that "does everything"
+- ❌ Copy-pasting shared logic instead of importing the one module
+- ❌ A "test version" of a module that differs from the production version
+- ❌ Hardcoded model names, thresholds, URLs in logic instead of config
+- ❌ Escalation/fallback logic re-implemented per caller instead of one path
+- ❌ Refactoring "for fun" without the testability/debugging payoff
+- ❌ Shipping a module that cannot run outside the host
+- ❌ Skipping the architecture writeup ("the code is self-documenting")