pi-aia-asf 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.5.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`
@@ -212,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.
 
@@ -256,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
@@ -274,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/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