@pilotspace/add 1.17.0 → 2.1.0

package/skill/add/phases/7-observe.md

@@ -1,45 +0,0 @@
-# Phase 7 — Observe (feed the next loop)
-
-Goal: release deliberately, watch reality, turn what you learn into the next spec. Fill **§7** in TASK.md.
-
-## Do
-
-1. **Release behind a scope-of-impact limit** — a flag and/or gradual rollout
-2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" now
-   define what you alert on: overall error rate, each rejection's rate (a spike is a
-   signal), latency of the risky op.
-3. **Draft the next spec delta** — every defect, surprise, or new need becomes a
-   change that re-enters the flow at Specify (a new task).
-4. **Propose a voice delta** — note where your voice diverged from the human's (wordings +
-   flow); propose a confirmable **voice delta** tuning `SOUL.md`, emitted `open`. The human
-   confirms, then you rewrite the routed section. Read `soul.md` (grammar, routing,
-   human-is-only-writer).
-
-> **Decisions (ADR)** — at the gate the engine harvests §7's ADR block (§1/§3/§5/§6); `add.py audit` flags one never harvested.
-
-## AI prompt
-
-<prompt>
-Role: a reliability analyst feeding the next cycle.
-Read first: telemetry · objectives · incidents.
-Steps: 1. report error-budget burn · 2. cluster errors, surface the top real failures ·
-  3. draft a SPEC delta with evidence links.
-Never: auto-roll-back — recommend; a human owns the production decision.
-</prompt>
-
-## Exit gate
-
-<exit_gate>
-- [ ] Released behind a flag/rollout.
-- [ ] Scenario-based monitors live.
-- [ ] A reviewed spec delta captured (becomes the next `new-task`).
-</exit_gate>
-
-> **Persona** — tag `· persona:<slug> · critical-rule|success-metric|anti-pattern|ability`;
-> `fold` grows that section — a HOW-an-agent-behaves lesson belongs in a persona, not the shared pile.
-> **Advisor · Confidence** — spawn a reviewer to mine the run for lessons (advisor.md); score Self-evaluation — did this loop teach the foundation? (confidence.md).
-
-## Next
-
-Loop — the artifacts are living docs the next cycle refines.
-Map: `self-improve.md` · book: `docs/09-the-loop.md`

package/skill/add/phases/fast-lane.md

@@ -1,34 +0,0 @@
-# Fast lane — less ceremony, same floor
-
-The fast lane is the **collapsed, opt-in task path for small work**. Same flow — ground → specify →
-contract → tests → build → verify — with fewer sections and the bundle approved in one pass. It
-**collapses** the ceremony; it never drops the floor. The human opts in (`--fast`); the engine never
-guesses that a task is small.
-
-## When
-
-Pick it for a **small, low-risk, roughly single-file change**. Stay on the full lane when the work
-wants its scenarios enumerated — a milestone or release, an architecture or security change, anything
-cross-cutting, or anything you are not yet sure is small. In doubt, run the full lane.
-
-## How
-
-1. `add.py new-task <slug> --fast` scaffolds the minimal `TASK.fast.md` (sections {0,1,3,4,5,6};
-   §2 SCENARIOS and §7 OBSERVE dropped — §1's Accept line carries the behavior a scenario would).
-2. Ground, draft §1 + §3, and **freeze the contract as one batched approval** — the single decision
-   point, led by the lowest-confidence flag.
-3. Write a **red** test (§4), run it failing for the right reason.
-4. Build (§5) to green, then record the **verify gate** (§6).
-
-Both human gates (freeze, verify) render `report-template.md` too — the fast lane collapses
-sections, never the report.
-
-## Floor kept, only collapsed
-
-Three things never move, on either lane: a **frozen** §3 before build · a **red** test before build ·
-a recorded **verify gate** at the end (a security finding is always HARD-STOP). A `--fast` task is
-freeze-gated under ANY milestone — `advance` refuses `contract_not_frozen` while §3 is a draft. Speed
-comes from **fewer sections + auto-gating**, not from cutting any of the three.
-
-Not a way around the contract, the red test, or the gate; not for milestones or releases; not
-engine-chosen — ceremony is human-owned.

package/skill/add/release.md

@@ -1,61 +0,0 @@
-# Release — cut a versioned ship, never an unwatched flip
-
-A project releases when ≥1 **closed milestones** are bundled into a versioned cut whose notes are evidence-backed, risk is disclosed, and behaviour is then watched. This is the **5th scope level** — distinct from milestone (feature-complete), graduation (rigor shift), and stage (mvp→prod).
-
-- **milestone** = feature-complete and consolidated; **release** = shipped + watched.
-- **graduation** changes *rigor*; a **release** ships a *version*. Orthogonal axes.
-
-You **gather and propose**; the **human confirms and ships**; the engine records the cut and enforces a floor — it **never tags, publishes, or deploys**.
-
-## The cue
-
-When ≥1 milestone is `done` AND archived AND not yet attributed to a release, `add.py status` prints:
-
-```
-  → releasable: N milestone(s) closed since last release
-```
-
-That line is a tally over unreleased-but-archived milestones — never a readiness judgment.
-
-## The flow
-
-One arc, seven steps: **cue → gather → draft notes → readiness floor → human confirms → cut → watch.**
-
-1. **Gather** — run `add.py release-report` (`--json` to branch on it). It clusters the cut's evidence: closed milestones since last release · consolidated deltas · open RISK-ACCEPTED waivers · open security HARD-STOP (blocker) · §2 scenarios to take live as monitors. Gathers, never judges.
-2. **Draft notes** — write a [Keep a Changelog](https://keepachangelog.com/) entry from the consolidated deltas + each milestone's goal. Group Added / Changed / Fixed. Propose the **semver bump** (breaking→MAJOR, feature→MINOR, fix-only→PATCH) for human confirmation.
-3. **Readiness floor** — the engine enforces: suite green, zero open security HARD-STOP, every RISK-ACCEPTED waiver signed and disclosed in the notes.
-4. **Human confirms** — present via `report-template.md`, opening with the ARC (goal · done · plan). Render as a guided choice (per `report-template.md`). Never pre-stamp; show-before-ask.
-5. **Cut** — only now run `add.py release <version> --notes <file>`. The engine records: CHANGELOG entry, append-only `RELEASES.md` row (newest-first: date · version · milestones · waivers · evidence), milestone attribution.
-6. **Ship** — the **human** runs the tag / publish / deploy (`git tag`, `npm publish`, deploy pipeline). Engine never performs it.
-7. **Watch** — §2 scenarios become live monitors. A regression re-enters at Specify as a **change request** → PATCH hotfix release.
-
-## The floor
-
-`add.py release <version>` is **guarded** — refuses (non-zero exit, state byte-unchanged) on:
-
-<reject_codes>
-- `release_security_open` — open security HARD-STOP exists. Never shipped. `--force` does NOT override this.
-- `release_build_in_flight` — a build is in flight, ungated.
-- `release_no_closed_milestone` — nothing new since last release.
-- `release_undisclosed_waiver` — a RISK-ACCEPTED waiver rides into the release but is absent from the notes.
-</reject_codes>
-
-`--force` preserves human authority for grandfathered / edge cases (e.g. brownfield first cut) — never overrides `release_security_open`.
-
-## Invariants
-
-- **Engine records; human ships.** `add.py release` writes CHANGELOG + ledger + attribution; never tags, publishes, or deploys.
-- **Security is a HARD-STOP at the cut**, not just at verify. No `--force`, no waiver, no exception.
-- **Notes draw from consolidated deltas** — release after `fold.md` has run. Lifecycle order: `milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
-- **Ledger is append-only (newest-first)** — a release row is never rewritten; a yanked version gets a new row.
-- **A release bundles, it does not equal.** One version may attribute several milestones.
-
-## Depth by stage
-
-- **prototype/poc** — one-line preview note + tag; no deploy ceremony.
-- **mvp** — full notes + tag + guarded publish; watch headline scenarios.
-- **production** — full rigor: notes + tag + deploy behind rollback-tested pipeline + live monitors + error-budget watch. Hotfix path (step 7) is first-class.
-
-## Worked example
-
-The `udd-design-loop` milestone closed (4/4), consolidated into `foundation-version 33`; the human drafted `## [1.5.0]` from those deltas, bumped version sources in lockstep, and `test_release_1_5_0.py` asserted readiness. The `git tag` stayed human-gated; live-registry confirmation gathered *after* the tag as verify evidence, never a unit test.

package/skill/add/scope.md

@@ -1,72 +0,0 @@
-# Scope drafting — turn a classified request into a versioned MILESTONE.md
-
-`intake.md` CLASSIFIES a request into a bucket; scope drafting turns that into a confirmed, well-formed, versioned `MILESTONE.md` through discussion. The MILESTONE.md template is the SHAPE; this rubric is HOW to fill it well.
-
-## What to do per intake outcome
-
-| intake outcome | scope-loop action | creates (after confirm) |
-|----------------|-------------------|-------------------------|
-| `new-major` / `sub-milestone` | draft ONE MILESTONE.md (fill the template via discussion) | 1 milestone |
-| `task` | route to `add.py new-task <slug>` (fits the active milestone) | 0 milestones |
-| `change-request` | route to SPECIFY/CONTRACT of the affected task | 0 milestones |
-| `split_required` | draft ALL N items as a batch in ONE pass | N milestones/tasks |
-
-**Confirm before create is the convention.** "One pass" means one drafting pass, NOT auto-creation — nothing is written until the human confirms; enforced only by the opt-in `--await-confirm` (below).
-
-**Confirm the milestone before detailing tasks.** `new-milestone <slug> --await-confirm` seeds it *unconfirmed* — `new-task` is HELD (`milestone_unconfirmed`) until you show the filled `MILESTONE.md`, get the human's go, and run `milestone-confirm <slug>`. Keeps you from digging into task §0–§5 before the parent is agreed. (Omit the flag: no gate.)
-
-## Position the goal — ground in assets, relate to the milestone map   (do this FIRST)
-
-Before drafting the goal sentence, position the request in what already exists — distinct from intake's classification, not redundant with it.
-
-1. **Ground in current assets.** Read the goal against what exists — the goal must reflect what the project already is. Ground as rigorously as a task's §0 (`phases/0-ground.md`), using the **same four fields** at milestone scope: **Touches** (the subsystems/files the milestone spans) · **Context** (the docs · todos · config · data it works against) · **Honors** (the `PROJECT.md` / `CONVENTIONS.md` invariants it must respect) · **Anchors** (the existing contracts/symbols its tasks will cite). Grounding is complete when each is named from real assets, not assumed. Touches spanning >1 app root (BE+FE, or multiple independently-testable dirs)? weigh `.add/components.toml` (`components.md`) now — before tasks decompose with flat cross-app paths.
-2. **Relate to the milestone map.** Run `add.py search <keyword> [<keyword> ...]` first — then read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
-3. **If the goal is already delivered** by an existing milestone, reject `duplicate_goal` and route as `task` or `change-request`.
-
-## Brainstorm before you draft — co-specify at milestone level
-
-Don't draft from thin input. Run the three-move co-specify (`phases/1-specify.md`) — Diverge → Converge → Validate — raised to milestone scope. Ask only what moves the goal, the In/Out line, or the task list.
-
-Diverge seeds (pick the live ones):
-- **Outcome** — done means a user can do *what* they can't today?
-- **Edge of scope** — nearest thing assumed IN that you want OUT?
-- **Riskiest decision point** — which contract, if wrong, costs the most rework?
-- **Done-looks-like** — how do we SEE each outcome without reading code?
-- **First slice** — which task unblocks the rest?
-
-Rank assumptions lowest-confidence first; top 1–2 get the flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. Present via `report-template.md` — open with the ARC (goal · done · plan), render as a guided choice.
-
-## Drafting a good MILESTONE.md (section by section)
-
-- **goal** — ONE outcome sentence (no "and" — that is two milestones).
-- **rationale** — intake bucket + WHY, AND the milestone relationship from "Position the goal". Never in state.json.
-- **Scope In/Out** — explicit anti-creep deferral list. An empty Out list means scope is not yet thought through. UI/UX scope? use the template's Scope hint vocabulary, not generic prose.
-- **Shared decisions & glossary deltas** — cross-cutting rules every task must honor. New terms get a glossary entry.
-- **Shared / risky contracts to freeze first** — decision points between tasks; name the owning task.
-- **Tasks (breadth-first)** — `slug · depends-on · one line` each. Decompose by deliverable; keep each task one-file-sized.
-- **Exit criteria** — observable; **every exit criterion maps to a declared task slug** (no dangling criterion).
-- **Close — ship review** + **Release steps** — **drafted-blank** here; filled LATER (`milestone-done` and `release.md`). Named so you know the full 9-section shape.
-
-## Draft well-formedness gate
-
-A scope draft is well-formed only when:
-- [ ] goal is ONE outcome sentence (no "and")
-- [ ] every exit criterion maps to a declared task slug (no dangling criterion)
-- [ ] `rationale` records the bucket + milestone relationship from "Position the goal"
-- [ ] `Close — ship review` and `Release steps` are left as the template (drafted-blank)
-- [ ] the In/Out list names what is deferred
-
-Propose only a well-formed draft — an incomplete one lets a milestone reach task breakdown half-formed.
-
-## Reject codes
-
-<reject_codes>
-- `not_classified` — the request has not been through intake. Classify it first.
-- `dangling_criterion` — a drafted MILESTONE.md has an exit criterion that maps to no declared task slug. FIX the draft before proposing.
-- `no_milestone` — intake routed to `task` or `change-request`; create NO milestone.
-- `duplicate_goal` — the goal is already delivered by an existing milestone (live or in `.add/archive/`). Route as `task` or `change-request`, create nothing.
-</reject_codes>
-
-## Worked example
-
-Request: *"open the Interface & Intake milestone"* → intake classified it `sub-milestone` of v4 → scope drafting produced **`.add/milestones/v4-1/MILESTONE.md`**: goal *make ADD harness-drivable and self-scoping*; tasks (breadth-first) `machine-state-json` · `versioning-policy` · `scope-loop`; each exit criterion maps to its slug.

package/skill/add/self-improve.md

@@ -1,20 +0,0 @@
-# Self-improving ADD — the one map
-
-Every loop improves four artifacts. You emit `open`; the human confirms; the engine
-transcribes — nothing self-approves. Emission lives in observe (§7); every earlier step
-feeds it: ground surprises → §1 · the freeze's ⚠ flag → the next spec · a red-suite gap →
-a TDD lesson · build's strategy-actually-used → the ADR block · verify residue → a SPEC delta.
-
-| what improves | grammar (closes `(evidence: …)`) | consolidator |
-|---|---|---|
-| foundation — `PROJECT.md`/`CONVENTIONS.md` | `[DDD\|SDD\|UDD\|TDD\|ADD · open] lesson` | `add.py fold` → `fold.md` |
-| personas — the agents' stances | `… · persona:<slug> · critical-rule\|success-metric\|anti-pattern\|ability` | same `fold` run |
-| `SOUL.md` — your voice | a voice delta, `open` | human rewrite → `soul.md` |
-| the next scope | `[SPEC · open]` → seeded · dropped · carried | `loop.md` → `new-task` |
-
-Routing: `DDD`→§Domain · `SDD`→§Spec · `UDD`→§Users · `TDD`/`ADD`→§Method learnings
-(grammar: `deltas.md`). A HOW-an-agent-behaves lesson → a persona, not the shared pile.
-
-Convergence: `fold` prepends newest-first; the settled tail rolls via
-`compact-foundation.md`; `status` counts the debt — `carried:` · `compaction:`.
-Self-score before emitting — `confidence.md` (six dimensions; < 0.9 → refine).

package/skill/add/sensitivity.md

@@ -1,51 +0,0 @@
-# Sensitivity — the project's risk-class vocabulary
-
-A task declares its risk-CLASS with a `sensitivity:` line in the TASK header — *what
-kind* of risk it carries, distinct from `risk:` (*how much*). The engine validates +
-surfaces the human's declaration; it **never classifies**. Read live by freeze/status/check.
-
-## The base four (method-universal — always apply)
-
-- **security** — authn/authz, secrets, crypto, attack surface. A finding here is HARD-STOP;
-  the human is in the loop in EVERY tier (never advisor-gated, never auto-passed).
-- **data** — persistence, migrations, privacy of stored records, data loss.
-- **architecture** — module boundaries, contracts, cross-cutting structure.
-- **mechanical** — rote, low-impact change (rename, move, format, doc). The only class
-  a recorded advisor verdict (three §6 fields: Verdict · Residue · Binding) can gate for
-  auto-completion (`advisor-gate-relax`).
-
-These four can't be removed — a project only EXTENDS them.
-
-## Extend per project (you maintain this)
-
-Domain risk-classes live in `.add/GLOSSARY.md` under a `## Sensitivity classes` section,
-one `- <token>: <definition>` bullet per line:
-
-```markdown
-## Sensitivity classes
-Base (always apply): security · data · architecture · mechanical
-- pii: personally identifiable information; any task touching it escalates to human review
-- payments: money movement; reconciliation + an audit trail are required
-```
-
-`freeze` then accepts a header `sensitivity:` value from **base ∪ your domain classes**;
-a token in neither is refused `sensitivity_invalid`. `status` prints the active task's
-class; `check` nudges (`sensitivity_classes_unset`, never red) until you declare some.
-
-## The AI's job — keep it current
-
-- When a milestone or task reveals a **new kind of risk** this project carries (a regulated
-  data category, a payment rail, a tenancy boundary), ADD it as a class with a one-line
-  definition — propose it, the human confirms (it is foundation, like a glossary term).
-- **Re-read the section each session** (it rides `GLOSSARY.md`); pick the tightest class
-  when you declare a task's `sensitivity:` at freeze.
-- **Map domain → base behavior** in the definition so downstream gating is unambiguous —
-  e.g. "pii … escalates to human review" pins it as human-floor, not advisor-gatable.
-
-## Hold the line
-
-- **Declared, never inferred** — the engine reads your token; it does not guess a class.
-- **Base four are universal** — domain classes add to them, never replace them; security
-  stays a human floor in every tier.
-- **A comment is never a declaration** — commented-out example bullets don't count; only a
-  real `- <token>:` line under the section is a class.

package/skill/add/setup-review.md

@@ -1,48 +0,0 @@
-# Setup review — the one page the human signs
-
-Autonomous setup ends at a single human gate: the **baseline approval** (`add.py lock`). `SETUP-REVIEW.md` is that page: every decision you made while drafting the foundation, first-scope, and the first contract, **ordered lowest-confidence-first** so the riskiest guesses meet the human's eye first.
-
-The engine never reads this file — `add.py lock` is judgment-free, the signature *is* the gate. The human **reading** this page is the review.
-
-## Where it lives
-
-Write **one** artifact at `.add/SETUP-REVIEW.md`. **Never clobber a human-edited one** — if it already exists with hand edits, append/update, don't overwrite. It sits beside `PROJECT.md`, not under a task.
-
-## The template
-
-```markdown
-# SETUP REVIEW — <project>
-
-<stage> · <brownfield | greenfield> · drafted by <model> @ <date>
-
-| # | Decision | Lands in | Tag | Why / Evidence |
-|---|----------|----------|-----|----------------|
-| 1 | <the drafted decision> | PROJECT.md \| scope \| first-contract | `guessed` | <the inference + why you had to guess> |
-| 2 | <…> | <…> | `evidence-grounded` | <cite the source file/line you read it from> |
-
-Sign: confirm in chat → the agent runs `add.py lock --by "<name>"` (typing it yourself works too)
-```
-
-Rows are numbered for reference at the gate ("row 1 is where my confidence is lowest").
-
-## The two rules that make it honest
-
-<constraints>
-1. **Lowest-confidence-first.** Order rows by confidence **ascending**. A `guessed` row always floats above an `evidence-grounded` one. The top of the table is the part the human actually needs to challenge.
-
-2. **Every row is tagged — `guessed` or `evidence-grounded`.**
-   - `evidence-grounded` — you read it from the code/repo. **Cite the file** (e.g. `pyproject.toml`). Brownfield onboarding (see `adopt.md`) is mostly these.
-   - `guessed` — the repo was silent, so you inferred it. **State the inference and why.** Thin-greenfield onboarding produces these. These are what the human must check; that is why they sit on top.
-
-   The tag vocabulary is shared with `adopt.md` — brownfield map tags flow straight into this table.
-</constraints>
-
-## Where it ends
-
-`SETUP-REVIEW.md` is read-only context for the baseline approval — present it lowest-confidence-first, not field-by-field; the human confirms in conversation; you run the lock:
-
-```bash
-python3 .add/tooling/add.py lock --by "<name>"
-```
-
-`lock` records the lock layers and opens the build — it does **not** parse or validate this file. Make the top of the table the truth they most need.

package/skill/add/soul.md

@@ -1,58 +0,0 @@
-# Self-improving the voice — how SOUL.md converges to the human
-
-`SOUL.md` is the AI's voice (Tone · Communication style · Trust). It ships as a **proposed starter** and is **human-owned**; this doc is how it starts converging to *this* human. It mirrors `deltas.md` (emit) + `fold.md` (confirm → rewrite), but a confirmed voice delta consolidates into **SOUL.md**, not the foundation — voice is not one of the five competencies.
-
-You **emit** voice deltas as `open`. Only the **human** confirms one; **the human's confirm is the only writer** — you never self-approve a voice rewrite.
-
-## What a voice delta is drawn from
-
-A voice delta is grounded in how the human shows up **in session**:
-- their **wordings** — the words they reach for, and the words they correct you on;
-- their **flow** — what they skip, what they double-check, where they want summary before detail.
-
-NOT from their private **memory** files or anything outside the working session — SOUL learns only from what you observed together.
-
-## The grammar (mirrors deltas.md)
-
-```
-- [VOICE · <status>] <observation about the voice> (evidence: <in-session pointer>)
-```
-
-- `<observation>` — what the voice should become ("lead with the decision, not the preamble").
-- `<status>` — `open` | `confirmed` | `declined`. A newly emitted delta is **`open`**.
-- `(evidence: …)` — **required**, non-empty: a moment in the session (a correction, a re-ask, a visible preference). No evidence → drop it.
-
-```
-- [VOICE · open] the human strips hedging from my drafts — cut "I think / it seems" and state it plainly
-  (evidence: they rewrote two replies this session to remove the qualifier)
-```
-
-## The loop — observe → confirm → rewrite
-
-1. **Emit** (OBSERVE) — propose 0–N voice deltas as `open` from wordings + flow. Surface in the report; show-before-ask.
-2. **Confirm** — the human accepts or declines each. **No SOUL.md write happens without this.**
-3. **Rewrite** — on a confirmed delta, edit the routed SOUL.md section, record the delta line (`confirmed`) at the **top** of "Voice deltas" (**newest-first**, append-only — declined stays in place).
-
-## Routing — every voice delta has a SOUL.md home
-
-| the delta is about… | rewrite this SOUL.md section |
-|---------------------|------------------------------|
-| how I *sound* (warmth, directness, hedging) | **## Tone** |
-| how I *structure* what I say (summary-first, show-before-ask, length) | **## Communication style** |
-| what keeps the human's *trust* (gates, honesty, what I never do) | **## Trust** |
-
-The rewrite is surgical: refine or append the bullet the delta names; never silently rewrite the rest of the voice. Every confirmed delta also gets its line in **## Voice deltas** (newest-first).
-
-## Reject codes
-
-<reject_codes>
-- `unconfirmed_voice_rewrite` — a SOUL.md write was attempted without a recorded human confirm. The AI proposes; it never self-approves. Stop and get the confirm.
-- `no_open_voice_deltas` — nothing is `open`. The loop is a no-op; do not touch SOUL.md.
-- `unroutable_voice_delta` — the observation maps to no SOUL.md section (not tone/style/trust). Fix the delta or widen the routing before writing.
-</reject_codes>
-
-## Where it plugs in
-
-- **Emit**: `phases/7-observe.md` proposes voice deltas beside competency/spec deltas.
-- **Target**: `SOUL.md` — "## Voice deltas" ledger holds confirmed history.
-- **Kin**: `deltas.md` + `fold.md` (same propose→confirm→write discipline). No `add.py` command writes the voice.