@pilotspace/add 1.8.0 → 1.9.0

package/tooling/add.py

@@ -152,6 +152,47 @@ 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:
+
+## 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:
+"""
+
+
 # --- low-level IO (designed for failure: atomic, no silent clobber) ----------
 
 def _now() -> str:
@@ -237,13 +278,14 @@ def _templates_dir() -> Path:
 def _render_template(name: str, **subs: str) -> str:
     """Load templates/<name>.tmpl and substitute {{key}} tokens.
 
-    Falls back to a built-in minimal template only for TASK.md.
+    Falls back to a built-in minimal template for TASK.md and the fast-lane TASK.fast.md.
     """
     tmpl = _templates_dir() / f"{name}.tmpl"
+    _fallbacks = {"TASK.md": _FALLBACK_TASK, "TASK.fast.md": _FALLBACK_TASK_FAST}
     if tmpl.exists():
         text = tmpl.read_text(encoding="utf-8")
-    elif name == "TASK.md":
-        text = _FALLBACK_TASK.replace("{title}", "{{title}}").replace(
+    elif name in _fallbacks:
+        text = _fallbacks[name].replace("{title}", "{{title}}").replace(
             "{slug}", "{{slug}}").replace("{date}", "{{date}}").replace("{stage}", "{{stage}}")
     else:
         text = ""
@@ -543,6 +585,80 @@ def _setup_locked(state: dict) -> bool:
     return ("setup" not in state) or (state["setup"].get("locked") is True)
 
 
+def _milestone_confirmed(state: dict, mslug: str) -> bool:
+    """True when milestone `mslug` is confirmed — i.e. the new-task gate is OPEN.
+
+    Mirrors `_setup_locked` one level down. A milestone record with NO "confirmed" key is
+    GRANDFATHERED-confirmed: every milestone created WITHOUT `--await-confirm` (and every
+    pre-existing one) is never gated. Opt-in: `new-milestone --await-confirm` seeds confirmed:false,
+    so the gate is active in exactly one case: the record is present AND confirmed is False. An
+    unknown milestone is treated as confirmed here (existence is cmd_new_task's separate check)."""
+    m = (state.get("milestones") or {}).get(mslug)
+    if not isinstance(m, dict) or "confirmed" not in m:
+        return True
+    return m["confirmed"] is True
+
+
+def _section_unfilled(md_text: str, header: str) -> bool:
+    """True iff the `header` section is PRESENT but UNFILLED — empty (no real bullet) or
+    still a `<…>` template placeholder. ABSENT section -> False (grandfathered legacy);
+    a filled section (>=1 real bullet, no `<…>`) -> False. Pure predicate — the shared
+    placeholder test the fill gates use (contract-fill at confirm; build-expectations at build)."""
+    body, in_sec, present = [], False, False
+    for ln in md_text.splitlines():
+        if ln.startswith(header):
+            in_sec, present = True, True
+            continue
+        if in_sec:
+            if ln.startswith("#"):          # ANY next header (## or ###) ends our section
+                break
+            if ln.lstrip().startswith(">"):  # skip blockquote GUIDANCE — it is not content
+                continue
+            body.append(ln)
+    if not present:
+        return False                        # absent -> grandfather
+    text = "\n".join(body).strip()
+    if not text:
+        return True                         # present but empty
+    return bool(re.search(r"<[^>\n]+>", text))   # a <…> placeholder remains
+
+
+def _stamp_gate_record(root: Path, state: dict, slug: str, outcome: str) -> None:
+    """Write-back (gate-record-writeback): mirror the resolved gate verdict into the task's
+    §6 `### GATE RECORD`, so the file and state.json never silently diverge (Finding C). Runs
+    for EVERY task — the write is ADDITIVE and never refuses, so (unlike the two refusal gates)
+    it needs no `--await-confirm` opt-in to protect the census. GRANDFATHER is the safety: a
+    GATE RECORD line is rewritten ONLY while it still holds a `<…>` placeholder; a resolved
+    (hand-filled) line is byte-untouched. No GATE RECORD block / no placeholder line / an
+    unreadable file -> silent no-op, the file stays byte-identical. Called AFTER save_state —
+    state is the source of truth; the file only mirrors it, so a write fault never loses a verdict."""
+    f = root / "tasks" / slug / "TASK.md"
+    try:
+        text = f.read_text(encoding="utf-8")
+    except OSError:
+        return                                   # unreadable -> no-op (never blocks the gate)
+    if "### GATE RECORD" not in text:
+        return                                   # nothing to mirror into
+    actor = _actor_stamp(state)
+    today = date.today().isoformat()
+    # each rule matches ONLY a line still carrying a `<…>` placeholder -> grandfather a resolved line.
+    rules = [
+        (r"(?m)^(Outcome:[ \t]*)<[^>\n]*>.*$", f"Outcome: {outcome}"),
+        (r"(?m)^Reviewed by:[ \t]*.*<[^>\n]*>.*$",
+         f"Reviewed by: {actor['name']} · date: {today}"),
+    ]
+    if outcome == "RISK-ACCEPTED":
+        w = ((state.get("tasks") or {}).get(slug) or {}).get("waiver") or {}
+        rules.append((r"(?m)^If RISK-ACCEPTED ->.*<[^>\n]*>.*$",
+                      f"If RISK-ACCEPTED -> owner: {w.get('owner', '?')} · "
+                      f"ticket: {w.get('ticket', '?')} · expires: {w.get('expires', '?')}"))
+    new = text
+    for pat, repl in rules:
+        new = re.sub(pat, repl, new, count=1)
+    if new != text:                              # no-op = no write (mtime stable)
+        _atomic_write(f, new)
+
+
 def _die(msg: str, code: int = 1) -> None:
     print(f"add: error: {msg}", file=sys.stderr)
     raise SystemExit(code)
@@ -763,6 +879,12 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     milestone = getattr(args, "milestone", None) or _active_milestone(state)
     if milestone and milestone not in state.get("milestones", {}):
         _die("unknown_milestone")
+    # confirm-parent gate (OPT-IN): a task may not be detailed before its parent milestone is
+    # human-confirmed — but ONLY when the milestone opted in via `new-milestone --await-confirm`.
+    # validate-then-write — refuse BEFORE any scaffold/state mutation. A milestone with no
+    # `confirmed` key (non-flag + pre-existing) is grandfathered (mirrors the setup-lock).
+    if milestone and not _milestone_confirmed(state, milestone):
+        _die(f"milestone_unconfirmed: confirm it first — add.py milestone-confirm {milestone}")
     depends_on = _parse_deps(getattr(args, "depends_on", None))
 
     # SEED (--from-delta): resolve a prior task's FIRST open SPEC delta into THIS task.
@@ -796,8 +918,13 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     # inherit the project's DECLARED autonomy default (task init-auto-default) — fail-SAFE:
     # absent -> auto, garbled -> conservative; the posture is project-scoped, not hardcoded.
     autonomy = _project_autonomy(root)
+    # fast lane (fast-new-task-flag): --fast scaffolds the MINIMAL template instead of the full one.
+    # The human opts in explicitly (the engine never guesses ceremony); the freeze floor is held by
+    # the freeze-before-build gate's fast arm (cmd_advance), so the lighter shape never drops the trust seam.
+    fast = bool(getattr(args, "fast", False))
     rendered = _render_template(
-        "TASK.md", title=title, slug=slug, date=date.today().isoformat(),
+        "TASK.fast.md" if fast else "TASK.md",
+        title=title, slug=slug, date=date.today().isoformat(),
         stage=state["stage"], autonomy=autonomy)
     if feature_override:                                     # pre-fill §1 from the seeded delta
         rendered = re.sub(r"(?m)^Feature:.*$",
@@ -822,6 +949,8 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     }
     if from_delta:
         state["tasks"][slug]["from_delta"] = from_delta     # lineage: seeded from <prior>
+    if fast:
+        state["tasks"][slug]["fast"] = True                 # durable lane marker (absent == not-fast)
     _set_active_task(state, slug, milestone)
     save_state(root, state)
     print(f"created task '{slug}' -> {task_md}")
@@ -938,7 +1067,29 @@ def cmd_advance(args: argparse.Namespace) -> None:
     # freezes — the unmarked predecessors are never retro-redded). REFUSE writes
     # nothing (fail-closed); below the build boundary the flag is never checked.
     if nxt == "build":
+        # the OPTED-IN crossing guards (fast-lane + flow-enforcement): a task whose PARENT
+        # milestone opted into --await-confirm is held to the trust floor at tests->build. A
+        # task under a plain / no milestone is never gated (every existing advance-to-build flow
+        # stays green). validate-then-write — every refusal runs BEFORE the tripwire/scope
+        # snapshots below, writing nothing; the task stays at `tests`.
+        _ms = state["tasks"][slug].get("milestone")
+        _optin = bool(_ms) and (state.get("milestones") or {}).get(_ms, {}).get("await_confirm") is True
         raw3 = _raw_phase_bodies(root, slug).get(3, "")
+        # freeze-before-build gate (fast-lane): "collapse-never-skip" made REAL — the freeze is
+        # engine-enforced for an opted-in milestone OR any --fast task (the fast arm, fast-new-task-flag:
+        # a fast task is held to the floor under ANY milestone, so the lighter lane never drops the
+        # trust seam). PRECEDES build-expectations: you freeze §3 before pre-declaring §6's outcomes.
+        _freeze_gated = _optin or state["tasks"][slug].get("fast") is True
+        if _freeze_gated and not _contract_frozen(raw3):
+            _die("contract_not_frozen: freeze §3 before crossing into build — approve "
+                 f"the contract in {slug}'s TASK.md (Status: FROZEN @ vN)")
+        # build-expectations gate (flow-enforcement): an opted-in task may not enter build until
+        # its §6 `### Build expectations` are pre-declared — so verify checks the build is RIGHT,
+        # not just green. Same opt-in switch as the contract-fill gate, one level out.
+        if _optin:
+            if _section_unfilled(_raw_phase_bodies(root, slug).get(6, ""), "### Build expectations"):
+                _die("build_expectations_unfilled: fill the §6 '### Build expectations' block "
+                     f"of {slug}'s TASK.md before crossing into build")
         if _contract_frozen(raw3):
             if not _flag_well_formed(raw3):
                 _die("unflagged_freeze: a frozen §3 must surface a well-formed "
@@ -1126,6 +1277,7 @@ def cmd_gate(args: argparse.Namespace) -> None:
     state["tasks"][slug]["gate_actor"] = _actor_stamp(state)   # WHO recorded the verdict (every outcome)
     state["tasks"][slug]["updated"] = _now()
     save_state(root, state)
+    _stamp_gate_record(root, state, slug, args.outcome)   # mirror the verdict into §6 (Finding C)
     print(f"task '{slug}' gate -> {args.outcome}")
     # the engine-sourced next step (next-footer-engine): a completing gate hands off to the
     # state arm; HARD-STOP routes to "resolve HARD-STOP …" — converging the old bespoke line.
@@ -1531,7 +1683,10 @@ def cmd_status(args: argparse.Namespace) -> None:
     if _rel:
         print(f"  → {RELEASABLE_CUE.format(n=len(_rel))}")
 
-    print(f"active  : {active or '(none)'}")
+    # fast-lane marker (fast-new-task-flag): tag an ACTIVE fast task so the lane is visible at a
+    # glance. Presentation-only, existence-gated — a plain/absent active task is byte-unchanged.
+    _fast_mark = " · fast" if active and tasks.get(active, {}).get("fast") is True else ""
+    print(f"active  : {active or '(none)'}{_fast_mark}")
     # parallel streams (parallel-status-view): when >=2 milestones are active, render each as its
     # own stream (active task + phase) so a user working N fronts reads them all at once. ADDITIVE —
     # the N<=1 output above is byte-identical (the standing additive-cue convention); presentation
@@ -2577,17 +2732,64 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
     _atomic_write(mfile, _render_template(
         "MILESTONE.md", title=title, goal=args.goal or "<goal>",
         stage=args.stage, date=date.today().isoformat()))
-    state["milestones"][slug] = {
+    # confirm-parent gate (OPT-IN, mirrors `init --await-lock`): `--await-confirm` seeds the
+    # milestone UNCONFIRMED so new-task is held until `add.py milestone-confirm`. WITHOUT the flag
+    # NO `confirmed` key is written → grandfathered-confirmed → no gate (so the existing engine
+    # tests stay byte-green). The guided skill flow passes the flag at the human-review point.
+    await_confirm = bool(getattr(args, "await_confirm", False))
+    record = {
         "title": title, "goal": args.goal or "", "stage": args.stage,
         "status": "active", "created": _now(), "updated": _now(),
     }
+    if await_confirm:
+        # `await_confirm` is the STABLE opt-in marker (set ONLY here, at creation). `confirmed`
+        # alone is NOT a reliable opt-in signal: milestone-confirm stamps confirmed:true on a plain
+        # milestone too, so a later build-entry gate must key on `await_confirm`, not `confirmed`.
+        record.update(confirmed=False, confirmed_at=None, confirmed_by=None, await_confirm=True)
+    state["milestones"][slug] = record
     _set_active_milestone(state, slug)
     save_state(root, state)
     print(f"created milestone '{slug}' -> {mfile}")
-    print("active milestone set.")
+    print("active milestone set." + ("" if not await_confirm else
+          "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
     print(_next_footer(root, state))   # converges the old "Decompose it into tasks: …" hint
 
 
+def cmd_milestone_confirm(args: argparse.Namespace) -> None:
+    """The human gate that opens new-task for a milestone (confirm-parent). Mirrors `cmd_lock`
+    one level down: the human reviews the filled MILESTONE.md, then RECORDS confirmation here.
+    The engine never self-confirms. Validate-then-write; re-confirm is an idempotent note."""
+    root = _require_root()
+    state = load_state(root)
+    slug = args.slug
+    if slug not in state.get("milestones", {}):
+        _die("unknown_milestone")
+    m = state["milestones"][slug]
+    if m.get("confirmed") is True:
+        print(f"milestone '{slug}' already confirmed (by {m.get('confirmed_by', '?')}).")
+        return
+    # contract-fill gate (flow-enforcement, OPTED-IN only): a milestone that opted into
+    # --await-confirm (carries a `confirmed` key) may not be confirmed until its cross-task
+    # `## Shared / risky contracts` section is filled — so "confirmed" MEANS the contracts
+    # were present at confirm time. A grandfathered no-key milestone keeps the plain stamp
+    # (gate skipped — keeps the census + existing flows green). Validate-then-write.
+    if "confirmed" in m:
+        mfile = root / "milestones" / slug / MILESTONE_FILE
+        md = mfile.read_text(encoding="utf-8") if mfile.exists() else ""
+        if _section_unfilled(md, "## Shared / risky contracts"):
+            _die("milestone_contracts_unfilled: fill the '## Shared / risky contracts' "
+                 f"section of {slug}'s MILESTONE.md before confirming")
+    who = getattr(args, "by", None) or getpass.getuser()
+    m["confirmed"] = True
+    m["confirmed_at"] = _now()
+    m["confirmed_by"] = who
+    m["actor"] = _actor_stamp(state)   # structured actor alongside the free-text confirmed_by
+    m["updated"] = _now()
+    save_state(root, state)
+    print(f"confirmed milestone '{slug}' (by {who}) — new-task is now open for it.")
+    print(_next_footer(root, state))
+
+
 def cmd_ready(args: argparse.Namespace) -> None:
     if getattr(args, "json", False):
         _, state = _load_state_for_json()
@@ -5696,6 +5898,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="with --from-delta: target the UNIQUE open SPEC delta whose text "
                          "contains SUBSTR (case-insensitive) instead of the first")
     pn.add_argument("--force", action="store_true", help="overwrite TASK.md if present")
+    pn.add_argument("--fast", action="store_true",
+                    help="opt into the fast lane: scaffold the minimal TASK.fast.md template + "
+                         "hold the task to the freeze floor under any milestone")
     pn.set_defaults(func=cmd_new_task)
 
     pdd = sub.add_parser("drop-delta",
@@ -5712,8 +5917,18 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("--goal", default=None, help="one-sentence outcome")
     pm.add_argument("--stage", default="mvp", choices=STAGES)
     pm.add_argument("--force", action="store_true", help="overwrite MILESTONE.md if present")
+    pm.add_argument("--await-confirm", action="store_true",
+                    help="opt into the confirm-parent gate: seed the milestone unconfirmed so "
+                         "new-task is held until `milestone-confirm` (mirrors `init --await-lock`); "
+                         "the guided skill flow passes this at the human-review point")
     pm.set_defaults(func=cmd_new_milestone)
 
+    pmc = sub.add_parser("milestone-confirm",
+                         help="confirm a milestone (the human gate that opens new-task for it)")
+    pmc.add_argument("slug")
+    pmc.add_argument("--by", default=None, help="free-text confirmer name (defaults to the OS user)")
+    pmc.set_defaults(func=cmd_milestone_confirm)
+
     pr = sub.add_parser("ready", help="list tasks whose dependencies are satisfied")
     pr.add_argument("--json", action="store_true", help="machine-readable JSON output")
     pr.set_defaults(func=cmd_ready)

package/tooling/templates/TASK.fast.md.tmpl

@@ -0,0 +1,72 @@
+# TASK: {{title}}
+
+slug: {{slug}} · created: {{date}} · stage: {{stage}}
+autonomy: {{autonomy}}
+phase: ground   <!-- fast lane: ground -> specify -> contract -> tests -> build -> verify -> observe -> done -->
+fast: true   <!-- the fast lane: a small task, collapsed flow + minimal template. Omit --fast for full rigor. -->
+
+> Fast lane — one small task, minimal sections, filled top-to-bottom. The trust floor still
+> holds: a FROZEN §3 contract · ≥1 red test before build · a recorded §6 gate (security = HARD-STOP).
+> The acceptance scenario collapses into §1 `Accept:`; OBSERVE is one optional line at the gate.
+
+---
+
+## 0 · GROUND — the real codebase
+
+Touches (files · symbols): <path:symbol — what it is / how it is keyed>
+Anchors the contract cites: <the symbols §3 will name>
+
+---
+
+## 1 · SPECIFY — the rules
+
+Feature: <name>
+Must:
+  - <required behavior>
+Reject:
+  - <bad input / situation> -> "<error_code>"
+Accept: <the one acceptance scenario, Given/When/Then condensed to one line — it drives the §4 test>
+Assumptions: ⚠ <the one most likely wrong> — why; if wrong: <cost>   (or "none material — biggest risk: X")
+
+---
+
+## 3 · CONTRACT — freeze the shape
+
+```
+<the shape that freezes: signature / fields · success + each rejection's response>
+```
+
+`Least-sure flag surfaced at freeze:` <[spec|contract|test] the point most likely wrong — why; if wrong: cost>
+Status: DRAFT
+<!-- The freeze IS the one approval. Approved -> Status: FROZEN @ vN — approved by <name>.
+     Changing a frozen contract = change request back to SPECIFY. -->
+
+---
+
+## 4 · TESTS — failing-first (red)
+
+Plan: test_<accept> — assert the §1 Accept line's Then (behavior, not internals).
+Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
+
+---
+
+## 5 · BUILD — AI writes code
+
+Scope (may touch): `./src/`   <every file the build may write — declared before the §3 freeze>
+Code lives in: `./src/`   ·   Constraints: change no test, no contract; allow-list packages only.
+
+---
+
+## 6 · VERIFY — evidence + gate
+
+- [ ] all tests pass · coverage held · no test or contract altered during build
+- [ ] green was EARNED — no overfit / vacuous asserts / stubbed-away logic
+- [ ] no exposed secrets, injection openings, or unexpected dependencies (security = HARD-STOP)
+
+Build expectations (from §1 Accept + §3 CONTRACT): <the observable outcome a correct build must produce — confirmed by <how / where>>
+
+### GATE RECORD
+Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
+Reviewed by: <name> · date: <date>
+<!-- A security finding is ALWAYS HARD-STOP. Record exactly one outcome — no silent pass.
+     OBSERVE (optional): one `[SPEC · open]` or competency-delta line here if the loop taught the foundation something. -->