@pilotspace/add 2.1.0 → 2.3.0

package/tooling/add_engine/constants.py

@@ -2,10 +2,9 @@
 
 Pure module-level constants. add.py re-exports these so `import add; add.STAGES`
 (and the 6 _-prefixed names) still resolve. `__all__` lists the public names so
-`from add_engine.constants import *` brings exactly them (not the Path import).
+`from add_engine.constants import *` brings exactly them.
 """
 import re
-from pathlib import Path
 
 __all__ = [
     "BOOK_URL",
@@ -32,8 +31,6 @@ __all__ = [
     "PERSONA_HINT",
     "PERSONA_FIT_HINT_TEMPLATE",
     "GUIDELINE_FILES",
-    "RULES_FILE_REL",
-    "WORKFLOW_HEADINGS",
     "_GATE_MODES",
     "_SKIPPABLE_PHASES",
     "_DIALECT_CLASSES",
@@ -223,15 +220,14 @@ GUIDELINE_FILES = ("AGENTS.md", "CLAUDE.md", ".clinerules")
 _GUIDE_BEGIN = "<!-- ADD:BEGIN — managed by `add.py sync-guidelines`; do not edit inside -->"
 _GUIDE_END = "<!-- ADD:END -->"
 
-# Rule-file mode (ccsk-style projects): instead of inlining the block into CLAUDE.md,
-# write it to a dedicated rule file under .claude/rules/ and leave a one-line reference
-# in CLAUDE.md's Workflows section. .claude/rules/ is a CLAUDE-only convention, so this
-# mode only ever relocates CLAUDE.md — AGENTS.md/.clinerules keep the inline block.
-RULES_FILE_REL = Path(".claude") / "rules" / "add-workflows.md"
-# Headings (most→least specific) a project may already use to group rule/workflow links.
-# Match is case-insensitive on the heading TEXT, at any `#` level.
-WORKFLOW_HEADINGS = ("Rules & Workflows", "Workflows", "Rules")
-_RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules/add-workflows.md"
+# PROJECT.md specs-pointer markers (foundation-specs-refs). PROJECT.md stays the thin
+# read-first index; this managed, SPEC_DDS-driven block routes to the standing 5-DD picture
+# in `.add/specs/`. `init` scaffolds it, `migrate` wires it into a pre-pointer PROJECT.md;
+# both refresh it idempotently in place. Same never-change rule as the guideline markers:
+# a re-run finds the old block by exact match, so changing these would orphan every block a
+# prior version wrote.
+_SPECS_BEGIN = "<!-- ADD:SPECS — the 5-DD standing picture; managed by add.py — do not edit inside -->"
+_SPECS_END = "<!-- /ADD:SPECS -->"
 
 # Minimal embedded fallback so the tool still works if templates/ is missing
 # (circuit breaker: never hard-fail just because a template file was deleted).
@@ -252,14 +248,13 @@ Boundary:
   ⚠ <the ONE assumption most likely to be wrong — if wrong: <cost>>
 </assumptions>
 
-## 2 · SCENARIOS
 ## 3 · PLAN
 ### Contract
 Status: DRAFT
 ### Build-strategy
 Scope (may touch):
 Regression floor:
-## 4 · TESTS
+## 4 · TESTS & SCENARIOS
 ## 5 · BUILD
 ## 6 · VERIFY
 ### GATE RECORD

package/tooling/add_engine/guidelines.py

@@ -3,7 +3,7 @@
 Inject one stable, marker-delimited ADD block into every GUIDELINE_FILES target under the
 project root (AGENTS.md, CLAUDE.md, .clinerules). DYNAMIC-BY-REFERENCE: the block tells the
 agent to run `add.py status` and read PROJECT.md — it never embeds live state. A closed,
-self-contained cluster (8 fns + the cluster-private _INIT_EXCLUDE); transitive-closure AST
+self-contained cluster (4 fns + the cluster-private _INIT_EXCLUDE); transitive-closure AST
 scan: ZERO outbound calls to non-cluster add fns. Deps: constants + _atomic_write (io_state)
 + stdlib. None patched.
 """
@@ -15,8 +15,12 @@ import sys
 from pathlib import Path
 
 from add_engine.constants import (
-    GUIDELINE_FILES, RULES_FILE_REL, WORKFLOW_HEADINGS,
-    _GUIDE_BEGIN, _GUIDE_END, _RULE_REF_LINE,
+    GUIDELINE_FILES,
+    SPEC_DDS,
+    _GUIDE_BEGIN,
+    _GUIDE_END,
+    _SPECS_BEGIN,
+    _SPECS_END,
 )
 from add_engine.io_state import _atomic_write
 
@@ -31,28 +35,28 @@ def _guideline_block() -> str:
         f"{_GUIDE_BEGIN}\n"
         "## ADD — how to work in this repo\n"
         "\n"
-        "This project uses **ADD (AI-Driven Development)**: you, the AI, drive the build;\n"
-        "the human owns direction and verification. The loop below works for any agent —\n"
-        "Claude, Cursor, Copilot, Codex — through the CLI alone. Before you change code:\n"
+        "**ADD (AI-Driven Development)** — you, the AI, drive the build; the human owns direction\n"
+        "and verification. Works for any agent (Claude · Cursor · Copilot · Codex) through the CLI\n"
+        "alone. Before you touch code, orient:\n"
         "\n"
-        "1. `python3 .add/tooling/add.py status` — the resume point; read it first each session.\n"
-        "2. `.add/PROJECT.md` — the foundation (domain · spec · UI/UX) every task builds on.\n"
-        "3. `python3 .add/tooling/add.py guide` — it names the phase + its guide file; work ONLY that phase.\n"
+        "1. `python3 .add/tooling/add.py status` — your resume point; read it first each session.\n"
+        "2. `.add/PROJECT.md` — the thin read-first index (goal · `invariants:` · pointers into\n"
+        "   `.add/specs/`, the 5-DD standing picture); drill into a spec on demand.\n"
+        "3. `python3 .add/tooling/add.py guide` — names the current phase + its guide; work ONLY that phase.\n"
         "\n"
-        "The flow: INTAKE sizes a request into a milestone; each task runs the **specification bundle**\n"
-        "(Spec+Scenarios+Contract+Tests) — ONE human approval at the frozen contract — then a\n"
-        "self-driving build→verify run. Non-negotiable for every agent: Never weaken a test or edit a frozen contract\n"
-        "to make a build pass; a security finding is always HARD-STOP — never auto-passed.\n"
-        "PROJECT.md `invariants:` (run/entry contracts) bind EVERY task: the artifact must hold under\n"
-        "the BARE declared runtime — a dependency that breaks it is a defect, never \"expected\".\n"
+        "Each task drafts the **specification bundle** (Spec · Contract · Tests & Scenarios) —\n"
+        "ONE human approval at the frozen contract, then a self-driving build→verify run.\n"
+        "Non-negotiable: Never weaken a test or edit a frozen contract to pass a build; a\n"
+        "security finding is always HARD-STOP. PROJECT.md `invariants:` bind EVERY task — the\n"
+        "artifact must hold under the BARE declared runtime.\n"
         "\n"
-        "Roster (from `add-method/agents/*.md`): TWO agents — `add-worker` runs each EXECUTION beat\n"
-        "(the spawn names it: direction · build · verify · persona), and `add-advisor` is the second\n"
-        "mind it spawns to propose a plan, pressure-test a draft, or decide a delegable ambiguity so\n"
-        "the beat never stalls. Each loads that beat's phase guide plus the best-fit `.add/personas/`\n"
-        "persona (personas carry the expertise, the agent carries the discipline; the floor binds both).\n"
+        "Roster (`agents/*.md`): `add-worker` runs each beat (direction · build · verify · persona);\n"
+        "`add-advisor` is the second mind it spawns to plan, pressure-test, or resolve a delegable\n"
+        "ambiguity. Each loads the beat's guide + the best-fit `.add/personas/` persona — personas\n"
+        "carry the expertise, the agent carries the discipline.\n"
         "\n"
-        "On Claude Code the `add` skill drives this loop; other agents follow the three steps. Book: https://pilotspace.github.io/ADD/. This block is generated by `add.py sync-guidelines` — edit outside the markers.\n"
+        "On Claude Code the `add` skill drives this loop; other agents follow the three steps.\n"
+        "Book: https://pilotspace.github.io/ADD/. Generated by `add.py sync-guidelines` — edit outside the markers.\n"
         f"{_GUIDE_END}"
     )
 
@@ -89,131 +93,17 @@ def _inject_block(path: Path) -> str:
     return "created"
 
 
-def _rule_file_mode(project_root: Path, flag: bool = False) -> bool:
-    """True when the ADD block should live in .claude/rules/add-workflows.md (referenced
-    from CLAUDE.md) instead of inline. Re-derived from disk EACH phase — no persisted
-    state — so an explicit `--rule-file` at install carries into init via the rule file it
-    leaves behind. Three triggers: the explicit flag, a ccsk project (.ccsk/ sibling to
-    .claude/), or a rule file already written by a prior run. Pure + fail-soft."""
-    if flag:
-        return True
-    try:
-        if (project_root / ".ccsk").is_dir():
-            return True
-        if (project_root / RULES_FILE_REL).exists():
-            return True
-    except OSError:
-        pass
-    return False
-
-
-def _strip_inline_block(text: str) -> str:
-    """Remove an inline ADD:BEGIN..ADD:END region (migration to rule-file mode), collapsing
-    the blank-line gap it leaves behind. An unterminated BEGIN (no END) is left as-is rather
-    than eating the rest of the file (design-for-failure)."""
-    begin = text.find(_GUIDE_BEGIN)
-    if begin == -1:
-        return text
-    end = text.find(_GUIDE_END, begin)
-    if end == -1:
-        return text
-    end += len(_GUIDE_END)
-    head = text[:begin].rstrip("\n")
-    tail = text[end:].lstrip("\n")
-    if head and tail:
-        return head + "\n\n" + tail
-    return head or tail
-
-
-def _insert_rule_reference(text: str) -> str:
-    """Insert the ADD rule-file bullet under an existing Workflows/Rules heading, or append a
-    fresh '## Workflows' section when none is found. Caller guarantees the bullet is absent."""
-    lines = text.split("\n")
-    heading_idx = -1
-    for i, line in enumerate(lines):
-        m = re.match(r"^(#{1,6})\s+(.*?)\s*$", line)
-        if m and any(m.group(2).strip().lower() == h.lower() for h in WORKFLOW_HEADINGS):
-            heading_idx = i
-            break
-    if heading_idx == -1:                       # no section — append a fresh one
-        body = text.rstrip("\n")
-        sep = "\n\n" if body else ""
-        return f"{body}{sep}## Workflows\n\n{_RULE_REF_LINE}\n"
-    level = len(re.match(r"^(#{1,6})", lines[heading_idx]).group(1))
-    end = len(lines)                            # section ends at next same/higher heading or EOF
-    for j in range(heading_idx + 1, len(lines)):
-        m = re.match(r"^(#{1,6})\s+", lines[j])
-        if m and len(m.group(1)) <= level:
-            end = j
-            break
-    insert_at = heading_idx + 1                 # after the last non-blank line in the section
-    for j in range(heading_idx + 1, end):
-        if lines[j].strip():
-            insert_at = j + 1
-    lines.insert(insert_at, _RULE_REF_LINE)
-    return "\n".join(lines)
-
-
-def _ensure_claude_reference(claude_md: Path) -> str:
-    """Make CLAUDE.md reference the ADD rule file under a Workflows/Rules heading, migrating
-    any prior inline ADD block out. Returns created|updated|unchanged.
-
-    - Strips a prior inline ADD:BEGIN..END block (rule-file mode supersedes inline).
-    - If a reference to add-workflows.md already exists -> no bullet change.
-    - Else inserts the bullet into the first matching section, or appends '## Workflows'.
-    .bak on change; idempotent. User content outside the touched region is preserved.
-    """
-    existed = claude_md.exists()
-    current = claude_md.read_text(encoding="utf-8") if existed else ""
-    new = _strip_inline_block(current)
-    if "add-workflows.md" not in new:
-        new = _insert_rule_reference(new)
-    if not new.endswith("\n"):
-        new += "\n"
-    if new == current:
-        return "unchanged"
-    if existed:
-        _atomic_write(Path(str(claude_md) + ".bak"), current)   # rollback path before mutate
-    _atomic_write(claude_md, new)
-    return "updated" if existed else "created"
-
-
-def _inject_guidelines(project_root: Path, rule_file: bool = False) -> list[tuple[str, str]]:
+def _inject_guidelines(project_root: Path) -> list[tuple[str, str]]:
     """Inject the block into each guideline file under `project_root`.
 
     Symlink-dedup: targets resolving (os.path.realpath) to the same inode are
     written once, against the REAL file (never replacing the symlink with a
     regular file). Per-target OSError is isolated (warn+skip) so one unwritable
     file never aborts the run or `init`.
-
-    Rule-file mode (ccsk projects / `--rule-file`): CLAUDE.md's full block is relocated
-    to .claude/rules/add-workflows.md and CLAUDE.md keeps only a reference bullet. This is
-    CLAUDE-only — AGENTS.md (and any other guideline file) keeps the inline block.
     """
     results: list[tuple[str, str]] = []
     seen: set[str] = set()
-    mode = _rule_file_mode(project_root, rule_file)
     for name in GUIDELINE_FILES:
-        if name == "CLAUDE.md" and mode:
-            rules_path = project_root / RULES_FILE_REL
-            real = os.path.realpath(rules_path)
-            if real not in seen:
-                seen.add(real)
-                try:
-                    action = _inject_block(rules_path)
-                except (OSError, UnicodeDecodeError) as exc:
-                    print(f"add: warning: could not sync {RULES_FILE_REL} — {exc}; skipped",
-                          file=sys.stderr)
-                    action = "skipped"
-                results.append((str(RULES_FILE_REL), action))
-            try:
-                ref_action = _ensure_claude_reference(project_root / "CLAUDE.md")
-            except (OSError, UnicodeDecodeError) as exc:
-                print(f"add: warning: could not sync CLAUDE.md — {exc}; skipped",
-                      file=sys.stderr)
-                ref_action = "skipped"
-            results.append(("CLAUDE.md", ref_action))
-            continue
         target = project_root / name
         real = os.path.realpath(target)
         if real in seen:
@@ -233,6 +123,66 @@ def _inject_guidelines(project_root: Path, rule_file: bool = False) -> list[tupl
     return results
 
 
+# --- PROJECT.md specs pointers -----------------------------------------------
+
+def _specs_pointer_block() -> str:
+    """The managed ADD:SPECS block (markers + body), driven entirely by SPEC_DDS.
+
+    PROJECT.md is the thin read-first index; this block routes to the standing
+    5-DD picture in `.add/specs/` — one line per lens, so the picture can never
+    drift from the closed 5-DD map."""
+    lines = [
+        _SPECS_BEGIN,
+        "## Foundation specs — the standing 5-DD picture",
+        "",
+        "This file is the thin index; the detail lives in the specs. Lessons land there via "
+        "`add.py delta-append <dd>`.",
+        "",
+    ]
+    for _dd, (fname, title, lens) in SPEC_DDS.items():
+        lines.append(f"- **{title}** → `.add/specs/{fname}` — {lens}")
+    lines.append(_SPECS_END)
+    return "\n".join(lines)
+
+
+def _inject_specs_pointers(project_md: Path) -> str:
+    """Inject/refresh the ADD:SPECS pointer block in PROJECT.md. Idempotent.
+
+    Returns created|updated|unchanged|absent:
+    - absent:    PROJECT.md does not exist -> no-op (nothing to wire).
+    - unchanged: on-disk block already matches -> no write.
+    - updated:   markers present -> replace only the marked region (refresh).
+    - created:   markers absent  -> insert before the first '## ' section
+                 (keeping the header/goal above it); append if no section exists.
+    Content outside the markers is always preserved."""
+    if not project_md.exists():
+        return "absent"
+    current = project_md.read_text(encoding="utf-8")
+    block = _specs_pointer_block()
+    begin = current.find(_SPECS_BEGIN)
+    if begin != -1:
+        end = current.find(_SPECS_END, begin)
+        if end != -1:                          # replace only the marked region
+            end += len(_SPECS_END)
+            new = current[:begin] + block + current[end:]
+        else:                                  # begin without end: corrupt — append fresh
+            print(f"add: warning: {project_md.name}: found an ADD:SPECS with no close "
+                  "— appending a fresh block; review the result", file=sys.stderr)
+            new = current.rstrip("\n") + "\n\n" + block + "\n"
+        action = "updated"
+    else:                                      # no block yet — insert above the first section
+        m = re.search(r"(?m)^## ", current)
+        if m:
+            new = current[:m.start()] + block + "\n\n" + current[m.start():]
+        else:
+            new = current.rstrip("\n") + "\n\n" + block + "\n"
+        action = "created"
+    if new == current:
+        return "unchanged"
+    _atomic_write(project_md, new)
+    return action
+
+
 # --- commands ----------------------------------------------------------------
 
 _INIT_EXCLUDE = {

package/tooling/templates/MILESTONE.md.tmpl

@@ -40,6 +40,15 @@ Issues/Risks (shared): <traps in the shared code that feed each task's §1 expec
 ## Exit criteria (observable; map each to the task that delivers it)
 - [ ] User can <observable behavior — the SEEN outcome only, NOT the task's plan line>        (← <slug>)
 
+## Strategy   (AI-drafted WITH the human — the optimized task plan; SOFT/advisory like a task's Build-strategy; drafted-blank for a micro/--fast milestone)
+> The persona-led strategy over THIS milestone's tasks — sequencing, freeze-first contracts,
+> parallel waves, the first unblocking slice, tradeoffs named. SOFT: the preferred plan; the
+> loop may deviate and records what it did. Drafted-blank is valid (risk-proportional).
+- Approach (sequencing): <risk-first | dependency-first | first-slice-unblocks — and WHY>
+- Freeze-first: <the shared/risky contract to freeze before the rest>
+- Waves (parallel): <task slugs that can run concurrently behind frozen contracts — or "sequential">
+- Tradeoffs weighed: <alternative decompositions considered + why this one>
+
 ## Close — ship review   (AI fills when every task is done — the evidence behind the engine gate, read before the boxes are checked)
 > Cross-task review the AI fills — the evidence behind the EXISTING milestone-done gate, NOT a new approval.
 

package/tooling/templates/PLAN.md.tmpl

@@ -30,13 +30,7 @@ Boundary: <one format-variant per external input shape the tests must speak —
   ⚠ <the ONE assumption most likely to be wrong — if wrong: <cost>>
 </assumptions>
 
----
-
-## 2 · SCENARIOS — pass/fail cases ▸ docs/04-step-2-scenarios.md
-
-<scenarios>
-</scenarios>
-<!-- The §4 test_plan is the canonical encoding of every scenario (one test per Must/Reject). Add gherkin above ONLY when a human stakeholder needs readable cases — never as ceremony. -->
+<!-- §2 (the old standalone SCENARIOS section) was RETIRED — pass/fail cases now live with the tests in §4 · TESTS & SCENARIOS. The §3–§7 numbers are unchanged so the freeze parser and every §-reference keep working; the jump from §1 to §3 is intentional. -->
 
 ---
 
@@ -55,10 +49,12 @@ Target (measurable): <the success bar §6 evidence must hit — numbers, not adj
 Status: DRAFT
 Reported: <yes — the freeze report (banner/ARC/SHAPE) rendered before this froze | no>
 
-### Build-strategy (SOFT: preferred; the builder self-improves and records actual at verify)
-Scope (may touch): `./src/`   <fill before the freeze — the file write-set, single source of truth; every file the build may write; scope-lock source>
-Regression floor: <the existing suite(s) that must stay green — the host repo's own tests are ALWAYS a floor; run them before the gate — or "none — greenfield">
-Persona (required): <persona file under `.add/personas/` this build embodies — advisory, never lowers a gate; "generic" if none fits>
+### Build-strategy — Scope (may touch) is HARD scope-lock; the rest is SOFT (the builder self-improves and records actual at verify)
+Scope (may touch): `src/`   <HARD — fill before the freeze; the file write-set, single source of truth; every file the build may write. Token grammar (backtick each): name/ = project root · ./… = THIS task's dir (rarely what a build writes) · a directory covers its whole subtree>
+Regression floor: <optional — the existing suite(s) that must stay green; the host repo's own tests are a floor when present; run them before the gate — or omit / "none — greenfield">
+Persona (optional): <persona file under `.add/personas/` this build embodies — advisory, never lowers a gate; omit or "generic" if none fits>
+
+Least-sure flag surfaced at freeze: [spec|scenario|contract|test] <the ONE part you trust least + why — REQUIRED at the freeze (unflagged_freeze refuses without it); pick ONE part tag from the menu; §1's top ⚠ usually feeds it>
 
 ### AI-verify record (required when gate_mode: ai-plan-verify)
 - [ ] §3 PLAN grounding anchors resolve in the current tree
@@ -67,16 +63,18 @@ Persona (required): <persona file under `.add/personas/` this build embodies —
 - [ ] Lowest-confidence flag surfaced and substantive (mirrors unflagged_freeze's own bar)
 Verified by: <agent-id> · at: <ISO-8601 UTC timestamp>
 
-<!-- The freeze IS the one approval, led by the bundle's lowest-confidence flag — Contract = HARD (tamper-guarded); Build-strategy = SOFT. Approved -> Status: FROZEN @ vN — approved by <name>; changing a frozen Contract = change request back to SPECIFY. Scope tokens, backticked: `./…` = this task dir · a "/" token = project root · a bare name = sibling of the previous token's dir · a directory covers its whole subtree · outside-root drops fail-closed · absent line = UNDECLARED (grandfathered, never retro-red). -->
+<!-- The freeze IS the one approval, led by the bundle's lowest-confidence flag — Contract + Scope (may touch) = HARD (tamper-guarded); Strategy · Regression floor · Persona = SOFT/optional. Approved -> Status: FROZEN @ vN — approved by <name>; changing a frozen Contract = change request back to SPECIFY. Scope tokens, backticked: `./…` = this task dir · a "/" token = project root · a bare name = sibling of the previous token's dir · a directory covers its whole subtree · outside-root drops fail-closed · absent line = UNDECLARED (grandfathered, never retro-red). -->
 
 ---
 
-## 4 · TESTS — failing-first suite or acceptance checks (red) ▸ docs/06-step-4-tests.md
+## 4 · TESTS & SCENARIOS — failing-first suite or acceptance checks (red) ▸ docs/06-step-4-tests.md
 
 <test_plan>
   - test_<name>: arrange / act / assert behavior not internals · covers: <M#, R:code>
 </test_plan>
 
+Rigor: one red test per §1 Must/Reject — the PRIMARY cases + primary edge cases — is the gated floor. Minor/secondary behaviors are DESCRIBED in prose below as build-guidance — no `covers:` tag, no red test, not gated. Add a Given/When/Then line inline ONLY when a human stakeholder needs a readable case — never as ceremony; the test_plan is the canonical encoding of every scenario.
+
 Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 <!-- declare paths as backticked tokens on this line: `./…` = this task dir · a token with "/" = the project root · a bare name = a sibling of the previous token's dir · a directory counts its *.py files (non-recursive) · declared counts marked † · outside the project root counts 0. The test_plan bullets' `covers:` tails are machine-read too: `add.py locate path::test_name` resolves a failing test to the frozen §3 clause it proves -->
 <!-- NON-CODING task (kind: docs · release · infra, or a non-coding project)? §4 is a failing-first ACCEPTANCE CHECK, not a script — verifiable pass/fail evidence (mkdocs build succeeds · §X covers A/B/C · every internal link resolves), red before the artifact exists and green after. Set `Tests live in: evidence` (no `./tests/`). The red→green discipline holds; only the must-be-executable-code requirement is lifted. -->
@@ -86,7 +84,7 @@ Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 ## 5 · BUILD — AI writes the code (execution) ▸ docs/07-step-5-build.md
 
 Strategy actually used: <fill at VERIFY — what you ACTUALLY did (or "as planned"); harvested into §7 Decisions (ADR)>
-Code lives in: `./src/`
+Code lives in: `src/`
 Spawn (multi-agent): build/verify subagent spawns default `isolation: worktree`; cross-agent advisor — spawn `add-advisor` (an agent OTHER than the builder) for the freeze `--cross` and the §6 refute-read; `self` only when solo.
 Constraints: do NOT change any test or the frozen §3 contract; stay inside §3 Scope (an out-of-scope build fails the gate: scope_violation); keep the §3 Regression floor green; allow-list packages only; ask if unclear.