pi-aia-asf 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-11
+
+### Added
+
+- **Absolute wait ceiling — 30 minutes (06b Rule 15)** — no single wait may
+  exceed 30 min (1800s). Addresses the reported failure where tool calls waited
+  forever for the system to react and the whole process kept hanging,
+  especially during testing. The ceiling is a **backstop, never a substitute**
+  for a real per-call bound: a 30s suite still gets ~120s, and a lone 1800s
+  bound is treated as not having bounded anything. Hitting the ceiling means
+  kill the wait and diagnose the blocking cause — it is a bug signal, not
+  patience.
+- **Explicit per-run waiver** — the ceiling can be disabled, but only
+  deliberately and only for a **single run**: stated before running, with the
+  reason and a finite larger bound. A waiver does not persist, does not carry
+  over, and resets immediately afterwards. Blanket/standing waivers are
+  disallowed; repeated need for waivers is a setup defect to report (Rule 11).
+- **"Every waiting call carries its own explicit timeout"** — makes the rule
+  cover *every* tool call or command that waits on the system, not just the
+  obviously slow ones, with testing called out as the highest-risk area
+  (harnesses, servers, daemons, browsers hanging on ports, locks and prompts).
+  Bounds are sized from the stated expected duration with headroom.
+- New Definition-of-Done item for the ceiling; ceiling applies at **both
+  scales** (small work is not exempt).
+- **Durable test suite in `test/`** — the ASF suites were previously only in
+  `/tmp` and would have been lost. `npm test` now runs 67 checks (timeouts,
+  ceiling, delegation, docs-rule) against the real shipped skill text;
+  `test/setup.sh` prepares the jiti harness against the installed pi.
+
+### Verification
+
+- 67/67 checks pass (`npm test`): 13 timeouts, 17 ceiling, 19 delegation,
+  18 docs-rule.
+- The 17 new ceiling checks were confirmed to **fail 11/17 on the pre-change
+  text** before implementation, proving they assert real content.
+- SKILL.md YAML frontmatter re-verified as parsing (pi silently skips skills
+  with malformed frontmatter).
+
+
 ## [0.6.1] - 2026-08-28
 
 ### Removed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.6.1",
+  "version": "0.7.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",
@@ -31,7 +31,7 @@
     "clean": "echo 'nothing to clean'",
     "build": "echo 'nothing to build — pi loads .ts via jiti at runtime'",
     "check": "tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck --allowImportingTsExtensions --noCheck index.ts",
-    "test": "echo 'see https://github.com/brunoj/pi-aia-asf for test suites'",
+    "test": "./test/run-all.sh",
     "release": "./scripts/release.sh"
   },
   "pi": {

package/skills/aia-asf/SKILL.md

@@ -204,7 +204,7 @@ Execute the task list milestone by milestone. Discipline rules:
 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. **Silent async paths included**: ingest through the real flow and wait for the enrichment to land (06b Rule 9).
-6. **Bounded waits — ALWAYS (06b Rule 15)**: before any long-running command (package install, platform/test-harness startup, browser/daemon launch, full suite), **state the expected duration explicitly** and wrap it in a **hard timeout** (`timeout N …` or the tool's `timeout` parameter) — never run unbounded. If it exceeds the bound: kill it, diagnose what it is blocking on, fix the root cause. If the bound proves too short, raise it deliberately with a reason — never silently extend, never remove the bound. A 50,000-second hang is a failure to investigate, not patience.
+6. **Bounded waits — ALWAYS (06b Rule 15)**: **every** tool call or command that waits on the system gets an explicit, reasonable **hard timeout** (`timeout N …` or the tool's `timeout` parameter) — never run unbounded. State the expected duration first and size the bound to it with headroom (a 30s suite gets ~120s, not 3000s). This matters most **during testing**, where harnesses, servers, daemons and browsers hang on ports, locks and prompts. **Absolute ceiling: no single wait may exceed 30 min (1800s).** The ceiling is a backstop, never a substitute for the real per-call bound. When it is hit: kill the wait and diagnose what it is blocking on — that is a bug signal, not patience. The ceiling may be **waived only for a single run**, stated explicitly beforehand with a reason and a finite larger bound; the waiver **does not persist** and resets immediately after that run. A 50,000-second hang is a failure to investigate.
 7. **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.
 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.

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

@@ -147,6 +147,7 @@ never arrives, the wiring is dead — that is a failed test.
 - [ ] **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)
 - [ ] **Every long-running command ran under an explicit timeout with a stated expected duration (no unbounded waits)**
+- [ ] **No wait exceeded the 30 min (1800s) absolute ceiling — or it was explicitly waived for that single run, with a reason and a finite bound**
 
 ## Rule 11 — Report honestly
 
@@ -216,3 +217,54 @@ done — the wiring may be dead.
 - **A hang that outlives its expected duration is a failure to investigate,**
   not a wait to endure. If you cannot verify something within a bounded time,
   say so explicitly (Rule 11) instead of waiting indefinitely.
+
+### Every waiting call carries its own explicit timeout
+
+This applies to **every tool call or command that waits on the system** — not
+just the obviously slow ones. Testing is where this bites hardest: a test
+harness, dev server, daemon, browser launch, or watcher can block forever on a
+port, a lock, a prompt, or a process that never exits.
+
+- Shell: `timeout <seconds> <command>` — always.
+- Tool calls: pass the tool's explicit `timeout` parameter — always.
+- Pick the bound from the **stated expected duration**, with headroom. A test
+  suite you expect to take 30s gets ~120s, not 3000s.
+- "I'll just run it and see" is the failure mode this rule exists to prevent.
+
+### The absolute ceiling — 30 minutes, no exceptions unless explicitly waived
+
+> **Real failure (user report):** tool calls waited forever for the system to
+> react and the whole process kept hanging — especially during testing.
+
+**No single wait may exceed 30 minutes (1800s).** This is a hard ceiling, not a
+default and not a target:
+
+- **It is a backstop, not a substitute for a per-call bound.** The ceiling never
+  replaces the real timeout: a 30s suite still gets a ~120s bound. If your only
+  bound is 1800s, you have not bounded anything — you have deferred the hang.
+- **Never exceed it.** If a command genuinely needs longer, that is a signal to
+  restructure it (run it in the background and poll with bounded checks, split
+  it into stages, or reduce the work) — not to raise the number.
+- **When the ceiling is hit, kill the wait and diagnose.** Hitting 30 minutes is
+  a bug signal and a failure to investigate: find what it is blocking on
+  (network, lock, hung process, missing dependency, waiting on stdin) and fix
+  the root cause. Never re-run the same unbounded wait hoping for a different
+  result.
+
+**Explicit per-run waiver.** The ceiling can be disabled, but only deliberately
+and only for a **single run**:
+
+- The agent must **state it explicitly before running** — what is being run, why
+  it legitimately needs more than 30 minutes, and the new bound. For example:
+  *"Waiving the 30-min ceiling for this one run: full integration suite against
+  a cold container build, expected ~45 min, bound 3600s."*
+- A waiver covers **that one run only**. It **does not persist**, does not carry
+  over to the next command, and **resets immediately afterwards** — the next
+  wait is bounded by 30 minutes again.
+- A waiver still requires a **finite bound**. Waiving the ceiling means choosing
+  a larger explicit number, never running unbounded.
+- Blanket or standing waivers are not allowed. If waivers are needed repeatedly,
+  that is a defect in the setup — report it (Rule 11) instead of normalizing it.
+
+**Applies at both scales.** Small work is not exempt: a hang wastes the same
+time regardless of how the task was classified.