pi-aia-asf 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-08-14
+
+### Added
+
+- **Scale-based flow.** Every ASF activation is now classified **small** or **large**:
+  - **Small** (small features, minor bugfixes, small refactors) — runs **automatically**: no intake question barrage (at most one clarifying question), no research, no adversarial gate, no PLAN.md, no approval. State the intent, capture specs silently, implement test-first, verify, deliver.
+  - **Large** (new projects, significant features, major bugfixes, architectural refactors) — full gated flow unchanged: intake → research → specs → adversarial → PLAN.md → **explicit approval** → implementation → verification.
+  - When in doubt, **default to small and start working**; re-classify upward if the work grows.
+- **`/asf small`** command — starts a small session directly in implementation phase. `/asf status` now shows the scale (`automatic — no gates` for small).
+
+### Changed
+
+- All gates (1–5) explicitly apply to large work only; Phase 2 (research) and Phase 5 (PLAN.md + approval) are skipped entirely for small work.
+- References `01-intake`, `04-adversarial`, `05-plan` annotated with the scale rule.
+- Anti-patterns: no question barrage or PLAN.md/approval demand for small work; when in doubt, start small.
+
+
+## [0.2.0] - 2026-08-14
+
+### Added
+
+- **Mandatory testing & QA standard** (`references/06b-testing-qa.md`) — 11 rules distilled from real shipped-broken failures: test the packaged artifact (not just source), assert the observable end state, probe for silent failures, read the actual error before editing, clean-room verification against stale caches, a regression test for every bug fixed, test triggers *and* non-triggers, state-machine deadlock tests, mandatory browser testing for web surfaces, a definition-of-done checklist, and honest reporting.
+- **`/asf verify`** — an explicit definition-of-done gate that itemises the 9 required checks, points at the QA standard, and forbids self-certifying unverifiable specs.
+
+### Changed
+
+- Phase 6 and Phase 7 of the skill now require the QA standard; Phase 7 additionally requires verifying the packaged artifact and the observable end state, plus honest reporting of skipped or inconclusive checks.
+- Anti-patterns extended: shipping without inspecting the packaged file list, treating "no error" as success, verifying against a stale install, guessing before reading the error, fixing without a regression test, and claiming assumed verification.
+
+### Fixed
+
+- **`/asf-approve` rubber-stamped Gate 5.** It marked the plan approved even when no `PLAN.md` existed — approving a plan the user had never seen. It now refuses unless `PLAN.md` is present, and advances the phase to implementation on success.
+
+
 ## [0.1.1] - 2026-08-14
 
 ### Fixed

package/index.ts

@@ -30,14 +30,30 @@ type AsfPhase =
   | "implementation"
   | "verification";
 
+type AsfScale = "small" | "large";
+
 interface AsfState {
   workType?: "new-project" | "feature" | "major-bugfix" | "refactor";
+  scale?: AsfScale;
   phase: AsfPhase;
   planApproved?: boolean;
   startedAt?: string;
   updatedAt: string;
 }
 
+/** Definition-of-done checks (references/06b-testing-qa.md, Rule 10). */
+const QA_CHECKLIST: Array<{ key: string; label: string }> = [
+  { key: "build", label: "Typecheck/build passes" },
+  { key: "tests", label: "Full test suite green (not a subset)" },
+  { key: "regression", label: "Regression test added for every bug fixed this cycle" },
+  { key: "triggers", label: "Triggers AND non-triggers tested for conditional behavior" },
+  { key: "artifact", label: "Shipped artifact inspected (npm pack file list) + clean-room install" },
+  { 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: "honest", label: "Skipped/inconclusive checks reported explicitly" },
+];
+
 interface ProjectStateFile {
   current: AsfState | null;
   history: Array<{ workType: string; phase: AsfPhase; startedAt: string; endedAt: string }>;
@@ -147,7 +163,7 @@ export default function register(pi: ExtensionAPI): void {
   // Startup check: warn once per session if deps are missing (unless disabled)
   // The extension loads at startup; log to console so it surfaces in logs.
 
-  const setPhase = async (ctx: ExtensionCommandContext, phase: AsfPhase, workType?: AsfState["workType"]): Promise<string> => {
+  const setPhase = async (ctx: ExtensionCommandContext, phase: AsfPhase, workType?: AsfState["workType"], scale?: AsfScale): Promise<string> => {
     const project = projectName();
     const state = await loadState(project);
     const now = new Date().toISOString();
@@ -170,6 +186,7 @@ export default function register(pi: ExtensionAPI): void {
         };
       }
       if (workType) state.current.workType = workType;
+      if (scale) state.current.scale = scale;
       state.current.phase = phase;
       state.current.updatedAt = now;
     }
@@ -183,13 +200,15 @@ export default function register(pi: ExtensionAPI): void {
 
     switch (sub) {
       case "new":
-        return await setPhase(ctx, "intake", "new-project");
+        return await setPhase(ctx, "intake", "new-project", "large");
       case "feature":
-        return await setPhase(ctx, "intake", "feature");
+        return await setPhase(ctx, "intake", "feature", "large");
       case "bugfix":
-        return await setPhase(ctx, "intake", "major-bugfix");
+        return await setPhase(ctx, "intake", "major-bugfix", "large");
       case "refactor":
-        return await setPhase(ctx, "intake", "refactor");
+        return await setPhase(ctx, "intake", "refactor", "large");
+      case "small":
+        return await setPhase(ctx, "implementation", undefined, "small");
       case "status": {
         const project = projectName();
         const state = await loadState(project);
@@ -197,22 +216,40 @@ export default function register(pi: ExtensionAPI): void {
         return (
           `ASF status (${project}):\n` +
           `  work type: ${state.current.workType || "unset"}\n` +
+          `  scale: ${state.current.scale || "unset"}${state.current.scale === "small" ? " (automatic — no gates)" : ""}\n` +
           `  phase: ${state.current.phase}\n` +
           `  plan approved: ${state.current.planApproved ? "yes" : "no"}\n` +
           `  started: ${state.current.startedAt || "?"}\n` +
           `  history: ${state.history.length} completed session(s)`
         );
       }
+      case "verify": {
+        // Gate 7: force an explicit, itemised QA pass before delivery.
+        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.`
+        );
+      }
       case "abort":
         return await setPhase(ctx, "none");
       default:
         return (
           "ASF commands:\n" +
-          "  /asf new        — start a new software project\n" +
-          "  /asf feature    — add a feature to an existing project\n" +
-          "  /asf bugfix     — major bugfix\n" +
-          "  /asf refactor   — architectural refactor\n" +
+          "  /asf new        — start a new software project (large, gated)\n" +
+          "  /asf feature    — add a feature to an existing project (large, gated)\n" +
+          "  /asf bugfix     — major bugfix (large, gated)\n" +
+          "  /asf refactor   — architectural refactor (large, gated)\n" +
+          "  /asf small      — small change, automatic (no gates)\n" +
           "  /asf status     — show current phase\n" +
+          "  /asf verify     — run the definition-of-done QA gate\n" +
           "  /asf abort      — end the current session\n\n" +
           dependencySummary()
         );
@@ -224,9 +261,25 @@ export default function register(pi: ExtensionAPI): void {
     const project = projectName();
     const state = await loadState(project);
     if (!state.current) return "No active ASF session — start one with /asf new|feature|bugfix|refactor.";
+
+    // Gate 5 must approve something that actually exists: refuse to rubber-stamp
+    // when no PLAN.md is present (a plan the user never saw cannot be approved).
+    const planPath = join(process.cwd(), "PLAN.md");
+    if (!existsSync(planPath)) {
+      return (
+        `No PLAN.md found in ${process.cwd()}.\n` +
+        "Gate 5 approves a written plan — write PLAN.md and present it to the user first."
+      );
+    }
+
     state.current.planApproved = true;
+    state.current.phase = "implementation";
     state.current.updatedAt = new Date().toISOString();
     await saveState(project, state);
-    return "Plan approved ✓ — Gate 5 passed, implementation may begin.";
+    return (
+      "Plan approved ✓ — Gate 5 passed, implementation may begin.\n" +
+      "Test-first, strict codebase isolation, regression test per bug fixed.\n" +
+      "Run /asf verify before delivery."
+    );
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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

@@ -4,15 +4,17 @@ description: >-
   Agentic Software Factory — run a complete, disciplined software development
   cycle. Use when the user wants to start a NEW software project, add a
   SIGNIFICANT FEATURE to an existing project, perform a MAJOR BUGFIX, or do an
-  ARCHITECTURAL REFACTOR. The flow classifies the work, asks questions until the
-  intent is clear, researches SOTA and existing packages, captures hard
-  specifications (via capture_spec, shared with pi-vigilant), runs adversarial
-  analysis, produces a PLAN.md and gets explicit user approval, then implements
-  test-first with strict codebase isolation and mandatory browser testing of any
-  web interfaces (pi-aia-browser). Do NOT activate for simple Q&A, one-line
-  fixes, casual conversation, content writing, or non-software tasks. When in
-  doubt about whether work qualifies as a project/feature/bugfix/refactor, ask
-  the user.
+  ARCHITECTURAL REFACTOR — and also for SMALL software changes (small features,
+  minor bugfixes, small refactors), which run AUTOMATICALLY with no intake
+  questions, no PLAN.md, and no approval. LARGE work (new projects, significant
+  features, major bugfixes, architectural refactors) runs the full gated flow:
+  classify, ask until intent is clear, research SOTA and packages, capture hard
+  specifications (via capture_spec, shared with pi-vigilant), run adversarial
+  analysis, produce a PLAN.md and get explicit user approval, then implement
+  test-first with strict codebase isolation and mandatory browser testing of web
+  interfaces (pi-aia-browser). Do NOT activate for simple Q&A, one-line fixes,
+  casual conversation, content writing, or non-software tasks. When in doubt,
+  ask the user.
 ---
 
 # AIA Agentic Software Factory (ASF)
@@ -28,24 +30,35 @@ You are running the **Ai Applied Agentic Software Factory**. This skill codifies
 
 ## Phase 0 — Classify the work (gate)
 
-Determine the work type. If it is not ASF work, **do not run the factory** — just help normally.
+Determine the work type **and scale**. If it is not ASF work, **do not run the factory** — just help normally.
 
-| Work type | ASF? |
-|---|---|
-| New software project | ✅ yes — full flow |
-| Significant feature in an existing project | ✅ yes — full flow (research: medium depth) |
-| Major bugfix (multi-file, behavior change, needs tests) | ✅ yes — lighter flow (research optional) |
-| Architectural refactor | ✅ yes — full flow (research: low depth) |
-| Simple Q&A, one-liner fix, casual talk, docs-only | ❌ no |
-| Non-software tasks (LinkedIn, research-only, writing) | ❌ no |
+| Work type | ASF? | Scale | Flow |
+|---|---|---|---|
+| New software project | ✅ | **large** | full flow |
+| Significant feature | ✅ | **large** | full flow (research: medium) |
+| Small feature | ✅ | **small** | automatic |
+| Major bugfix (multi-file, behavior change, needs tests) | ✅ | **large** | lighter flow (research optional) |
+| Minor bugfix (one area, no contract change) | ✅ | **small** | automatic |
+| Architectural refactor | ✅ | **large** | full flow (research: low) |
+| Small refactor (renames, restructure of one module) | ✅ | **small** | automatic |
+| Simple Q&A, one-liner fix, casual talk, docs-only | ❌ | — | — |
+| Non-software tasks (LinkedIn, research-only, writing) | ❌ | — | — |
+
+**Scale rule — the core behavior difference:**
+
+- **Large work** runs the full gated flow: intake questions → research → specs → adversarial → PLAN.md → **explicit approval** → implementation → verification.
+- **Small work runs automatically**: no intake question barrage (at most ONE clarifying question, only if truly ambiguous), no research, no PLAN.md, no approval gate. State the intent in one or two sentences, capture specs, implement test-first, verify, deliver. Do not ask permission to start; do not stop for sign-off. If it turns out to be larger than expected mid-way, re-classify, say so, and switch to the full flow with approval.
+- When in doubt about scale, **default to small and start working** — the user prefers action over questions. Re-classify upward if the work grows.
 
 If the user's request is ambiguous, **ask** before starting. State the classification explicitly:
-`ASF: <new-project|feature|major-bugfix|refactor> — starting Phase 1 (intake).`
+`ASF: <new-project|feature|major-bugfix|refactor> <large|small> — starting Phase 1 (intake).`
 
 ---
 
 ## Phase 1 — Intake: ask until it's clear (gate)
 
+> **Scale check — applies to LARGE work only.** For **small** work: skip the question bank. If the request is clear enough to act, state your understanding in one or two sentences and proceed immediately. Ask at most ONE clarifying question, and only when genuinely ambiguous.
+
 The factory **keeps asking until all is clear**. Never start planning or implementation on guesses.
 
 Minimum intake checklist (ask anything not yet known, one question at a time or a short batch):
@@ -60,12 +73,14 @@ Minimum intake checklist (ask anything not yet known, one question at a time or
 
 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.
 
-**Gate 1**: You may only leave intake when the user has confirmed the summary of intent (restate it back in 3–5 bullet points and ask "is this correct?").
+**Gate 1** (large only): You may only leave intake when the user has confirmed the summary of intent (restate it back in 3–5 bullet points and ask "is this correct?"). Small work does not pass through this gate.
 
 ---
 
 ## Phase 2 — Research: SOTA and packages (adaptive depth)
 
+> **Small work skips research entirely.** If implementation needs a library you don't know, a single quick search is enough — no research summary, no Gate 2.
+
 | Work type | Research depth |
 |---|---|
 | New project | **Mandatory, full** — SOTA approaches, frameworks, existing packages, reference implementations |
@@ -80,7 +95,7 @@ Research method (use `web_search` + `web_fetch`/`batch_web_fetch`):
 4. **Cite sources** in the research summary — every claim about a package/library gets a URL
 5. Summarize findings + a **recommendation** (which approach, which packages, with rationale)
 
-**Gate 2**: present the research summary + recommendation to the user. Ask: "proceed with this approach, or adjust?" Do not enter planning until the approach is agreed.
+**Gate 2** (large only): present the research summary + recommendation to the user. Ask: "proceed with this approach, or adjust?" Do not enter planning until the approach is agreed.
 
 ---
 
@@ -94,12 +109,14 @@ Turn the intake answers + research into the authoritative spec set.
 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.
 
-**Gate 3**: show the full spec tree (`get_task_specs`) and get user sign-off: "specs correct — proceed to adversarial analysis?"
+**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.
 
 ---
 
 ## Phase 4 — Adversarial analysis (gate)
 
+> **Small work:** skip the formal gate. Do a quick mental pass over edge cases and failure modes while implementing; if something real surfaces, fix it or capture a spec. No user checkpoint.
+
 Challenge the plan like a hostile reviewer before committing to it. For each spec and the overall design, ask and resolve:
 
 - **Edge cases** — empty input, zero users, max load, missing data, concurrency
@@ -112,12 +129,14 @@ Challenge the plan like a hostile reviewer before committing to it. For each spe
 
 For each finding: either capture a new spec, refine an existing one (supersede), or record the decision to accept the risk. **Ask the user about anything that changes scope.**
 
-**Gate 4**: summarize adversarial findings + resolutions, get user confirmation.
+**Gate 4** (large only): summarize adversarial findings + resolutions, get user confirmation.
 
 ---
 
 ## Phase 5 — Plan + approval gate
 
+> **Small work: SKIP this phase entirely.** No PLAN.md, no approval — go straight to Phase 6 (implementation).
+
 Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
 
 ```markdown
@@ -136,18 +155,28 @@ Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
 
 Keep the plan **implementation-ready**: any competent engineer (or agent) can execute the task list without re-deriving decisions.
 
-**Gate 5 — MANDATORY user approval**: present the plan and ask explicitly:
+**Gate 5 — MANDATORY user approval (large only)**: present the plan and ask explicitly:
 > "Plan ready. Do you approve starting implementation? (yes / changes needed)"
 
-**Never start implementing before Gate 5 passes.** If the user says "go" without reading, still show the plan and confirm.
+**Never start implementing before Gate 5 passes — for LARGE work.** If the user says "go" without reading, still show the plan and confirm. Small work never reaches this gate.
 
 ---
 
 ## Phase 6 — Implementation (test-first, disciplined)
 
+> **Read `references/06b-testing-qa.md` before writing tests.** It is the mandatory QA
+> standard, distilled from real shipped-broken failures. Non-negotiable highlights:
+> **test the shipped artifact, not just the source** (inspect `npm pack` output);
+> **assert the observable end state**, not intermediate files; **probe for silent
+> failures** (a malformed manifest/frontmatter is skipped without any error);
+> **read the actual error before editing**; **verify clean-room** (caches serve stale
+> builds); **add a regression test for every bug fixed**.
+
 Execute the task list milestone by milestone. Discipline rules:
 
 1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
+   Every bug fixed gets a **regression test** that fails on the old code. For conditional
+   behavior (skills, gates, auto-activation) test **triggers AND non-triggers**.
 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.
@@ -159,8 +188,17 @@ Execute the task list milestone by milestone. Discipline rules:
 
 ## Phase 7 — Verification & delivery (gate)
 
-1. Run the full test suite; fix failures; re-run until green.
-2. Run `get_task_specs` and verify **every spec** with `update_spec_status` + concrete evidence (test output, build result, code inspection). Unverifiable → `partial` + ask the user. Never self-certify.
+Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule 10). Every box must hold.
+
+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
+   cleared, confirm the installed version is the one just built, and confirm the
+   **observable end state** (the tool/skill/page actually appears and works) — not just
+   that files are in place. Any web surface must be exercised through `pi-aia-browser`.
+3. Run `get_task_specs` and verify **every spec** with `update_spec_status` + concrete evidence (test output, build result, code inspection). Unverifiable → `partial` + ask the user. Never self-certify.
+4. **Report honestly**: never claim a check you didn't run; state explicitly anything
+   skipped or inconclusive, and distinguish "tests pass" from "works for the user".
 3. If the project is a library/package that the user publishes (npm, GitHub release): **offer** to run the release (see `references/07-release.md`): version bump, CHANGELOG, git tag, push. **Publishing is always the user's decision** — never publish without explicit approval. Optionally offer to set up a CI/CD pipeline for publishing.
 4. Present a completion summary: what was built, specs met, tests passing, how to use it.
 
@@ -176,6 +214,15 @@ Execute the task list milestone by milestone. Discipline rules:
 - ❌ Vague commits or CHANGELOG placeholders
 - ❌ Declaring done while specs are still `open`
 - ❌ Publishing anything without the user's explicit go-ahead
+- ❌ Shipping a package without inspecting the packaged file list (`npm pack`)
+- ❌ Treating "no error" as "it worked" — malformed config is skipped **silently**
+- ❌ Verifying against a cached/stale install, or with an old duplicate still present
+- ❌ Guessing at a fix before reading the actual error message
+- ❌ Fixing a bug without adding a regression test
+- ❌ Claiming something was verified when it was assumed
+- ❌ 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
 
 ## References
 
@@ -184,4 +231,5 @@ Execute the task list milestone by milestone. Discipline rules:
 - `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/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

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

@@ -1,5 +1,9 @@
 # Phase 1 — Intake: Question Bank
 
+> **Scale note: this bank is for LARGE work.** Small work (small features, minor
+> bugfixes, small refactors) skips the questions — state understanding in 1–2
+> sentences and start. At most ONE clarifying question, only if genuinely ambiguous.
+
 Keep asking until the user confirms. One question at a time is fine; short batches (3–5) are faster. Do not proceed on guesses.
 
 ## Starter questions
@@ -32,3 +36,5 @@ Every concrete requirement the user states → `capture_spec` immediately, befor
 ## Intake gate
 
 Restate intent in 3–5 bullets, then ask: **"Is this correct?"** Only proceed on an explicit yes.
+
+> Large work only. Small work has no intake gate.

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

@@ -1,5 +1,9 @@
 # Phase 4 — Adversarial Analysis Checklist
 
+> **Scale note: the full checklist and gate apply to LARGE work.** Small work does
+> a quick mental pass on edge cases and failure modes while implementing — no
+> formal review, no user checkpoint.
+
 Challenge every spec and design decision like a hostile reviewer. For each item, determine: capture a new spec / supersede an existing one / accept the risk (recorded).
 
 ## Per-spec questions

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

@@ -1,5 +1,8 @@
 # Phase 5 — PLAN.md Template
 
+> **Scale note: this phase is for LARGE work only.** Small work skips PLAN.md and
+> the approval gate entirely — implement directly.
+
 Write `PLAN.md` in the project root. It must be executable by any competent engineer without re-deriving decisions.
 
 ```markdown
@@ -54,7 +57,7 @@ From adversarial analysis. Each risk: likelihood, impact, mitigation, owner.
 Explicitly cut items (so nobody re-adds them).
 ```
 
-## Approval gate (MANDATORY)
+## Approval gate (MANDATORY — large work only)
 
 Present the plan and ask:
 

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

@@ -0,0 +1,146 @@
+# Testing & QA Standard (MANDATORY)
+
+These rules are distilled from real failures in production sessions (pi-vigilant,
+pi-aia-asf, pi-aia-browser, conversense, betamaxx). Each rule exists because
+skipping it **shipped a broken artifact**. They are not optional.
+
+---
+
+## Rule 1 — Test the ARTIFACT you ship, not the source you wrote
+
+Source passing ≠ shipped thing working. The packaging layer is a real failure surface.
+
+> **Real failure:** `pi-aia-browser` 0.1.0. All source tests passed. But `package.json`
+> declared `"postinstall": "node scripts/install-browser.mjs"` while the `files`
+> allowlist omitted `scripts/`. The published tarball had no such file → every
+> `npm install` aborted with `MODULE_NOT_FOUND`. The package was **100% broken for
+> every user** while every source test was green.
+
+Required before declaring a package done:
+
+```bash
+npm pack                       # or the equivalent build
+tar tzf <pkg>-<ver>.tgz        # inspect the ACTUAL file list
+```
+
+- Verify every file the manifest/scripts reference is present in the list.
+- Extract to a clean temp dir and load/run it from there.
+- For anything installable: install it **from the registry/tarball**, not the repo.
+
+## Rule 2 — Assert the OBSERVABLE END STATE, not intermediate artifacts
+
+"Files are in the right place" and "config is correct" do not prove the feature works.
+
+> **Real failure:** the `aia-asf` skill. Files shipped correctly, `pi.skills` manifest
+> correct, description under the length limit — all intermediate checks passed. But the
+> YAML description contained an unquoted colon (`The flow is: classify...`), so the
+> frontmatter failed to parse and pi **silently skipped the skill**. It was invisible to
+> the agent even with an explicit `--skill` path.
+
+Ask: *what would the user observe?* Then assert exactly that.
+
+| Weak (intermediate) | Strong (observable) |
+|---|---|
+| SKILL.md exists, manifest lists it | Agent reports the skill as available |
+| Extension file present | Tool appears in the tool list and executes |
+| Server process running | Real request returns correct response |
+| Config contains the key | Behavior driven by the key actually changes |
+
+## Rule 3 — Probe for SILENT failures
+
+The worst bugs raise no error. Loaders skip malformed input; caches serve stale data.
+
+- After any config/manifest/frontmatter change, **verify it parsed** (parse it yourself).
+- Never treat "no error" as "it worked" — demand positive confirmation.
+- Validate machine-read files with a real parser, not by eyeballing:
+
+```bash
+python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]).read())" file.yaml
+node -e "JSON.parse(require('fs').readFileSync('f.json','utf8'))"
+```
+
+## Rule 4 — Read the ACTUAL error before changing anything
+
+> **Real failure:** on the `MODULE_NOT_FOUND` install error the first fix was a *guess*
+> at the `files` array. It happened to be right, but the reinstall still failed and the
+> real signal — `Cannot find module '.../scripts/install-browser.mjs'` plus a stale npm
+> cache — was sitting in the log the whole time.
+
+1. Find and read the real error (log file, stderr, exit code).
+2. State the root cause in one sentence.
+3. Only then edit.
+
+Never fix by pattern-matching on symptoms. Never retry unchanged and hope.
+
+## Rule 5 — Clean-room verification (defeat caches and local state)
+
+Your machine lies: caches, stale installs, leftover globals, symlinks.
+
+```bash
+npm cache clean --force
+cd $(mktemp -d) && npm install <pkg>@<version>   # fresh dir, explicit version
+```
+
+- Verify the **installed version** is the one you just published.
+- Remove/disable old copies first — a stale duplicate can serve your test and fake a pass.
+- Confirm *which* copy answered (distinct log path, version string, marker).
+
+> **Real failure:** a stale npm cache kept serving the broken 0.1.0 after 0.1.1 was
+> published; the install kept failing with an error already fixed.
+
+## Rule 6 — Every fixed bug gets a REGRESSION test
+
+A bug fixed without a test will return. For each fix, add an assertion that fails on
+the old code and passes on the new one, and keep it in the permanent suite.
+
+## Rule 7 — Test triggers AND non-triggers
+
+For anything conditional (skills, auto-activation, gates, hooks), correctness is
+two-sided. Half a test suite hides half the bugs.
+
+- **Triggers**: every case that must activate, activates.
+- **Non-triggers**: every case that must NOT activate, stays silent (Q&A, one-liners,
+  casual talk, unrelated domains).
+- **Boundaries**: the ambiguous cases — assert it asks rather than guesses.
+
+## Rule 8 — Test state machines for deadlock and bad transitions
+
+> **Real failure:** pi-vigilant gated a write on "all specs resolved", but the cooldown
+> suppressed that very write → permanent deadlock. Found only by simulating the full
+> multi-turn sequence.
+
+- Drive the real sequence of transitions, not one isolated call.
+- Check terminal states are reachable, and no state can block its own exit.
+- Test repeat/idempotent invocations and out-of-order calls.
+
+## Rule 9 — Browser testing is mandatory for any web surface
+
+API/curl checks do not replicate what a human sees. Via `pi-aia-browser`:
+
+1. `browser_init`, `browser_navigate` to the running app
+2. Walk each key user journey with real clicks/typing
+3. Assert rendered DOM content (`browser_dom`), not just HTTP 200
+4. Check console errors via `browser_js`
+5. `browser_screenshot` for the record; check mobile + desktop viewports
+
+A 200 response with a blank or broken page is a **failure**.
+
+## Rule 10 — Definition of done (all must hold)
+
+- [ ] Typecheck/build passes
+- [ ] Full test suite green (not a subset)
+- [ ] Regression test added for every bug fixed this cycle
+- [ ] Triggers **and** non-triggers tested for conditional behavior
+- [ ] Shipped artifact inspected (`npm pack` file list) and installed clean-room
+- [ ] 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`)
+- [ ] Unverifiable specs → `partial` + asked the user (never self-certified)
+
+## Rule 11 — Report honestly
+
+- Never claim a test passed that you did not run.
+- Never say "verified" for something inferred or assumed.
+- 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.