pi-aia-asf 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,11 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-28
+
+### Added
+
+- **Delegation reference `references/06d-delegation.md`** — codifies the two
+  delegation mechanisms available to ASF work: **intercom** (message another
+  live pi session that owns relevant context — `list` first, say what you want
+  back, treat peer findings as evidence, not proof) and **subagents** (spawn an
+  isolated `pi -p` process when the OUTCOME matters more than the trace — scoped
+  codebase research, independent parallel fixes, fresh-perspective review).
+- **Two verified hard limits, backed by experiment** (both documented as
+  anti-patterns in SKILL.md):
+  - **Never run parallel subagents against the same file.** Tested: 4 concurrent
+    whole-file writers left only 1 of 4 edits, silently, all exiting 0 — the
+    no-mutual-dependencies rule is enforced by physics, not preference.
+  - **Exit code 0 does not mean success.** Tested: a subagent asked to read a
+    non-existent file exited 0. Always validate the returned output.
+- **`pi-intercom` as a declared dependency** (`dependencies` in package.json,
+  `^0.10.1`) — `npm install` pulls it in. Intentionally **not bundled**: a
+  bundled copy conflicts with a top-level `pi install npm:pi-intercom`
+  (tool-name collision, verified), so the tool must be installed top-level to
+  register. Added to the ASF runtime dependency check (`/asf` summary now lists
+  all five: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser,
+  pi-intercom).
+- **SKILL.md wiring** — Phase 6 delegation note, reference index entry, and
+  three new anti-patterns (same-file parallel subagents, trusting subagent exit
+  codes/self-reports, re-deriving context another live session already has).
+
+### Changed
+
+- README dependencies table now lists pi-intercom with the not-bundled rationale.
+
 ## [0.3.0] - 2026-08-25
 
 ### Added
 
-- (describe changes for 0.3.0)
+- **Mechanical spec-to-code traceability gate in `/asf verify`** (large work
+  only) — reads the shared spec-memory task and validates every `met` spec's
+  trace (`outcome → codePath → testFile + assertion`); `testFile` must exist
+  and `assertion` must appear in it. Outputs a traceability matrix with
+  PASS/FAIL rows and refuses delivery on FAIL (`GATE NOT PASSED`). Small work
+  keeps the checklist only — no mechanical gate (scale proportionality).
+- **New QA rules (06b-testing-qa.md)**: Rule 12 — test the operator-facing
+  outcome, not the machinery (Betamaxx dead-code failure); Rule 13 — nothing
+  is delivered until consumed by a surface (UI or API); Rule 14 — every
+  feature spec ships an E2E behavioral test through the real entry point.
+  Rule 9 extended for silent async paths; Rule 10 DoD extended (traceability,
+  consumed-by-surface, E2E).
+- **M4 — challenge approved designs during implementation** (06-implementation.md):
+  product tension → resolve with the user before implementing.
+- **M5 — the delivery log is a claim; the code is the evidence**: trace the
+  actual code path before marking anything delivered.
+- **M6 — external planning docs are specs, not ground truth** (01-intake.md +
+  SKILL.md Phase 1/3): locate IMPROVEMENT-PLAN.md / PLAN.md / requirements
+  docs / delivery logs / tickets, ingest every actionable item as a captured
+  spec; their ✅ markers are claims, not evidence.
+- **Adversarial traceability lens** (04-adversarial.md): operator-facing
+  outcome + code path + where dead wiring hides.
+- **PLAN.md traceability matrix** (05-plan.md): spec → outcome → code path →
+  test.
+- DoD checklist extended; anti-patterns added (delivery-log trust, machinery
+  without a surface, unit tests as wiring proof, external plan checkmarks,
+  literal implementation of tension-creating specs).
+
+### Changed
+
+- `/asf verify` output now shows scale and, for large work, the mechanical
+  traceability matrix before the DoD checklist.
+
+### Requires
+
+- pi-vigilant 0.1.3+ (provides the `trace` field on specs).
 
 
 ## [0.2.2] - 2026-08-14

package/README.md

@@ -41,6 +41,9 @@ You can also force/start a session explicitly:
 | **pi-smart-web-search** | `web_search` | `pi install npm:pi-smart-web-search` |
 | **pi-smart-fetch** | `web_fetch`, `batch_web_fetch` | `pi install npm:pi-smart-fetch` |
 | **pi-aia-browser** | `browser_init`, `browser_navigate`, … (Playwright + Chromium, auto-installed) | `pi install npm:pi-aia-browser` |
+| **pi-intercom** | `intercom` — message other live pi sessions directly (delegation, cross-session verification) | `pi install npm:pi-intercom` |
+
+`pi-intercom` is also declared in `dependencies` in `package.json`, so `npm install` of this package pulls it in. It is intentionally **not bundled** into the tarball: bundling it would conflict with a top-level `pi install npm:pi-intercom` (tool name collision), so the tool must be installed at top level to register.
 
 The extension warns at startup (and on `/asf` with no args) when any dependency is missing.
 

package/index.ts

@@ -215,6 +215,12 @@ function checkDependencies(): DependencyCheck[] {
         existsSync(join(gitDir, "github.com", "brunoj", "pi-aia-browser")),
       hint: "pi install npm:pi-aia-browser (installs Playwright + Chromium)",
     },
+    {
+      name: "pi-intercom (intercom: message other pi sessions)",
+      package: "pi-intercom",
+      present: existsSync(join(npmDir, "pi-intercom")),
+      hint: "pi install npm:pi-intercom",
+    },
   ];
 
   return checks;
@@ -224,7 +230,7 @@ function dependencySummary(): string {
   const checks = checkDependencies();
   const missing = checks.filter((c) => !c.present);
   if (missing.length === 0) {
-    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser ✓";
+    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser, pi-intercom ✓";
   }
   return (
     "⚠️ ASF dependencies missing — install before starting a project:\n" +

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-aia-asf",
-  "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.",
+  "version": "0.4.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, pi-aia-browser, and pi-intercom.",
   "keywords": [
     "pi-package",
     "software-factory",
@@ -48,6 +48,9 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
+  "dependencies": {
+    "pi-intercom": "^0.10.1"
+  },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
       "optional": false

package/skills/aia-asf/SKILL.md

@@ -182,6 +182,15 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > understand; layered with clear boundaries and an architecture writeup; full I/O debug
 > logging with replay; nothing breaks existing functionality.
 
+> **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), and
+> **subagents** (spawn an isolated `pi -p` process when the OUTCOME matters more than the
+> trace — scoped codebase research, independent parallel fixes, fresh-perspective review).
+> Two verified hard limits: **never run parallel subagents against the same file** — tested,
+> 4 concurrent writers left only 1 of 4 edits, silently, all exiting 0 — and **exit code 0
+> does not mean success**, so always validate the returned output against what you asked for.
+
 Execute the task list milestone by milestone. Discipline rules:
 
 1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
@@ -246,6 +255,9 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - ❌ 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`)
+- ❌ Running parallel subagents that touch the same file — edits are silently lost (see `references/06d-delegation.md`)
+- ❌ Trusting a subagent's exit code or self-report instead of verifying the actual code/test result
+- ❌ Re-deriving context another live session already has instead of asking it over intercom
 - ❌ 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)
@@ -262,4 +274,5 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - `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/06d-delegation.md` — **intercom & subagents**: when to message another session, when to spawn isolated workers, the no-mutual-dependencies rule, and why exit codes lie
 - `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

package/skills/aia-asf/references/06d-delegation.md

@@ -0,0 +1,130 @@
+# Delegation: Intercom & Subagents
+
+ASF work does not have to happen in one session, in one context window, or one task at a time. Two delegation mechanisms are available. They solve different problems and must not be confused.
+
+| | **Intercom** | **Subagents** |
+|---|---|---|
+| What it is | Messaging between *live pi sessions* | Spawning a *fresh, isolated pi process* |
+| Peer | A human-driven or long-running session with its own context and history | A stateless worker that exits when done |
+| You get back | A conversation (peer can push back, ask, disagree) | One result |
+| Use when | Another session owns the context/decision | You want the OUTCOME, not the trace |
+| Cost | Cheap (a message) | A whole context window + model spend |
+
+---
+
+## Part 1 — Intercom: passing messages to other sessions
+
+Other pi sessions on this machine are often working on directly relevant things: the same monorepo, an adjacent service, the package you depend on. **Use intercom to talk to them directly instead of guessing, duplicating their work, or routing everything through the user.**
+
+### When to use intercom
+
+- **Another session owns the context.** They have the repo loaded, the failure reproduced, the domain knowledge. Ask them rather than re-deriving it.
+- **Your change affects their work.** You changed a shared interface, published a version, moved a file they depend on. Tell them.
+- **You need independent verification.** A second session reproducing your result is stronger evidence than your own re-run (see 06b Rule 11).
+- **Cross-project coordination.** Your package is their dependency; sequencing matters.
+- **You found something they need to know.** A bug in shared code, a broken assumption, a security issue.
+
+### How
+
+```
+intercom({ action: "list" })                                  // who is live
+intercom({ action: "send", to: "<name-or-id>", message: "…" }) // fire-and-forget
+intercom({ action: "ask",  to: "<name-or-id>", message: "…" }) // wait for a reply
+```
+
+Target by session name, full ID, or the short id in parentheses from `list`. Use `cwd` to scope to a directory when two sessions share a name.
+
+### Rules
+
+1. **`list` before you send.** Don't message a session that isn't live.
+2. **Say what you want back.** "Please verify X and reply with the result" beats "FYI X."
+3. **Give them what they need to act** — file paths, repro commands, exact error text. Assume zero shared context.
+4. **`ask` blocks; `send` doesn't.** Use `ask` only when you genuinely need the answer before continuing.
+5. **Hand over your weak points, not just your conclusions.** If you want a peer to verify, tell them what you did *not* test and what you'd most like broken. A peer who only receives conclusions will rubber-stamp them.
+6. **Their findings are evidence, not proof.** An independent reproduction is strong; an unverified claim from a peer is still a claim (06b Rule 12, and M5: the log is a claim, the code is the evidence).
+7. **Don't leak the user's private context** across projects without reason.
+
+---
+
+## Part 2 — Subagents: delegating for the outcome
+
+A subagent is a **fresh `pi` process with its own context window**. It takes a task, works independently, returns a result, and exits. The parent context never sees its intermediate tool calls — only the answer.
+
+> **Core principle: subagents are context isolation, not role-play.** The point is to keep 5,000 lines of grep/read output out of the parent context, not to create "personas."
+
+### When to spawn a subagent
+
+Spawn when **the outcome matters more than the trace**:
+
+- **Scoped codebase research.** "Which module owns retry logic, and what's its interface?" The search noise is worthless once the answer exists. *Signal: gathering the answer means reading many files.*
+- **Independent small changes with NO MUTUAL DEPENDENCIES.** Three unrelated files each needing the same mechanical fix — run them in parallel.
+- **Fresh-perspective review.** A reviewer that never saw your reasoning catches what familiarity hides. Especially valuable for challenging an approved design (06-implementation M4).
+- **Bounded, noisy verification.** Running a long test matrix and reporting just the failures.
+
+**Rule of thumb:** if the task needs exploring many files, or there are 3+ genuinely independent pieces of work, delegate.
+
+### When NOT to spawn a subagent
+
+- **Sequential/dependent work.** If step 2 needs step 1's full output, one context is cleaner than a relay.
+- **Anything touching the same file.** See the hard evidence below.
+- **Small tasks.** Delegation overhead exceeds the benefit. Just do it.
+- **Work needing judgment you'd have to fully specify anyway.** If writing the task description costs more than doing the work, do the work.
+- **The core implementation of a gated (LARGE) change.** You own the specs and the traceability. Delegate research and isolated fixes around it, not the spec-carrying work itself.
+- **Nested delegation.** A subagent must not spawn subagents. Keep the tree one level deep.
+
+### ⚠️ The no-mutual-dependencies rule is not advisory — it is enforced by physics
+
+**Verified experimentally.** Four subagents were told to each change a different key in the *same* file, reading it and writing the complete file back:
+
+```
+before: { a: 1, b: 2, c: 3, d: 4 }   → 4 agents, one key each
+after:  { a: 1, b: 2, c: 3, d: 99 }  → 1 of 4 edits survived
+```
+
+**Three edits were silently lost.** Every agent reported success. Every process exited 0. There was no error, no conflict marker, no warning — just a file that quietly lost 75% of the intended work.
+
+Concurrent agents each read a snapshot and write back a whole file; last writer wins. Therefore:
+
+- **Never run parallel subagents against the same file.** Partition by file, and state the partition in each task.
+- If two tasks *might* touch the same file, they are dependent — **run them sequentially or do them yourself**.
+- Independence must be verified before spawning, not assumed. If you cannot name the disjoint file set, you do not have independence.
+
+### ⚠️ Exit code 0 does NOT mean the task succeeded
+
+**Verified:** a subagent asked to read a non-existent file explained the problem conversationally and **exited 0**.
+
+Never treat process exit status as the success signal. **Validate the returned output against what you asked for.** If a subagent was supposed to change code, verify the code changed — read the file, run the test. This is the delegation-shaped instance of M5: *the report is a claim; the code is the evidence.*
+
+### How to spawn
+
+There is **no built-in subagent tool in pi** — this is deliberate ("no sub-agents" is a stated design choice; you compose it yourself). Two supported routes:
+
+**1. Direct subprocess (always available, zero install):**
+
+```bash
+pi -p "<task>" --no-extensions --no-skills -t read,grep,find,ls
+```
+
+Run several in the background and `wait` for them to parallelize.
+
+**2. A subagent extension** (e.g. the `subagent/` example shipped with pi, or a package providing agent orchestration) — gives streaming output, parallel/chain modes, and usage tracking. Prefer this when available; fall back to `pi -p`.
+
+### Rules for spawning
+
+1. **Restrict tools to the job.** Research agents get read-only (`-t read,grep,find,ls`). Never hand write access to a task that only needs to look.
+2. **Use `--no-extensions --no-skills` for research.** Faster, cheaper, and it prevents a subagent from writing to shared state (specs, feedback) that belongs to the parent task.
+3. **Specify the output format.** "Return: file path, function name, and the 3-line interface — nothing else." Unspecified output returns an essay.
+4. **Bounded, stateless, single-responsibility.** A subagent that needs prior conversation is the wrong tool.
+5. **Partition writes by file** and say so explicitly in every parallel task.
+6. **Verify the result yourself** (see exit-code warning). For code changes: read the file or run the test.
+7. **Cap the fan-out.** A handful of parallel agents, not dozens; each costs a full context window.
+8. **One level deep.** No nesting.
+
+### Interaction with ASF gates
+
+Delegation changes **who does the work**, never **what must be proven**:
+
+- Specs, traceability, and the `/asf verify` gate remain the **parent's** responsibility. A subagent cannot discharge a spec.
+- The QA standard (06b) applies to delegated work identically. "A subagent did it" is not evidence.
+- Subagent findings enter the record as **claims** until verified against code or tests.
+- For LARGE work, the approval gate is unaffected: no subagent may start implementation before plan approval.