@pilotspace/add 1.10.0 → 1.11.0

package/tooling/add_engine/__init__.py

@@ -0,0 +1,5 @@
+"""add_engine — the ADD engine, modularized.
+
+add.py is the runnable entry; the engine body lives here as focused modules.
+Started by the engine-modularization milestone (first module: constants).
+"""

package/tooling/add_engine/accessors.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""add_engine.accessors — pure active-task / active-milestone state-dict accessors.
+
+In-memory readers/mutators over the state dict (no file IO, no imports beyond
+__future__). Extracted from add.py (engine-modularization 4/N); add.py re-exports
+them as module globals so `add._active_task` etc. resolve unchanged.
+"""
+from __future__ import annotations
+
+
+def _active_milestone(state: dict) -> str | None:
+    """The primary active milestone — the N<=1 scalar mirror (== active_milestones[0])."""
+    return state.get("active_milestone")
+
+def _active_task(state: dict, milestone: str | None = None) -> str | None:
+    """The active task: per-milestone when `milestone` is given (partial-state -> None),
+    else the global/primary scalar active task. Total — never raises."""
+    if milestone is None:
+        return state.get("active_task")
+    return (state.get("active_tasks") or {}).get(milestone)
+
+def _set_active_milestone(state: dict, slug: str | None) -> None:
+    """Set the primary active milestone, keeping `active_milestones` consistent (N<=1 sync)."""
+    state["active_milestone"] = slug
+    state["active_milestones"] = [] if slug is None else [slug]
+
+def _set_active_task(state: dict, slug: str | None, milestone: str | None = None) -> None:
+    """Set the active task, keeping the scalar mirror AND the per-milestone map in sync.
+    With no owning active milestone the active task is scalar-only (the migration's orphan
+    rule); clearing (slug is None) pops the milestone's entry."""
+    state["active_task"] = slug
+    ms = milestone if milestone is not None else _active_milestone(state)
+    tasks_map = state.setdefault("active_tasks", {})
+    if ms is None:
+        return
+    if slug is None:
+        tasks_map.pop(ms, None)
+    else:
+        tasks_map[ms] = slug
+
+def _activate_milestone(state: dict, slug: str) -> None:
+    """Add a milestone to the active SET (idempotent) and make it the primary focus,
+    syncing the scalar active_task to that milestone's entry. Does NOT remove other members
+    (this is how a user reaches N>=2 active milestones)."""
+    ms_list = state.setdefault("active_milestones", [])
+    if slug not in ms_list:
+        ms_list.append(slug)
+    state["active_milestone"] = slug
+    state["active_task"] = (state.get("active_tasks") or {}).get(slug)
+
+def _deactivate_milestone(state: dict, slug: str) -> None:
+    """Remove a milestone from the active SET, pop its active-task entry, and (if it was the
+    primary) repoint the primary to the most-recent remaining member (or None when empty)."""
+    ms_list = state.setdefault("active_milestones", [])
+    if slug in ms_list:
+        ms_list.remove(slug)
+    (state.setdefault("active_tasks", {})).pop(slug, None)
+    if state.get("active_milestone") == slug:
+        new = ms_list[-1] if ms_list else None
+        state["active_milestone"] = new
+        state["active_task"] = (state.get("active_tasks") or {}).get(new) if new else None

package/tooling/add_engine/autonomy.py

@@ -0,0 +1,58 @@
+"""add_engine.autonomy — autonomy-level read & resolve (engine-modularization 16/N).
+
+Read the declared level off a task header, resolve the effective level (declared else the
+project default), and read the project default token. A closed, unpatched cluster
+(transitive-closure AST = zero outbound). The cluster-private _AUTONOMY_LINE_RE lives here;
+the SHARED _AUTONOMY_LEVELS lives in constants.py. Deps: constants + taskdoc (_task_header)
++ stdlib; no add.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+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)
+
+
+def _autonomy_level(hdr: str):
+    """The declared autonomy rung from a TASK.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
+    the set was written (unknown). PURE."""
+    m = _AUTONOMY_LINE_RE.search(hdr)
+    if not m:
+        return None
+    tok = m.group(1).strip().lower()
+    return tok if tok in _AUTONOMY_LEVELS else "?"
+
+def _effective_autonomy(root: Path, state: dict, slug: str) -> str:
+    """The autonomy rung that governs `slug` right now: the task's own declared rung,
+    falling back to the project default when the task line is UNSET (None) or an
+    unrecognized token ("?") — the same fail-safe chain cmd_new_task seeds from
+    (_project_autonomy: absent -> auto, garbled -> conservative). PURE. `state` is unused
+    today; it is kept in the signature beside _driver_stop for symmetry."""
+    lvl = _autonomy_level(_task_header(root, slug))
+    return lvl if lvl in _AUTONOMY_LEVELS else _project_autonomy(root)
+
+def _project_autonomy_token(root: Path):
+    """The RAW autonomy declaration in PROJECT.md — a recognized rung, None when no
+    declaration line is present, or "?" for a real-but-unrecognized token. Uses the
+    anchored _autonomy_level (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 _autonomy_level(re.sub(r"<!--.*?-->", "", text, flags=re.S))
+
+def _project_autonomy(root: Path) -> str:
+    """The autonomy rung a new task INHERITS from the project default. Fail-SAFE:
+    no declaration -> "auto" (the method default; v7: absent = auto); an unrecognized
+    token -> "conservative" (NEVER silently "auto"); an unreadable foundation -> "auto".
+    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)

package/tooling/add_engine/components.py

@@ -0,0 +1,117 @@
+"""add_engine.components — the component-aware-add subsystem (engine-modularization 11/N).
+
+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).
+"""
+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.
+    The v2 confinement check — no read is attempted on a path that fails it."""
+    try:
+        return p.resolve().is_relative_to(rootp)
+    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
+    token, whole-subtree prefix containment for a directory token ('…/')."""
+    for tok in declared:
+        if tok.endswith("/"):
+            if rel.startswith(tok) or rel == tok.rstrip("/"):
+                return True
+        elif rel == tok:
+            return True
+    return False

package/tooling/add_engine/constants.py

@@ -0,0 +1,221 @@
+"""add_engine.constants — engine constants (moved verbatim from add.py).
+
+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).
+"""
+import re
+from pathlib import Path
+
+__all__ = [
+    "ROOT_DIRNAME",
+    "STATE_FILE",
+    "MILESTONE_FILE",
+    "GOAL_UNSET",
+    "STAGES",
+    "GRADUATION_CUE",
+    "RELEASABLE_CUE",
+    "RELEASES_FILE",
+    "PHASES",
+    "GATES",
+    "HEAL_CAP",
+    "PHASE_GUIDE",
+    "PHASE_OWNER",
+    "SETUP_FILES",
+    "GUIDELINE_FILES",
+    "RULES_FILE_REL",
+    "WORKFLOW_HEADINGS",
+]
+
+ROOT_DIRNAME = ".add"
+STATE_FILE = "state.json"
+MILESTONE_FILE = "MILESTONE.md"
+# The project GOAL (v20) is read live from PROJECT.md — never copied into state.json
+# (single-source; the foundation is the truth). A missing/blank source degrades to
+# 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")
+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
+# the task to BUILD for an honest redo; after HEAL_CAP such attempts the next confirmed cheat
+# forces a HARD-STOP escalation to the human. MONOTONIC — attempts never auto-resets (a gamed
+# green is never auto-passed; the loop is never unbounded).
+HEAL_CAP = 3
+
+
+
+# `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",
+                  "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",
+                  "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`
+# 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",
+}
+SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md")
+
+# Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
+# never reach git. Bare-filename patterns match at any depth under .add/ (tasks/,
+# milestones/, archive/). These are working state, not records: scope-snapshot.json
+# is the tests->build touch baseline the verify scope-gate reads from disk (the
+# durable scope declaration is the state.json anchor); pre-archive-state.bak.json is
+# archive-milestone's pre-delete recovery net — needed on disk, never in history;
+# pre-update-state.bak.json is the installer update's pre-write state backup (cli.js
+# cmdUpdate / pip _installer.update) — same "on disk, never in git" need; .update-cache.json
+# is the update-nudge's once-a-day registry throttle. All stay on disk; git-ignoring them
+# is hygiene, never deletion. SINGLE-SOURCED: this constant is kept byte-identical to
+# tooling/templates/gitignore.tmpl (test_gitignore_bak_seed parity) so the installers,
+# which seed/refresh .add/.gitignore from that template on update, never drift from init.
+_GITIGNORE_BODY = """\
+# ADD engine transient artifacts — local working state, never committed.
+# (Scaffolded by `add.py init`; refreshed additively by the installer on update.)
+scope-snapshot.json
+pre-archive-state.bak.json
+pre-update-state.bak.json
+.update-cache.json
+"""
+
+# Guideline-injection targets + version-stable markers. NEVER change these marker
+# strings: a re-run finds the old block by exact match, so changing them would
+# orphan every block written by a prior version (see TASK guideline-inject).
+GUIDELINE_FILES = ("AGENTS.md", "CLAUDE.md")
+_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"
+
+# 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}
+
+slug: {slug} · created: {date} · stage: {stage}
+autonomy: auto
+phase: ground
+
+## 0 · GROUND
+Touches (files · symbols · signatures):
+Honors (patterns / conventions):
+Anchors the contract cites:
+
+## 1 · SPECIFY
+Feature:
+Framings weighed:
+Must:
+Reject:
+After:
+Assumptions — lowest-confidence first:
+  ⚠ <most likely wrong> — lowest confidence because <why>; if wrong: <cost>
+
+## 2 · SCENARIOS
+## 3 · CONTRACT
+Status: DRAFT
+## 4 · TESTS
+## 5 · BUILD
+## 6 · VERIFY
+### GATE RECORD
+Outcome:
+## 7 · OBSERVE
+### Spec delta
+### Competency deltas
+"""
+
+
+# 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:
+
+## 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/`
+
+## 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)
+
+
+# --- shared delta-parsing regexes (used by taskdoc readers AND the deltas-web lint) ---
+_DELTA_RE = re.compile(
+    r"\s*-\s*\[\s*(DDD|SDD|UDD|TDD|ADD)\s*·\s*(open|folded|rejected)\s*\]\s*(.+)$"
+)
+_EVIDENCE_RE = re.compile(r"^(.*?)\s*\(evidence:\s*(.*?)\)\s*$")
+_SPEC_DELTA_RE = re.compile(
+    r"\s*-\s*\[\s*(SPEC)\s*·\s*(open|seeded|dropped)\s*\]\s*(.+)$"
+)
+
+
+# --- autonomy levels (shared: autonomy resolvers + _AUTONOMY_ORDER/cmd_autonomy) ---
+_AUTONOMY_LEVELS = ("manual", "conservative", "auto")