pi-aia-asf 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **The `aia-asf` skill was never loaded.** Its YAML frontmatter description contained an unquoted colon (`The flow is: classify the work...`); a colon followed by a space starts a mapping in YAML, so the frontmatter failed to parse and pi silently skipped the skill. The extension's `/asf` commands worked, but the workflow skill itself was unavailable. The description is now a YAML block scalar with no inline colon.
+
+
 ### Added
 
 - Initial release of the Ai Applied Agentic Software Factory.

package/index.ts

@@ -38,6 +38,19 @@ interface AsfState {
   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 }>;
@@ -203,6 +216,21 @@ export default function register(pi: ExtensionAPI): void {
           `  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:
@@ -213,6 +241,7 @@ export default function register(pi: ExtensionAPI): void {
           "  /asf bugfix     — major bugfix\n" +
           "  /asf refactor   — architectural refactor\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 +253,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.0",
+  "version": "0.2.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

@@ -1,6 +1,18 @@
 ---
 name: aia-asf
-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 is: classify the work, ask questions until the intent is clear, research SOTA and existing 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 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.
+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.
 ---
 
 # AIA Agentic Software Factory (ASF)
@@ -133,9 +145,19 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 
 ## 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.
@@ -147,8 +169,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.
 
@@ -164,6 +195,12 @@ 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
 
 ## References
 
@@ -172,4 +209,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/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.