pi-aia-asf 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -7,13 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.9.0] - 2026-09-27
+## [0.9.2] - 2026-10-04
 
 ### Added
 
-- (describe changes for 0.9.0)
+- (describe changes for 0.9.2)
+
+
+## [0.9.1] - 2026-10-03
+
+### Fixed
+
+- **Extension no longer loads on pi >= 1.0** — pi 1.0 changed the command
+  contract to `registerCommand(name, { description, handler })`, where
+  `handler(args: string, ctx)` returns void and user-visible output goes
+  through `ctx.ui.notify()`. `/asf` and `/asf-approve` were registered as bare
+  functions taking `(args: string[], ctx)` and returning their text, so pi
+  1.0.1 refused to load the package at all:
+  `Command "/asf" registered by extension ".../index.ts" must define handler()`.
+  Both commands now use the options-object form; the argument string is split
+  into subcommand + flags and every gate report is notified. Subcommand
+  behaviour is unchanged.
+
+### Tests
+
+- The test harness mock now enforces the real `RegisteredCommand` contract
+  (it accepted any shape before, which is how this shipped) and exposes
+  `invokeCommand()`, which calls a registered command exactly as pi does and
+  captures `ctx.ui.notify()` output.
+- New `test/test-command-contract.mjs` (16 checks): contract enforcement with a
+  negative control, arg-as-string parsing, case-insensitive subcommands,
+  void return, notify-based output, no bare-function registration left.
 
 
+## [0.9.0] - 2026-09-27
+
 ### Added
 
 - **Indexed reference structure (P-index)** — SKILL.md now carries a reference

package/index.ts

@@ -271,7 +271,14 @@ export default function register(pi: ExtensionAPI): void {
     return state.current ? `ASF phase → ${phase}${workType ? ` (${workType})` : ""}` : "ASF session ended.";
   };
 
-  pi.registerCommand("asf", async (args: string[], ctx: ExtensionCommandContext) => {
+  // pi >= 1.0 contract: registerCommand(name, { description, handler }) where
+  // handler receives the raw argument STRING and returns void — output goes to
+  // ctx.ui.notify(). The command body stays a string-returning function so the
+  // gate text is testable without a UI.
+  const runAsf = async (
+    args: string[],
+    ctx: ExtensionCommandContext,
+  ): Promise<string> => {
     const sub = (args[0] || "").toLowerCase();
 
     switch (sub) {
@@ -420,10 +427,20 @@ export default function register(pi: ExtensionAPI): void {
           dependencySummary()
         );
     }
+  };
+
+  pi.registerCommand("asf", {
+    description:
+      "Agentic Software Factory — /asf new|feature|bugfix|refactor|small|status|verify|health|abort",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const argv = args.trim() ? args.trim().split(/\s+/) : [];
+      const out = await runAsf(argv, ctx);
+      if (out) ctx.ui.notify(out, "info");
+    },
   });
 
-  // Plan-approval helper: /asf approve marks the plan as approved (records Gate 5)
-  pi.registerCommand("asf-approve", async (_args: string[], ctx: ExtensionCommandContext) => {
+  // Plan-approval helper: /asf-approve records Gate 5 approval (requires PLAN.md)
+  const runApprove = async (ctx: ExtensionCommandContext): Promise<string> => {
     const project = projectName();
     const state = await loadState(project);
     if (!state.current) return "No active ASF session — start one with /asf new|feature|bugfix|refactor.";
@@ -447,5 +464,12 @@ export default function register(pi: ExtensionAPI): void {
       "Test-first, strict codebase isolation, regression test per bug fixed.\n" +
       "Run /asf verify before delivery."
     );
+  };
+
+  pi.registerCommand("asf-approve", {
+    description: "Record Gate 5 plan approval (requires PLAN.md) and begin implementation",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      ctx.ui.notify(await runApprove(ctx), "info");
+    },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",

package/skills/aia-asf/SKILL.md

@@ -199,6 +199,13 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > bloat), split it by topic and keep the parent as an index — never let it grow until
 > editing breaks.**
 
+> **Read `references/06i-completeness.md` before implementing, and again before claiming
+> done.** Ship the real thing or say out loud what is not real: no `// TODO` /
+> not-implemented paths on a user-reachable code path, no fake or seed data the user will
+> read as their own, no invented facts presented as checked, no silently deferred scope,
+> no built-but-never-wired module. A stub is legitimate only when the user asked for one
+> — and then it is declared, never silent.
+
 > **Read `references/06d-delegation.md` before delegating.** Work may be delegated two ways:
 > **intercom** (message another live pi session that owns relevant context — always `list`
 > first, say what you want back, and treat their findings as evidence, not proof; **optional** —
@@ -228,6 +235,7 @@ Execute the task list milestone by milestone. Discipline rules:
 8. **CHANGELOG discipline**: every user-visible change gets a CHANGELOG entry describing exactly what changed (no placeholder text).
 9. **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.
 10. **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.
+11. **No stubs, no fake data, no invented facts (`references/06i-completeness.md`)**: the deliverable is the real implementation. Finish it, or state the discrepancy plainly to the user — what is missing, why, what remains. Never let the user discover the gap by using the product.
 
 ---
 
@@ -239,6 +247,8 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 
 Also check the **stability DoD** (`references/06f-stability.md`): if the deliverable makes external calls, it has timeouts and bounded retries (idempotent only). And the **security DoD** (`references/06h-security.md`): no secrets in the repo, no untrusted input reaches a shell/query/path unvalidated, no unbounded resource use on user-controlled input; for agent-like tool surfaces, every tool is least-privilege with an abuse-case test.
 
+Also check the **completeness DoD** (`references/06i-completeness.md`): no stub, placeholder, unimplemented path or fabricated data left on a user-reachable path (or declared to the user with the reason); every part of the ask reachable from where the user enters it, with the exercising command/request/action named in the delivery report; nothing asked for quietly moved to "later"; no claim presented as verified when it was not. `pi-vigilant` scans the changed files for these markers at completion — resolve every finding or explain it; a clean scan is not proof of completeness.
+
 **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.
 
 **Independent reviewer gate (large work, P19):** before delivery, run the
@@ -259,8 +269,8 @@ conflicts). Record the review + triage in the delivery report.
 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): **check the release policy** — read `.asf-release.json` at the project root if present (see `references/07-release.md`). It defines **when** (user-stated conditional rules: "when X is true, publish automatically; when Y is true, do this…") and **how** (instructions the ASF drives with judgment — credentials, git sync, publish steps). If the policy authorizes automatic publishing for the current state, drive the release per `how`; otherwise **offer** to run the release and get explicit approval (the default stance: publishing is the user's decision). **Always test on publish / in production, if applicable** — verify the shipped artifact from the registry / smoke-test prod, never assume it works. 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.
+5. If the project is a library/package that the user publishes (npm, GitHub release): **check the release policy** — read `.asf-release.json` at the project root if present (see `references/07-release.md`). It defines **when** (user-stated conditional rules: "when X is true, publish automatically; when Y is true, do this…") and **how** (instructions the ASF drives with judgment — credentials, git sync, publish steps). If the policy authorizes automatic publishing for the current state, drive the release per `how`; otherwise **offer** to run the release and get explicit approval (the default stance: publishing is the user's decision). **Always test on publish / in production, if applicable** — verify the shipped artifact from the registry / smoke-test prod, never assume it works. Optionally offer to set up a CI/CD pipeline for publishing.
+6. Present a completion summary: what was built, specs met, tests passing, how to use it.
 
 ---
 
@@ -298,6 +308,12 @@ conflicts). Record the review + triage in the delivery report.
 - ❌ 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)
+- ❌ A `// TODO`, `not implemented`, empty handler or `coming soon` on a user-reachable path — that is an absent feature wearing a name
+- ❌ Fake, seed, demo or lorem-ipsum data on a path the user reads as their own
+- ❌ An invented API signature, config key, endpoint, version or limit stated as fact — verify it or mark it unverified
+- ❌ Quietly deferring part of the ask ("v1 does X") instead of finishing it or telling the user
+- ❌ Presenting a stub as complete because the tests written against it pass
+- ❌ Leaving a deliberate stub unexplained — if the user asked for a scaffold, say so in the report
 - ❌ 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
@@ -329,6 +345,7 @@ reads at most 06b + 06c; large work reads the ones its phase calls for.
 | `06f-stability.md` | stability patterns + error handling + observability (P06/P07/P08) | **if the deliverable makes external calls or is a service** |
 | `06g-test-design.md` | risk-based test derivation + determinism | Phase 6 large (test plan) / non-trivial tests |
 | `06h-security.md` | threat model, ASVS DoD, supply chain, agent tools | Phase 4/5 large; small = one line |
+| `06i-completeness.md` | **mandatory** no stubs / no fabricated data / no invented facts + completeness DoD | before implementing and before claiming done (always) |
 | `07-release.md` | release workflow + **configurable release policy** (`.asf-release.json`: when/how) + test-on-publish | before publishing |
 
 ## ASF self-modification policy (P22)

package/skills/aia-asf/references/06i-completeness.md

@@ -0,0 +1,67 @@
+# Completeness — no stubs, no fabricated data, no invented facts
+
+**Read when:** before writing implementation, and again before claiming done — for
+every deliverable with real behaviour. **Skip when:** never. Small work needs only
+the Core rule and the DoD checklist at the bottom.
+
+Newer models can produce work that *looks* finished: a function with the right name
+whose body is a placeholder, a screen populated with invented records, a report that
+cites a limit nobody checked. Green tests do not disprove it — the tests were written
+against the stub. This reference is the standing answer.
+
+## Core rule
+
+**Ship the real thing, or say out loud what is not real.**
+
+Complete means: the user can use what they asked for, through the entry point they
+will actually use. Not: the files exist, the suite is green, the shape looks right.
+There is no third option — an undeclared gap is a defect, however tidy it looks.
+
+## Never ship silently
+
+| Pattern | Why it is a lie |
+|---|---|
+| `// TODO`, `FIXME`, `not implemented`, `coming soon`, `pass`, empty handler, `throw new Error("not implemented")` on a user-reachable path | The feature is absent; the name says it is present |
+| Fake / seed / demo data on a user path — hardcoded users, invented prices, lorem ipsum, `example.com`, `+1 555-…`, `dummy`/`fake`/`sample` records | The user reads invention as their own data |
+| Invented facts presented as checked — API signatures, config keys, endpoints, version numbers, limits, quotas | Confidence without verification is the expensive kind of wrong |
+| Silently deferred scope — "v1 covers X" when X+Y was asked | A stub with better marketing |
+| Built-but-never-wired — the module exists and is tested, but nothing calls it, no route reaches it, no surface consumes it | The user cannot get to the feature at all |
+| Mocks or fakes in production code paths | Test seams belong at test seams (06b) |
+| A config/env value the code reads but nothing sets, or a key the code never reads | The switch does nothing |
+
+## Legitimate exceptions — declared, never silent
+
+1. **The user asked for it**: a scaffold, spike, stub, mock or placeholder was the
+   requested deliverable. Keep it, and state in the delivery report that it is
+   deliberate and what it stands in for.
+2. **An approved deferral**: a scope conflict, missing credential, or external
+   dependency stopped part of the work. Record it as an open item: what is missing,
+   why, what remains.
+3. **A fake at a test seam**: legitimate, and stays out of shipped paths.
+
+Anything else: **finish it.** If it cannot be finished in this run, the discrepancy
+goes in the final message in plain words — never discovered by the user through use.
+
+## Prove it is real (Phase 7)
+
+- **Exercise each part through the entry point the user will use** — the CLI command,
+  the HTTP request, the UI action, the installed package — and name that action in the
+  delivery report. "Implemented the export endpoint" is a claim; "`curl -s
+  localhost:3000/export.csv` returned 412 rows" is evidence.
+- **Data-shaped output**: show one real record end to end. If data is seeded, label it
+  seeded and say where the real source plugs in.
+- **Factual claims**: cite where verified (doc URL, tool output, schema, measured run)
+  or mark it unverified. Never launder an assumption into a statement of fact.
+- **The host audits you**: `pi-vigilant` scans the files this session changed for
+  stub / fabricated-data / fact-hole markers and puts the findings in front of you at
+  completion. Resolve every finding or explain it — and a clean scan is *not* proof of
+  completeness: deferral and wiring remain your check, not the scanner's.
+
+## Definition of Done — completeness
+
+- [ ] No stub, unimplemented path, placeholder or fabricated data remains on a
+      user-reachable path — or it is declared to the user with the reason.
+- [ ] Every part of the ask is reachable from where the user enters it; the delivery
+      report names the command / request / action that exercised each part.
+- [ ] Nothing asked for was quietly moved to "later" without the user being told.
+- [ ] No claim in the deliverable or the report is presented as verified when it was not.