@pilotspace/add 1.17.0 → 2.0.0

package/tooling/add_engine/autonomy.py

@@ -11,15 +11,14 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from add_engine.constants import _AUTONOMY_LEVELS, _STREAMS_POSTURES
+from add_engine.constants import _AUTONOMY_LEVELS
 from add_engine.taskdoc import _task_header
 
 _AUTONOMY_LINE_RE = re.compile(r"(?:^|·)[ \t]*autonomy:[ \t]*([^\s<#|]+)", re.MULTILINE)
-_STREAMS_LINE_RE = re.compile(r"(?:^|·)[ \t]*streams:[ \t]*([^\s<#|]+)", re.MULTILINE)
 
 
 def _autonomy_level(hdr: str):
-    """The declared autonomy rung from a TASK.md header region (HTML comments
+    """The declared autonomy rung from a PLAN.md header region (HTML comments
     already stripped by _task_header). Returns a member of _AUTONOMY_LEVELS, or
     None when no `autonomy:` line is present (UNSET — an unfilled `<…>` placeholder,
     whose value the regex declines, counts as unset), or "?" when a REAL token outside
@@ -57,37 +56,3 @@ def _project_autonomy(root: Path) -> str:
     Read-only and PURE — mirrors _project_goal; the seed source for cmd_new_task."""
     tok = _project_autonomy_token(root)
     return "auto" if tok is None else ("conservative" if tok == "?" else tok)
-
-
-# --- streams posture: the parallel-vs-sequential half of the run mode (persist-run-mode) ---
-# A project-scoped declaration in PROJECT.md beside autonomy. Mirrors the autonomy resolvers:
-# anchored read (a title/prose substring is never a declaration), fail-safe defaults.
-
-def _streams_posture(text: str):
-    """The declared streams posture from a foundation region (HTML comments already stripped
-    by the caller). A member of _STREAMS_POSTURES, None when no `streams:` line is present, or
-    "?" when a REAL token outside the set was written (unknown). PURE."""
-    m = _STREAMS_LINE_RE.search(text)
-    if not m:
-        return None
-    tok = m.group(1).strip().lower()
-    return tok if tok in _STREAMS_POSTURES else "?"
-
-def _project_streams_token(root: Path):
-    """The RAW streams declaration in PROJECT.md — a recognized posture, None when no
-    declaration line is present, or "?" for a real-but-unrecognized token. Uses the anchored
-    _streams_posture (a title/prose substring is never a declaration) with HTML comments
-    stripped. Unreadable foundation -> None. Read-only and PURE."""
-    try:
-        text = (root / "PROJECT.md").read_text(encoding="utf-8")
-    except OSError:
-        return None
-    return _streams_posture(re.sub(r"<!--.*?-->", "", text, flags=re.S))
-
-def _project_streams(root: Path) -> str:
-    """The streams posture the project runs under. Fail-SAFE: no declaration -> "parallel"
-    (the documented project default: parallel+auto); an unrecognized token -> "sequential"
-    (the conservative fallback, NEVER silently parallel); an unreadable foundation -> "parallel".
-    Read-only and PURE — mirrors _project_autonomy."""
-    tok = _project_streams_token(root)
-    return "parallel" if tok is None else ("sequential" if tok == "?" else tok)

package/tooling/add_engine/components.py

@@ -1,21 +1,13 @@
-"""add_engine.components — the component-aware-add subsystem (engine-modularization 11/N).
+"""add_engine.components — scope-confinement utilities.
 
-Registry (.add/components.toml) + produced/consumed contracts + cross-repo federation +
-scope confinement. A closed, unpatched cluster (transitive-closure AST = zero outbound).
-Replicates add.py's degrade-safe tomllib guard so `import` stays safe on Python < 3.11
-(where the registry degrades to opt-out). Opt-in: no components.toml -> every reader is
-byte-identical to single-component. Deps: stdlib only (no add, no add_engine).
+kernel-trim (ADD 2.0 M5): the components pillar (registry · cross-component contracts ·
+federation) died with its verbs; only the two GENERIC path/scope utilities every scope
+read shares survive here. Deps: stdlib only (no add, no add_engine).
 """
 from __future__ import annotations
 
-import re
 from pathlib import Path
 
-try:                          # component registry parse (Python 3.11+ stdlib); degrade-safe
-    import tomllib
-except ModuleNotFoundError:   # < 3.11: registry unsupported -> tomllib None -> opt-out
-    tomllib = None
-
 
 def _confined(p: Path, rootp: Path) -> bool:
     """True only if p resolves (symlinks followed) inside rootp; errors -> False.
@@ -25,85 +17,10 @@ def _confined(p: Path, rootp: Path) -> bool:
     except OSError:
         return False
 
-def _components(root: Path) -> dict[str, dict]:
-    """The registry from .add/components.toml → {name: {root, verify, green_bar,
-    language}}. `root` required per entry; an entry missing it is skipped (the finding
-    surface reports it). `verify` is stored OPAQUE — parsed as data, NEVER executed. PURE."""
-    if tomllib is None:
-        return {}
-    try:
-        raw = (root / "components.toml").read_bytes()
-    except OSError:
-        return {}
-    try:
-        data = tomllib.loads(raw.decode("utf-8"))
-    except (tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
-        return {}
-    out: dict[str, dict] = {}
-    for name, spec in (data.get("component") or {}).items():
-        # "?" is the reserved unknown-binding sentinel (_task_component) — a component
-        # named "?" would collide and silently drop cover, so it never registers.
-        if name == "?" or not isinstance(spec, dict) or not isinstance(spec.get("root"), str):
-            continue
-        out[name] = {"root": spec["root"], "verify": spec.get("verify"),
-                     "green_bar": spec.get("green_bar"), "language": spec.get("language")}
-    return out
 
-def _cite_region(body: str) -> str:
-    """The user-authored "Build expectations" evidence region of a §6 body, stamp-stripped —
-    the only place a per-component green-bar cite counts (per-component-verify, v3). PURE.
 
-    The marker matches BOTH template shapes: the standard "### Build expectations …" heading AND
-    the fast-lane bare "Build expectations (from …):" line, running up to the GATE RECORD sub-block.
-    So the top-of-§6 checklist ("- [ ] all tests pass") and the "Outcome: <PASS|…>" placeholder are
-    excluded, and a component-bound FAST task is still citable. The trailing strip removes the
-    engine's own "component: … · expected green-bar: …" stamp wherever it landed, so a stamp that
-    fell inside the region can never self-satisfy the gate. No marker -> "" (fail-closed for a bound
-    task: it must declare its evidence)."""
-    m = re.search(r"(?im)^#*[ \t]*Build expectations\b.*?(?=\n#+[ \t]*GATE RECORD\b|\Z)", body, re.DOTALL)
-    region = m.group(0) if m else ""
-    return re.sub(r"(?m)^component:.*·.*expected green-bar:.*$", "", region)
 
-def _contracts(root: Path) -> dict[str, dict]:
-    """[contract.<id>] from .add/components.toml -> {id: {producer: str, consumers: list[str]}}.
-    A malformed entry (producer not a str) is skipped (the finding surface reports it). PURE."""
-    if tomllib is None:
-        return {}
-    try:
-        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
-    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
-        return {}
-    out: dict[str, dict] = {}
-    for cid, spec in (data.get("contract") or {}).items():
-        if not isinstance(spec, dict) or not isinstance(spec.get("producer"), str):
-            continue
-        cons = spec.get("consumers")
-        out[cid] = {"producer": spec["producer"],
-                    "consumers": [c for c in cons if isinstance(c, str)] if isinstance(cons, list) else []}
-    return out
-
-def _federation(root: Path) -> dict[str, dict]:
-    """[federation.<id>] from .add/components.toml -> {id: {source: str, pin: str|None}}.
-    The cross-REPO join: a consumer repo names where a producer repo's published snapshot lives.
-    A malformed entry (no string source) is skipped; a non-string `pin` degrades to None. Degrade-safe
-    — never raises. PURE. On Python < 3.11 (no tomllib) this returns {} like the other component
-    readers, so `federate` reports federation_unknown — components.toml needs a 3.11+ runtime."""
-    if tomllib is None:
-        return {}
-    try:
-        data = tomllib.loads((root / "components.toml").read_bytes().decode("utf-8"))
-    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError, ValueError):
-        return {}
-    out: dict[str, dict] = {}
-    for fid, spec in (data.get("federation") or {}).items():
-        if not isinstance(spec, dict) or not isinstance(spec.get("source"), str):
-            continue
-        pin = spec.get("pin")
-        out[fid] = {"source": spec["source"], "pin": pin if isinstance(pin, str) else None}
-    return out
 
-def _contract_snapshot(root: Path, cid: str) -> Path:
-    return root / "contracts" / f"{cid}.json"
 
 def _in_scope(rel: str, declared: list[str]) -> bool:
     """True when rel falls under any declared token — exact match for a file

package/tooling/add_engine/constants.py

@@ -8,27 +8,35 @@ import re
 from pathlib import Path
 
 __all__ = [
+    "BOOK_URL",
+    "book_url",
     "ROOT_DIRNAME",
     "STATE_FILE",
     "MILESTONE_FILE",
     "GOAL_UNSET",
     "STAGES",
-    "GRADUATION_CUE",
-    "RELEASABLE_CUE",
-    "RELEASES_FILE",
     "PHASES",
+    "LEGACY_PHASES",
     "GATES",
     "HEAL_CAP",
     "PHASE_GUIDE",
     "PHASE_OWNER",
+    "PHASE_GROUPS",
+    "PHASE_AGENT",
     "SETUP_FILES",
     "PERSONA_FRONTMATTER_KEYS",
     "PERSONA_REQUIRED_SECTIONS",
+    "PERSONA_FLOW_VALUES",
+    "TASK_KINDS",
+    "SPEC_DDS",
     "PERSONA_HINT",
     "PERSONA_FIT_HINT_TEMPLATE",
     "GUIDELINE_FILES",
     "RULES_FILE_REL",
     "WORKFLOW_HEADINGS",
+    "_GATE_MODES",
+    "_SKIPPABLE_PHASES",
+    "_DIALECT_CLASSES",
 ]
 
 ROOT_DIRNAME = ".add"
@@ -39,18 +47,19 @@ MILESTONE_FILE = "MILESTONE.md"
 # this sentinel so the read-only orientation surfaces never blank or crash.
 GOAL_UNSET = "(unset — add a 'goal:' line to PROJECT.md)"
 STAGES = ("prototype", "poc", "mvp", "production")
-# v22 stage-graduation: the read-only cue `status` shows when the MVP is covered.
-# Worded as the ACTION (never a file) so it stands before graduate.md exists.
-GRADUATION_CUE = "MVP covered → propose graduation"
-# release-altitude: the read-only cue `status` shows when ≥1 closed milestone is
-# unreleased. The 5th scope level (release.md). `{n}` is filled at print time; the
-# wording matches SKILL.md's "Beyond the bundle" cross-ref byte-for-byte.
-RELEASABLE_CUE = "releasable: {n} milestone(s) closed since last release"
-# the append-only release ledger lives at the PROJECT ROOT (the dir containing .add/),
-# a sibling of CHANGELOG.md — NOT inside .add/. The ledger IS the attribution source:
-# a milestone is "released" iff its slug appears on a `milestones:` row.
-RELEASES_FILE = "RELEASES.md"
-PHASES = ("ground", "specify", "scenarios", "contract", "tests", "build", "verify", "observe", "done")
+# kernel-trim (ADD 2.0 M5): GRADUATION_CUE / RELEASABLE_CUE / RELEASES_FILE died with the
+# graduate/release verbs — the release-manager persona owns that judgment now.
+PHASES = ("direction", "build", "verify", "done")
+# phase-collapse-3 (thin-engine-loop W2): the 6-phase walk collapsed to 3 work phases.
+# `direction` is the whole front span (the old specify+plan+tests — §1–§4 drafted
+# top-to-bottom, ONE freeze approval crosses it into build). Legacy tokens normalize to
+# their 3-phase home at READ time (load_state) — 473 pre-collapse task records are never
+# bulk-rewritten; the map below is the single source both load_state and _phase_index use.
+LEGACY_PHASES = {
+    "ground": "direction", "specify": "direction", "scenarios": "direction",
+    "contract": "direction", "plan": "direction", "tests": "direction",
+    "observe": "verify",
+}
 GATES = ("none", "PASS", "RISK-ACCEPTED", "HARD-STOP")
 # heal-then-escalate (verify-integrity): the bounded self-heal loop cap. A CONFIRMED cheat
 # (mechanical tripwire divergence, or an agent-reported semantic refute-read finding) returns
@@ -61,36 +70,61 @@ HEAL_CAP = 3
 
 
 
+# The AIDD book's published home (book-stops-shipping, ADD 2.0 M6b): the book no
+# longer installs into projects as .add/docs/ — every engine chapter pointer deep-
+# links here instead. mkdocs pretty-URLs: docs/<stem>.md renders at <BOOK_URL>/<stem>/.
+BOOK_URL = "https://pilotspace.github.io/ADD"
+
+
+def book_url(chapter: str) -> str:
+    """Deep link for a book chapter filename ('02-the-flow.md' -> …/02-the-flow/)."""
+    stem = chapter[:-3] if chapter.endswith(".md") else chapter
+    return f"{BOOK_URL}/{stem}/"
+
+
 # `add.py guide` copy: per-phase (concrete next action, book chapter to read).
 # Keep the action wording aligned with each phase's EXIT line in the TASK template.
 PHASE_GUIDE = {
-    "ground":    ("gather the real codebase the task touches — files, symbols, signatures, conventions, and the anchor points the contract will cite; defer to PROJECT.md/CONVENTIONS.md and gather only the task delta",
-                  "02-the-flow.md"),
-    "specify":   ("state every rule — Must / Reject (+ named code) / After; rank assumptions lowest-confidence first and flag the biggest risk",
+    "direction": ("draft the Direction bundle top-to-bottom — §1 rules (Must / Reject + named codes / After, assumptions ranked lowest-confidence first) · §2 one scenario per rule · §3 the change PLAN: ground the real code, draft the contract, and DESCRIBE what this task will do (scope · ordered batches · approach — the plan-of-action the freeze report shows the human) · §4 red suite failing for the right reason; then the ONE approval: freeze --by <name> --cross",
                   "03-step-1-specify.md"),
-    "scenarios": ("write one Given/When/Then per Must AND per Reject; every result observable",
-                  "04-step-2-scenarios.md"),
-    "contract":  ("freeze the shape — signature, fields, error codes; names match the glossary",
-                  "05-step-3-contract.md"),
-    "tests":     ("write one failing test per scenario; run them RED for the right reason",
-                  "06-step-4-tests.md"),
     "build":     ("write the minimum code to pass the tests; change no test and no contract",
                   "07-step-5-build.md"),
-    "verify":    ("run the suite + non-functional checks, then record the gate",
+    "verify":    ("run the suite + non-functional checks, then record the gate; then note what to watch + the spec delta for the next loop (§7)",
                   "08-step-6-verify.md"),
-    "observe":   ("note what to watch + the spec delta for the next loop",
-                  "09-the-loop.md"),
     "done":      ("this task is done — pick the next feature",
                   "02-the-flow.md"),
 }
 # Phase -> who owns it, for the `--json` autonomy signal. An autonomous harness may run a
 # phase only when owner=="ai" (stop is false); every other phase is a checkpoint. The map
-# follows the book's who-does-what table (Verify is "human only"); `tests`/`build`/`observe`
+# follows the book's who-does-what table (Verify is "human only"); `tests`/`build`
 # are AI-led. A phase missing here is `unmapped_phase` (fail closed) — never defaulted.
 PHASE_OWNER = {
-    "ground": "ai",
-    "specify": "human", "scenarios": "human", "contract": "seam",
-    "tests": "ai", "build": "ai", "verify": "human", "observe": "ai", "done": "human",
+    "direction": "seam",
+    "build": "ai", "verify": "human", "done": "human",
+}
+# phase-bundles: the work phases (PHASES minus the terminal "done") group into 3
+# agent-owned bundles surfaced at `status`/`guide` — DIRECTION fixes the shape (through
+# the frozen change plan — grounding + contract + build-strategy — AND the red suite; the
+# method thesis is "fix spec/scenarios/plan/failing-tests BEFORE the build"), BUILD makes
+# it green, VERIFY earns trust and feeds the next loop. A grouping OVER PHASES, never a
+# reorder; "done" (terminal, human-led) deliberately has no bundle — see PHASE_AGENT/
+# _phase_bundle below. Union == set(PHASES) - {"done"}, pairwise disjoint (test_phase_bundles.py).
+PHASE_GROUPS = {
+    "DIRECTION": ("direction",),
+    "BUILD": ("build",),
+    "VERIFY": ("verify",),
+}
+# phase-bundles: the roster agent PREFERRED for each phase (per-PHASE, not per-bundle —
+# roster-distill (ADD 2.0 M1): ONE execution shell — the `add` agent — serves every
+# phase; the spawn prompt names the mode (direction·build·verify·advise·persona) and
+# the agent loads that beat's guide + the fitting persona (personas carry the
+# expertise, the agent carries the discipline). A phase missing here is a bug (PHASE_GROUPS'
+# own union covers every key); `_phase_bundle` is the fail-closed resolver for an
+# unmapped/corrupted phase token, not this map directly.
+PHASE_AGENT = {
+    "direction": "add",
+    "build": "add",
+    "verify": "add",
 }
 SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md", "personas/_template.md")
 
@@ -100,23 +134,52 @@ SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md
 # content quality is the AI's authoring concern, not the engine gate. NO-EXEC: validation is pure.
 PERSONA_FRONTMATTER_KEYS = ("name", "vibe")
 PERSONA_REQUIRED_SECTIONS = ("## Identity", "## Critical Rules", "## Default Requirement", "## Success Metrics")
+# persona-schema-hardening: the closed set of apply-surfaces a `flow:` value may name — the
+# single source the quality predicate reads (a value outside this set is loaded by NO surface,
+# so a typo would otherwise fail silently). Findings are WARN-only (measure-not-block).
+PERSONA_FLOW_VALUES = ("design", "build", "advisor", "verify")
+# persona-task-kinds (ADD 2.0 M1 persona-core): the closed task-kind taxonomy — the join key
+# between a persona's routing claim (`task-kinds:` frontmatter) and a task's declared kind
+# (`kind:` header line). Route-outcome traces record it, the persona scoreboard groups by it.
+# Closed on purpose: a free-text kind can't be scored across tasks. Measure-not-block —
+# an unknown kind is a named WARN (quality predicate Finding C), never a refusal.
+TASK_KINDS = ("feature", "refactor", "test", "docs", "ui",
+              "security", "data", "infra", "release", "integration")
+
+# specs-5dd (ADD 2.0 M3): the closed 5-DD map — dd tag -> (spec file under .add/specs/,
+# title, lens). init renders ONE template (templates/specs/SPEC.md.tmpl) five ways;
+# `delta-append <dd>` routes a lesson to its file. Closed on purpose: the five lenses ARE
+# the method's competency model (DDD·SDD·UDD·TDD·ADD) — an unknown dd is a refusal
+# (delta_dd_unknown), because a delta filed under a sixth ad-hoc lens is a delta lost.
+SPEC_DDS = {
+    "ddd": ("domain.md", "Domain",
+            "what the system IS: entities, rules, ubiquitous language (DDD)"),
+    "sdd": ("system.md", "System",
+            "how it is built: architecture, contracts, data shapes (SDD)"),
+    "udd": ("experience.md", "Experience",
+            "how it feels to use: flows, surfaces, the humans served (UDD)"),
+    "tdd": ("quality.md", "Quality",
+            "how we know it works: test strategy, floors, evidence (TDD)"),
+    "add": ("method.md", "Method",
+            "how we work: the loop, autonomy, ceremony budget (ADD)"),
+}
 
 # persona-seed-nudge v2: ONE hint, single-sourced — `new-milestone`/`check`/`status` all print
 # THIS constant (not their own copy) so the wording can never drift across the three surfaces.
 # Project-scoped (not "this milestone's domain") per the confirmed v2 amendment: the AI should
 # catch up ALL of a project's missing personas, not draft a single milestone-fit one.
-PERSONA_HINT = ("no project-fit persona seeded yet under .add/personas/ — spawn the add-persona "
-                "agent (or read docs/18-personas.md) to seed the project's persona(s) from "
-                "PROJECT.md's domain")
+PERSONA_HINT = ("no project-fit persona seeded yet under .add/personas/ — spawn the add agent "
+                "in persona mode (or read docs/18-personas.md) to seed the project's persona(s) "
+                "from PROJECT.md's domain + the seed templates (tooling/templates/personas/)")
 
 # persona-fit-nudge: the OPPOSITE-branch, mutually-exclusive sibling of PERSONA_HINT — fires only
 # when ≥1 real persona ALREADY exists, so a brand-new milestone doesn't silently assume one of
 # them fits its domain. Existence-only (names the persona slugs already seeded); the AI still
-# owns the actual fit judgment via add-persona — the engine never scores content similarity.
-# {slugs} is filled at call time from `.add/personas/*.md` (excluding `_template`).
+# owns the actual fit judgment (the add agent's persona mode) — the engine never scores content
+# similarity. {slugs} is filled at call time from `.add/personas/*.md` (excluding `_template`).
 PERSONA_FIT_HINT_TEMPLATE = (
     "existing persona(s) seeded — {slugs} — confirm one fits this milestone's domain, or spawn "
-    "the add-persona agent (or read docs/18-personas.md) to draft a better-fit one"
+    "the add agent in persona mode (or read docs/18-personas.md) to draft a better-fit one"
 )
 
 # Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
@@ -171,16 +234,11 @@ _RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules
 
 # Minimal embedded fallback so the tool still works if templates/ is missing
 # (circuit breaker: never hard-fail just because a template file was deleted).
-_FALLBACK_TASK = """# TASK: {title}
+_FALLBACK_TASK = """# PLAN: {title}
 
 slug: {slug} · created: {date} · stage: {stage}
 autonomy: auto
-phase: ground
-
-## 0 · GROUND
-Touches (files · symbols · signatures):
-Honors (patterns / conventions):
-Anchors the contract cites:
+phase: direction
 
 ## 1 · SPECIFY
 Feature:
@@ -188,12 +246,18 @@ Framings weighed:
 Must:
 Reject:
 After:
-Assumptions — lowest-confidence first:
-  ⚠ <most likely wrong> — lowest confidence because <why>; if wrong: <cost>
+Boundary:
+<assumptions>
+  ⚠ <the ONE assumption most likely to be wrong — if wrong: <cost>>
+</assumptions>
 
 ## 2 · SCENARIOS
-## 3 · CONTRACT
+## 3 · PLAN
+### Contract
 Status: DRAFT
+### Build-strategy
+Scope (may touch):
+Regression floor:
 ## 4 · TESTS
 ## 5 · BUILD
 ## 6 · VERIFY
@@ -205,46 +269,9 @@ Outcome:
 """
 
 
-# Fast-lane fallback: the minimal TASK.md variant (sections {0,1,3,4,5,6}; §2 + §7 dropped).
-# Mirrors templates/TASK.fast.md.tmpl's section set (circuit-breaker parity); a deleted
-# templates/ never hard-fails the fast lane. Keeps the trust floor: §3 freeze-flag + Status,
-# §6 GATE RECORD/Outcome, §0 Anchors, §4 red-before-build, §5 Scope.
-_FALLBACK_TASK_FAST = """# TASK: {title}
-
-slug: {slug} · created: {date} · stage: {stage}
-autonomy: auto
-phase: ground
-fast: true
-
-## 0 · GROUND
-Touches (files · symbols):
-Anchors the contract cites:
-Ground SHA:
-
-## 1 · SPECIFY
-Feature:
-Must:
-Reject:
-Accept:
-Assumptions: ⚠ <most likely wrong> — why; if wrong: <cost>
-
-## 3 · CONTRACT
-Least-sure flag surfaced at freeze:
-Status: DRAFT
-
-## 4 · TESTS
-Plan:
-Tests live in: `./tests/` · MUST run red before Build.
-
-## 5 · BUILD
-Scope (may touch): `./src/`
+# atomic-node: the ONE template IS the lean render — _FAST_SECTIONS retired with
+# the lane scaffolds (the stripped blocks no longer exist in the template).
 
-## 6 · VERIFY
-Build expectations (from §1 Accept + §3 CONTRACT):
-### GATE RECORD
-Outcome:
-Reviewed by:
-"""
 
 _DEFAULT_WIDTH = 72       # fixed width for the persisted/canonical render (RETRO.md)
 
@@ -284,12 +311,39 @@ _TAG_TOKEN_RE = re.compile(r"(M\d+|R:[A-Za-z0-9_]+)")
 # --- autonomy levels (shared: autonomy resolvers + _AUTONOMY_ORDER/cmd_autonomy) ---
 _AUTONOMY_LEVELS = ("manual", "conservative", "auto")
 
-# --- streams posture (shared: streams resolvers + cmd_streams) — the parallel-vs-sequential
-#     half of the run mode (persist-run-mode); project-scoped, persisted in PROJECT.md beside autonomy ---
-_STREAMS_POSTURES = ("parallel", "sequential")
-
 # --- sensitivity taxonomy (shared: _task_sensitivity reader + cmd_freeze/status/audit) — the
 #     risk-CLASS the human declares in the TASK header at freeze (risk-sensitivity-taxonomy). The
 #     engine validates + surfaces a HUMAN-declared token; it NEVER classifies. A closed enum, sibling
-#     of _AUTONOMY_LEVELS/_STREAMS_POSTURES. Consumed downstream by advisor-gate-relax (mechanical). ---
+#     of _AUTONOMY_LEVELS. Consumed downstream by advisor-gate-relax (mechanical). ---
 _SENSITIVITY_VALUES = ("security", "data", "architecture", "mechanical")
+
+# --- gate mode (shared: _task_gate_mode reader + cmd_freeze's --ai-plan-verify path) — the
+#     two-way DIRECTION-freeze declaration (ai-plan-verify-gate): human (default) | ai-plan-verify.
+#     A closed 2-tuple, sibling of _AUTONOMY_LEVELS/_SENSITIVITY_VALUES — but,
+#     unlike them, listed in __all__: a NEW trust-loosening capability is deliberately surfaced via
+#     `from add_engine.constants import *`, not tucked into the _-prefixed sibling import list.
+#     Absent header line -> None from the resolver, treated as "human" by every caller (fail-closed
+#     default — never silently upgrades to the loosened path). ---
+_GATE_MODES = ("human", "ai-plan-verify")
+
+# --- skippable phases (shared: _task_skip_set reader + cmd_advance's skip pre-pass) — the
+#     fast-lane-skips closed tuple: the ONLY set cmd_advance's skip pre-pass ever tests `nxt`
+#     against (scenarios left it at phase-merge-specify: merged into specify, the retired
+#     header token is tolerated-and-ignored). specify/plan/tests/build/verify can NEVER be
+#     skipped — a structural
+#     exclusion (this tuple never names them), not a runtime-checked policy. Same relative order
+#     as PHASES. Listed in __all__ (mirrors _GATE_MODES): a new trust-loosening capability is
+#     deliberately surfaced via `from add_engine.constants import *`, not tucked away. ---
+_SKIPPABLE_PHASES = ()
+
+# --- format-dialect registry (shared: _dialect_gaps + the tests->build crossing warning +
+#     cmd_check's dialect_gap lint) — quality-floors floor 1. Closed (name, regex) pairs: a
+#     class matches only its FULL value shape, never prose fragments (a bare `2026-07-10`
+#     date must not match — the aware class requires the T separator + a zone suffix). Born
+#     from benchmark WV1 wm2: an arm's own suite stayed green on naive timestamps while the
+#     spec's own examples were Z-suffixed; the aware/naive crash shipped green. Listed in
+#     __all__ (mirrors _GATE_MODES): a new trust surface is deliberately surfaced. ---
+_DIALECT_CLASSES = (
+    ("aware-iso-timestamp",
+     r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})"),
+)

package/tooling/add_engine/guidelines.py

@@ -41,19 +41,17 @@ def _guideline_block() -> str:
         "\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:\n"
-        "Never weaken a test or edit a frozen contract to make a build pass; a security\n"
-        "finding is always HARD-STOP — never auto-passed.\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"
         "\n"
-        "Roster (from `add-method/agents/*.md`; adopt per phase — point at each phase guide, the floor above binds all):\n"
-        "- design · setup → contract · top\n"
-        "- build · tests → build · mid\n"
-        "- verify · verify → observe · top\n"
-        "- persona · any phase, cross-cutting service · mid\n"
-        "- advisor · any phase, cross-cutting service · top\n"
+        "Roster (from `add-method/agents/add.md`): ONE `add` agent — the spawn names the mode\n"
+        "(direction · build · verify · advise · persona); the agent loads that beat's phase guide\n"
+        "plus the best-fit `.add/personas/` persona (personas carry the expertise, the agent\n"
+        "carries the discipline; the floor above binds every mode).\n"
         "\n"
-        "On Claude Code the `add` skill drives this loop; other agents follow the three steps. The\n"
-        "book is in `.add/docs/`. 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. Book: https://pilotspace.github.io/ADD/. This block is generated by `add.py sync-guidelines` — edit outside the markers.\n"
         f"{_GUIDE_END}"
     )
 

package/tooling/add_engine/io_state.py

@@ -117,17 +117,32 @@ def _atomic_write_many(writes: list[tuple[Path, str]]) -> None:
 # --- root finding + state load/save + the shared error primitive ------------
 
 def find_root(start: Path | None = None) -> Path | None:
-    """Walk up from cwd to find a .add/ project root."""
+    """Walk up from cwd to find a .add/ project root.
+
+    Opt-in boundary: when `ADD_ROOT_CEILING` is set, the walk stops at that dir
+    (inclusive) and never ascends above it — so a workspace nested under an
+    ancestor project resolves ONLY its own root (or None before init), never the
+    parent's. Unset (every normal invocation) is the legacy walk to fs-root,
+    byte-identical. Both paths are resolved so a symlinked ceiling still matches.
+    """
     cur = (start or Path.cwd()).resolve()
+    _ceil = os.environ.get("ADD_ROOT_CEILING")
+    ceil = Path(_ceil).resolve() if _ceil else None
     for d in (cur, *cur.parents):
         if (d / ROOT_DIRNAME / STATE_FILE).exists():
             return d / ROOT_DIRNAME
+        if ceil is not None and d == ceil:
+            break
     return None
 
 def _require_root() -> Path:
     root = find_root()
     if root is None:
-        _die("no .add/ project found. Run `add.py init` first.")
+        # skip-error-ergonomics M2: hand the exact command with its flags — the
+        # bare "run init first" hint made every fresh headless agent read
+        # `init --help` before its first real call (LOOP-2 re-measure, all reps).
+        _die('no .add/ project found — run: add.py init --name "<project>" '
+             "--stage <prototype|poc|mvp|production>")
     return root
 
 def _migrate_state(state: dict) -> dict:
@@ -170,8 +185,60 @@ def _state_text_or_die(root: Path) -> str:
              f"`git checkout --ours/--theirs {STATE_FILE}`), then run `add.py doctor` to verify")
     return text
 
+# kickoff-truth M3 (contract v2): the dup-failure short-circuit. The 2026-07-13
+# transcript audit measured 12-21% of all engine calls as byte-identical repeats of
+# a call that had just failed the same way — the agent re-issues the command
+# unchanged instead of reading the error. The sig sidecar lives OUTSIDE the project
+# tree (OS tmp dir, keyed by md5(root path)): the engine's reject-writes-nothing
+# floor pins that a REJECTED command leaves the .add tree byte-identical, so the
+# hint state is ephemeral per-project cache, never a tree write. add.main()
+# registers each invocation and clears the sidecar on any successful exit, so only
+# CONSECUTIVE identical failures short-circuit. Fail-open everywhere: no root /
+# unreadable sidecar / any OSError -> no hint, never a block — a hint helper must
+# never change an error's outcome.
+_INVOCATION: list[str] | None = None    # set by add.main() per dispatch
+
+def _register_invocation(argv: list[str]) -> None:
+    global _INVOCATION
+    _INVOCATION = list(argv)
+
+def _last_fail_path() -> Path | None:
+    root = find_root()
+    if root is None:
+        return None
+    key = hashlib.md5(str(root.resolve()).encode("utf-8")).hexdigest()[:12]
+    return Path(tempfile.gettempdir()) / f"add-last-fail-{key}.json"
+
+def _clear_last_fail() -> None:
+    try:
+        side = _last_fail_path()
+        if side is not None:
+            side.unlink(missing_ok=True)
+    except OSError:
+        pass                            # hygiene only — success must never fail on it
+
+def _dup_fail_hint(msg: str) -> str | None:
+    try:
+        side = _last_fail_path()
+        if side is None:
+            return None
+        argv = _INVOCATION if _INVOCATION is not None else sys.argv[1:]
+        code_head = msg.split(":", 1)[0].strip()
+        sig = hashlib.md5((" ".join(argv) + "\n" + code_head).encode("utf-8")).hexdigest()
+        hint = None
+        if side.exists() and json.loads(side.read_text(encoding="utf-8")).get("sig") == sig:
+            hint = ("hint: this exact call already failed with the same error — change "
+                    "the command or input before retrying (add.py status shows the true state)")
+        side.write_text(json.dumps({"sig": sig}), encoding="utf-8")
+        return hint
+    except (OSError, ValueError):
+        return None
+
 def _die(msg: str, code: int = 1) -> None:
+    hint = _dup_fail_hint(msg)          # kickoff-truth M3 — fail-open, never raises
     print(f"add: error: {msg}", file=sys.stderr)
+    if hint:
+        print(hint, file=sys.stderr)
     raise SystemExit(code)