pi-aia-asf 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-28
+
+### Added
+
+- **06c Rule 9 — Documents are code: refactor them when they outgrow
+  editability** (new mandatory rule, Ai Applied tenet): when a document starts
+  causing writing/editing issues (edit-tool matching failures, truncation,
+  multi-topic bloat, every change touching the same big file), it is time to
+  refactor it — split by topic, keep the parent as an index/map, keep
+  cross-references exact, preserve content (Rule 8 applied to documents),
+  verify, and refactor before it hurts rather than after.
+- **Wiring**: 06c "Where this applies" (Phase 6 + Phase 7), 06c anti-patterns
+  (letting a document grow until edits break; wall-of-prose SKILL.md), SKILL.md
+  Phase 6 note, Phase 7 modularity DoD (documents too), SKILL.md anti-pattern,
+  and the reference index (now 9 rules).
+
+## [0.5.0] - 2026-08-28
+
+### Added
+
+- **06b Rule 15 — bound every long-running operation** (new mandatory QA rule):
+  state the expected duration before running any long command (package installs,
+  platform/test-harness startup, browser/daemon launches, full suites); ALWAYS
+  wrap it in a hard timeout (`timeout N …` / tool timeout parameter); exceeding
+  the bound is a bug signal — kill and diagnose the root cause; if the bound
+  proves too short, raise it deliberately with a reason. Rooted in the user
+  report of package hangs lasting up to 50,000 seconds with the agent waiting
+  idle. Added to the Rule 10 definition-of-done checklist.
+- **SKILL.md discipline rule 6 — Bounded waits — ALWAYS** (renumbered rules
+  7–10): the same rule at the phase level, with the 50,000-second hang as the
+  anti-example.
+- **07-release.md**: "Verify first" step now requires every long-running
+  verification command to have run under an explicit timeout with a stated
+  expected duration.
+
 ## [0.4.0] - 2026-08-28
 
 ### Added

package/package.json

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

package/skills/aia-asf/SKILL.md

@@ -180,7 +180,10 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > SSOT); no hardcoding (config-driven); **testable outside the host then integrated
 > verbatim** (same modules in tests and production); refactor what is too complex to
 > understand; layered with clear boundaries and an architecture writeup; full I/O debug
-> logging with replay; nothing breaks existing functionality.
+> logging with replay; nothing breaks existing functionality. **Documents are code too
+> (Rule 9): when a document outgrows editability (failing edits, truncation, multi-topic
+> bloat), split it by topic and keep the parent as an index — never let it grow until
+> editing breaks.**
 
 > **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`
@@ -200,10 +203,11 @@ 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. **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.
-7. **CHANGELOG discipline**: every user-visible change gets a CHANGELOG entry describing exactly what changed (no placeholder text).
-8. **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.
-9. **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.
+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.
+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.
+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.
 
 ---
 
@@ -211,7 +215,7 @@ Execute the task list milestone by milestone. Discipline rules:
 
 Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule 10). Every box must hold.
 
-Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green.
+Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green. **Documents too (06c Rule 9)**: no document so large that editing it is fragile — if a doc you worked on started causing edit failures/truncation, it was refactored (split by topic, parent kept as index, cross-references updated).
 
 **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.
 
@@ -255,6 +259,7 @@ 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`)
+- ❌ Letting a document grow until edits start breaking instead of splitting it (06c Rule 9)
 - ❌ 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
@@ -273,6 +278,6 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - `references/05-plan.md` — PLAN.md template with examples (incl. spec-to-code traceability matrix)
 - `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/06c-code-quality.md` — **mandatory modularity & maintainability standard** (9 rules, SSOT, testable-standalone, single escalation path, documents-are-code)
 - `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/06b-testing-qa.md

@@ -146,6 +146,7 @@ never arrives, the wiring is dead — that is a failed test.
 - [ ] **Consumed by a surface: every delivered feature's output is visible in the product (UI or API) — nothing ships as dead machinery**
 - [ ] **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)**
 
 ## Rule 11 — Report honestly
 
@@ -194,3 +195,24 @@ done — the wiring may be dead.
 - **Scale note:** mandatory for feature specs in **large/gated work**. For small
   work, required only when the change touches a surface/wiring; otherwise the
   standard test-first rules above suffice.
+
+## Rule 15 — Bound every long-running operation: state the expected duration, then enforce it
+
+> **Real failure (user report):** package installs / platform startups / test
+> harnesses hung for up to **50,000 seconds** while the agent waited, doing
+> nothing. An unbounded wait is not patience — it is a silent stall.
+
+- **State the expected duration before running.** "This install should take
+  ~2 min", "first platform startup ~10 min", "suite ~3 min". The expectation is
+  part of the command, not an afterthought.
+- **ALWAYS wrap it in a hard timeout** — `timeout 300 …` for shell commands, an
+  explicit `timeout` parameter for tool calls. Never run unbounded.
+- **Exceeding the bound is a bug signal, not a slow command.** Kill it and
+  diagnose immediately: what is it blocking on (network, lock, hung process,
+  missing dependency, waiting for input)? Fix the root cause.
+- **If the bound proves too short, raise it deliberately** — state the new
+  expectation and the reason ("first-time platform startup needs 10 min;
+  bound raised to 900s"). Never silently extend, never remove the bound.
+- **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.

package/skills/aia-asf/references/06c-code-quality.md

@@ -141,6 +141,38 @@ existing functionality. Each rule below carries the lesson.
 - This is the SSOT/refactor safety net: refactoring restructures *structure*,
   never *behavior*.
 
+## Rule 9 — Documents are code: refactor them when they outgrow editability
+
+> *"Whenever documents you work on become so big that they start causing
+> writing / editing issues, it's time to refactor them."* — Ai Applied tenet
+
+A document that is too big to edit safely is a **maintainability bug**, not a
+fact of life. The same triggers that say "extract a module" for code say
+"split this document" for docs:
+
+- **Edit-tool failures**: `oldText` matching starts failing or needs huge
+  context; edits become fragile and overlapping.
+- **Truncation**: the file approaches context limits; reads get cut off;
+  you can no longer see the whole document.
+- **Multi-topic bloat**: one file covers several distinct subjects (e.g. a
+  SKILL.md that has grown into a wall of prose instead of a map).
+- **Every change touches the same big file**: constant conflict risk, slow
+  review, no single place to look.
+
+**The refactor pattern (documents):**
+
+1. **Split by topic** — one subject per document (like one responsibility per
+   module). Move detail into focused references; keep the parent as an
+   **index/map** that points to them.
+2. **Keep cross-references exact** — every pointer to the old content is
+   updated; nothing dangles.
+3. **Preserve content** — a doc refactor moves text, it does not rewrite or
+   drop it (Rule 8 applied to documents).
+4. **Verify** — re-read the split docs, confirm every referenced rule/topic
+   still exists and is reachable, and that the frontmatter/format stays valid.
+5. **Refactor before it hurts, not after** — if you notice edit friction
+   starting, that is the moment. Do not wait for a broken edit.
+
 ---
 
 ## Where this applies in ASF
@@ -152,11 +184,14 @@ existing functionality. Each rule below carries the lesson.
   their boundaries, the one-way dependencies, where shared truth lives, and
   how each module is tested standalone.
 - **Phase 6 (implementation)**: apply Rules 1–8 as you build; extract modules
-  when triggers fire; write the architecture doc alongside the code.
+  when triggers fire; write the architecture doc alongside the code. Apply
+  Rule 9 to the documents you write: SKILL.md, references, PLAN.md, README —
+  split them when they outgrow editability.
 - **Phase 7 (verification)**: the DoD checklist includes: no duplicated shared
   logic (Rule 2), no hardcoded config values (Rule 3), every module tested
   standalone with the same calls (Rule 4), architecture doc written (Rule 6),
-  existing functionality still green (Rule 8).
+  existing functionality still green (Rule 8). Documents: no doc so large that
+  editing it is fragile (Rule 9).
 
 ## Anti-patterns
 
@@ -168,3 +203,6 @@ existing functionality. Each rule below carries the lesson.
 - ❌ Refactoring "for fun" without the testability/debugging payoff
 - ❌ Shipping a module that cannot run outside the host
 - ❌ Skipping the architecture writeup ("the code is self-documenting")
+- ❌ Letting a document grow until edits start breaking instead of splitting it
+  (Rule 9)
+- ❌ A SKILL.md that is a wall of prose instead of a map to focused references

package/skills/aia-asf/references/07-release.md

@@ -15,6 +15,7 @@ Publishing is **always the user's decision**. The factory prepares everything; t
    - typecheck / build passes
    - test suite green
    - all MUST specs `met` in pi-vigilant
+   - every long-running verification command ran under an explicit timeout with a stated expected duration (06b Rule 15) — no unbounded waits
 2. **Version bump** — semantic versioning:
    - `patch` (0.1.0 → 0.1.1): bug fixes
    - `minor` (0.1.0 → 0.2.0): new features, backward compatible