@appchy/jarvis 0.1.36 → 0.1.39

package/harness/presets/appchy/references/graph.md

@@ -0,0 +1,154 @@
+# Planning against a graph — the worked loop
+
+How the blast-radius step in [`SKILL.md`](../PRESET.md) actually runs when
+`graph.mcp` names an engine. SKILL.md owns *what the step must achieve*, in five
+ordered outcomes; this owns what each one looks like in practice, what each is
+**not** for, and the two ways the step goes wrong silently.
+
+**No engine is named here, and none should be.** The payload resolves its repo
+from config and never writes one in — so the calls below are described by what
+they DO, and the names in the table are illustrations of a common vocabulary,
+not a contract. **Your engine's own tool descriptions are the authority**; read
+them before planning, which is step 0 and is not optional.
+
+## Why this file exists at all
+
+The harness used to name four graph queries: neighbours, impact, path, search.
+All four are real and useful — and following them literally was often the **slow
+path**, because they are the manual pieces a good engine already composes into one
+call. Meanwhile the engine's own instructions said so, and a session got two
+instructions for the same moment with no way to tell which to obey.
+
+So SKILL.md now names the OUTCOME and defers the calls. That deferral only works
+if the descriptions actually get read.
+
+## The five steps
+
+| Step | What it must achieve | A common name |
+|---|---|---|
+| 1 | orient: work in flight, most-cited rules, **index freshness** | `brief` |
+| 2 | a task in words → edit set + governing rules + covering tests + blast radius | `scope` |
+| 3 | the **full text** of every rule step 2 surfaced | `read` |
+| 4 | the plan, citing the ids you read | — |
+| 5 | the diff → governance it touches that the plan never cited | `review` |
+
+### 1. Orient
+
+One call for the top-down state of the repo. Call it first in a session, before
+searching for anything.
+
+**Not for**: finding a specific thing. If you know what you are looking for, you
+are already past this step.
+
+**The freshness read is the load-bearing half**, and it has three answers:
+
+| What you see | What it means | What to do |
+|---|---|---|
+| fresh, built from this commit | the map describes this tree | plan against it |
+| stale, or an older commit | it describes a tree that no longer exists | **rebuild**, then re-read |
+| the tools are absent entirely | `graph.mcp` names a server nothing serves | treat as `null` and **say so in the plan** |
+
+A stale index that reads as a complete map is worse than no map, because nothing
+about the answer looks wrong.
+
+### 2. Scope
+
+The task **in words** → what to edit, what governs it, what covers it, what
+breaks. This is the fast path for **modifying** existing code, and where an engine
+composes it into one call, **that call IS the step** — asking its pieces separately
+is slower and no more complete.
+
+**Not for**: building something new. Scoping needs an existing thing to scope
+against; for BUILD-NEW the entry is a concept search, then the rule text, and the
+plan says that is what it got.
+
+### 3. Read the rule text
+
+Every decision and standard step 2 surfaced, **in full**.
+
+**Not delegable and not skippable.** A one-line summary is not the rule — it is
+the rule with the qualifier, the exception and the ordering removed, which are the
+three things a plan actually trips on. It is also why a delegated grind may never
+paraphrase: a cheap summary of a rule reads exactly like the rule.
+
+**Not for**: confirming what you already believe. If you can predict what the text
+says, read it anyway — the whole cost of this step is paid on the day it surprises
+you.
+
+### 4. Draft, and cite the ids
+
+A cited id is what stops the builder tripping a rule the planner already weighed,
+and it is what makes step 5 a check rather than a re-derivation.
+
+### 5. Verify the edit set
+
+The mirror of step 2, run **before committing**: given this diff, what governance
+does it touch that the plan never cited? This catches a rule nobody knew applied —
+a different failure from breaking one you knew about, and the only one no amount of
+care at step 4 prevents.
+
+**Not for**: correctness. It reads governance, not behaviour. Tests and
+`/code-review` are the other half, and neither substitutes for the other.
+
+## The three direct questions, and when they earn their place
+
+When the scope call is not enough — usually because the change is structural
+rather than behavioural:
+
+- **neighbours** of a file — its real callers and callees. Before touching
+  anything unfamiliar.
+- **impact** — the transitive blast radius. Before a rename, a signature change or
+  a deletion.
+- **search for a helper, then neighbours on each hit** — the **DRY / single-source
+  check**: is this the only implementation? It finds the inline re-implementation
+  grep misses, because the second copy spells everything differently.
+
+Where the engine ranks coupling or clusters nodes, that surfaces god-node smells
+for free — worth one call at a version boundary.
+
+A **trace**-shaped call ("why does this file exist / where is this rule enforced")
+earns its place when the plan touches code whose reason for existing is not
+obvious from reading it, which is most code that survived a decision.
+
+## The two ways this goes wrong quietly
+
+**Laundering.** You read a scope result, a delegate's map or a tool summary, and plan
+off it without opening the primary source. Everything reads fine; the plan rests on
+a paraphrase. The tell: *if you could have written the plan without opening a file,
+you did not do step 3.*
+
+**Overstating.** The plan's As-found implies a complete map it did not get — the
+engine was absent, or stale, or answered a narrower question than the prose
+suggests. SKILL.md's rule is absolute: **never write an As-found that implies a
+complete map you did not get.** Grep-wide and honest beats graph-shaped prose with
+nothing behind it.
+
+Both are invisible downstream. Nothing in the harness can detect either, which is
+why they are stated rather than linted.
+
+## What a map does NOT know
+
+Worth holding, because a confident empty answer reads like an absence of risk:
+
+- **What is not indexed.** Shared infrastructure deliberately claimed by no region
+  answers "nothing tracked connects to me" — honest, and not the same as "safe to
+  change".
+- **Dynamic reach.** A call assembled from a string, a route resolved at runtime, a
+  hook fired by config — the extractor sees none of it.
+- **Anything uncommitted, on a machine that is not this one.** A graph built from a
+  clone carries only what was committed to it.
+- **Edge confidence.** Some engines mark circumstantial edges (a file sitting in a
+  region, a semantic match) apart from deterministic ones. Where they do, a blast
+  radius defaults to the precise half — widening it is a decision, not a default.
+
+## When your engine is missing a step
+
+The five outcomes are the contract; the calls are not. With no scoping call, step 2
+becomes search + neighbours + impact by hand, and the plan says so. With no review
+call, step 5 becomes a manual re-read of the rules the sweep found — which is
+exactly what `graph.mcp: null` already prescribes.
+
+**A repo whose `graph.mcp` names a server its MCP config does not serve is in the
+worst of the three states**: the harness tells every session it has a map, the
+tools do not exist, and nothing says why. `work.py list` warns on this. If you see
+that warning, fix the config or set `graph.mcp: null` — do not plan around it.

package/harness/presets/appchy/references/operations.md

@@ -0,0 +1,444 @@
+# Operations — detailed playbooks
+
+The on-demand reference for every harness operation. `SKILL.md` names them;
+this file walks through each. `work.py` locates `work/` automatically and
+regenerates `work/README.md` after every mutating command — there is no
+manual `readme` step.
+
+## Create a version
+
+**First check you may.** A version is a RELEASE, so `version-new`
+refuses on two counts: while **any earlier version is unreleased**, and without
+a **`--outcome`** you can state in one line. Either refusal usually means the
+work is an **epic**, not a version — go to *Create an epic* instead, and come
+back the day the earlier cuts release.
+
+1. Scaffold:
+   ```bash
+   work.py version-new <v> \
+     --outcome "what a user can newly DO when this ships" \
+     --title "Human-readable title" [--target YYYY-MM-DD] [--design] [--architecture]
+   ```
+   Creates `version.md` (+ `design.md` only with `--design`,
+   `architecture.md` only with `--architecture`). `--design` scaffolds the
+   claude.ai/design **UI** brief for a UI-bearing version; `--architecture`
+   scaffolds the version-level **technical** brief (the cross-task "plan FROM
+   this" doc) for a version whose tasks share seams a single technical brief
+   should own. Skip either for a version that doesn't need it — they're
+   independent (an engine-only version might take `--architecture` alone; a
+   thin UI version might take `--design` alone).
+2. Fill `version.md` (Goal expanding the `outcome:`, Scope naming the epics in
+   the cut) together with the user. Stories live per-feature in `<feature>.md`.
+3. **Design pass (only if `--design`).** Lift the stories into `design.md`'s
+   **User stories**, paste it into <https://claude.ai/design>, link the repo.
+   Claude Design works in two passes plus cleanup (per `design.md`'s
+   **Workflow** section): Pass 1 wireframes + per-page `wireframes/ui.md`
+   behaviour spec; Pass 2 the polished prototype; then cleanup + fresh
+   screenshots. The bundle (`project/` + `ui.md` + screenshots) drops into
+   `/wireframes/`.
+4. **Architecture pass (only if `--architecture`).** Fill `architecture.md`'s
+   As-found / Target architecture / Phases / Risks before decomposing into
+   tasks — each task's own `plan.md` then plans FROM it rather than
+   re-deriving the cross-task design.
+5. **Pull the epics that fill it** — `work.py pull <epic> --version <v>` moves a
+   backlog epic in whole, tasks and all.
+
+## Create an epic
+
+The normal way work starts. An epic is the coherent goal you plan together, and
+it lives in the **backlog** until a cut opens for it.
+
+1. Scaffold:
+   ```bash
+   work.py epic-new <name> \
+     --title "The goal, in user terms" \
+     --covers <feature>/AC-03,<feature>/AC-04     # FEATURE-QUALIFIED
+     # --version <v> only when a cut is already open and this belongs in it
+   ```
+   Name it for the **goal**, not the mechanism — and not the same as any task
+   inside it, since names are globally unique across all three tiers.
+2. **Plan the whole goal, here, once** — this is the step that pays for the
+   tier. Fill `epic.md`'s **Plan**: the as-found (send the blast-radius/search
+   grind out — ONCE for the goal, not once per task), the target
+   architecture and shared seams, the constraining rules
+   (`work.py rules --task` over the union of the regions), the slices in
+   landing order, and the forward-compat pass. Then **Goal**, **Governance this
+   implies** and **Non-goals**.
+3. **Decompose into tasks** (next section) — the tasks fall out of the slices you
+   just settled; they do not re-open them.
+
+## Decompose an epic into tasks
+
+Slice the epic into **vertical e2e tasks** — one goal per task,
+shippable on its own. Source is `epic.md`'s Goal + Plan, plus
+`wireframes/ui.md` for UI work.
+
+1. Read the source together with the `<feature>.md` of every feature the epic
+   `covers:`.
+2. **Propose candidate slices.** Each cuts *down* through every layer it
+   needs (types → db → workflow/agent → API → UI), never one layer across
+   with the rest stranded. Shared infrastructure folds into the task that
+   first consumes it, not its own task.
+3. **Test each against the shippability rule** — *if this ships and nothing
+   after it does, is the repo green, consistent and integrated?* If not,
+   merge with a sibling. Order the survivors, note dependencies.
+4. **Align with the user** via `AskUserQuestion`, each candidate with its
+   one-line shippability rationale.
+5. **Scaffold each agreed task** — a brief only, no plan yet, tagged into the
+   graph (see *Two-pass decomposition* below). `--epic` is **required**; the
+   version is derived from where that epic lives:
+   ```bash
+   work.py new <task> --epic <e> \
+     [--priority P1] [--depends a,b] \
+     [--owner <feature>|<domain>] [--code region-a,region-b] [--covers AC-01,AC-02]
+   ```
+   **If a slice needs 3+ `code` regions it is not a task** — the lint says so,
+   and it is right. Split the goal again, by goal rather than by layer.
+6. **Count the slices.** Fewer than three and the epic is the wrong unit
+   (`SKILL.md` §Three tiers) — either the goal is smaller than it looked, in
+   which case its tasks belong in an existing epic, or it was sliced too coarsely.
+   Say which, in the epic's §Plan, before scaffolding anything.
+
+## Merge thin epics back together
+
+The inverse operation, and it comes up whenever the backlog has been fed
+one-task-at-a-time. `work.py` has no `merge` — the mechanics are folder moves —
+so the discipline is entirely in what happens to the prose.
+
+1. **Read every dissolving `epic.md` IN FULL first**, not just its Goal. A thin
+   epic is exactly where a fully-planned, deliberately-deferred goal hides —
+   banked founder calls, verified as-found, an architecture already settled — and
+   its own text usually says *do not re-derive this*. Deleting one silently costs
+   the next session everything the file was written to save.
+2. **Group by surface and audience, not by package.** The learner's runtime, the
+   teacher's desk, the agent-facing surfaces, the content itself, the harness.
+   Two tasks touching `packages/blocks` are not thereby one goal.
+3. **Move the task folders** (`mv`; the epic is derived from where a folder
+   sits), then **write the surviving `epic.md`**: a Goal that covers what was
+   merged in, a §Plan holding every settled call from the dissolved files, and
+   their Governance-implied and Non-goals folded in. A non-goal often survives as
+   a *sequencing rule* rather than an exclusion — "Hebrew waits for good English"
+   becomes "slice 3 runs last".
+4. **Only then delete the empty epic folders**, and check `covers:` on the
+   survivor: a criterion inherited from a dissolved epic may already be met by
+   other work, in which case the honest move is to drop it and record the new
+   `AC-nn` the work actually owes.
+5. Re-run `work.py list` — the floor lint should be silent, and the README table
+   regenerates itself.
+
+## Two-pass decomposition
+
+Decomposing a version and planning a task are **two passes over the same
+connected graph** — cut shallow up front, plan deep at pickup, so no task
+is ever designed blind to its siblings. `SKILL.md` carries the rule; this is the
+playbook.
+
+**Pass 1 — the epic (shallow).** Runs during *Decompose an epic into tasks*
+(above); the graph-connecting steps on top of the base slicing:
+
+1. **Story-map the goal** — lay its topology out as the vertical e2e
+   slices (base mechanics above), a release story-map, not a layer stack.
+2. **Tag each slice** into the graph — its `code` region(s) (`--code`), its
+   `owner:` feature (`--owner`), and the `AC-nn` it satisfies (`--covers`).
+   The tags are what wire the slice to the rest of the graph.
+3. **Cluster change-affine slices** — group the slices that share a `code`
+   region or a feature; a shared region is where a seam will be set and reused,
+   so those slices must agree on it.
+4. **Pick a walking-skeleton first slice** — thin, end-to-end, exercising the
+   real seams; NOT a foundation *layer* built ahead of any consumer.
+5. **Record the seams** — for each `code` region the cut touches, write its
+   seam + known-next constraints + consumers + foundation task into
+   `architecture.md`'s **Code map**. Shallow: a map of seams/decisions/links,
+   never a design or a code dump.
+
+**Pass 2 — pickup (execute).** Deliberately CHEAP. The thinking was done in
+Pass 1; pickup reads it and builds.
+
+1. **Read `epic.md` §Plan** — the as-found, the seams, the rules, this
+   task's slice and what it depends on. Plus the `<feature>.md` it serves.
+2. **Build.** No fresh blast-radius sweep, no re-derived architecture, no second
+   design document. If you are re-running the blast-radius grind for a task, the epic
+   plan was incomplete — fix that, don't absorb the cost silently.
+3. **When pickup DOES surface something unsettled** — an unknown the plan missed,
+   a seam that turns out too narrow — settle it and **write it back UP into
+   `epic.md`**, immediately, so every sibling inherits the answer. A task-local
+   `plan.md` is for a call genuinely nobody else needs; `work.py list` warns when
+   a task inside an epic carries one, because that is usually a gap upstairs.
+
+## Rescope a version or an epic
+
+1. Edit `version.md` (`outcome:` + Scope) or `epic.md` (Goal + Plan +
+   Governance this implies).
+2. If it's a UI version, update `design.md` and re-run Claude Design;
+   `wireframes/` rewrites. If it has an `architecture.md`, update its Target
+   architecture / Phases to match.
+3. Sync tasks: add new ones with `work.py new --epic <e>`; defer obsolete ones
+   into a backlog epic (plain `mv`). Update affected `task.md` briefs. A whole
+   epic moves between cuts with `work.py rehome <epic> --version <v>`.
+4. A rescope IS a direction change — run the governance sweep (SKILL.md
+   "Governance cuts both ways"): record the new direction (a durable rule /
+   `<feature>.md`), then update or re-scope-stamp everything the change
+   invalidates — other epics' `epic.md`, in-flight `plan.md`/`handoff.md`,
+   product docs. Conflicts with a standing rule go to the user as an
+   explicit supersede fork.
+
+## Create a task (one-off)
+
+1. Derive a kebab-case `<name>` and one-line title.
+2. Settle priority (P0/P1/P2) and its **epic** — every task has one. If no
+   existing epic owns the goal, create one first (*Create an epic*); a backlog
+   epic is cheap, a version is not.
+3. **Offer to investigate** for a bug or unknown-scope task — launch an
+   `Explore`/`general-purpose` agent; findings populate **Context &
+   findings**.
+4. Scaffold:
+   ```bash
+   work.py new <name> --epic <e> \
+     --priority P1 --title "Human-readable title" \
+     [--depends other-task]
+   ```
+5. Edit `task.md` (Problem, Context & findings, Acceptance criteria, Open
+   questions; delete the **Approach** heading unless already agreed). No length
+   cap — write what a cold reader needs. What is banned is a competing PLAN, not
+   detail: the design is settled once in `epic.md` §Plan, at pickup.
+
+## Pull from backlog
+
+```bash
+work.py pull <epic> --version <v>
+work.py pull <task> --version <v> --epic <e>
+```
+
+The **name decides the tier**. An epic moves whole — the normal promotion, since
+an epic is the unit a cut is filled with — and its tasks gain the `queue/`
+bucket they had no need of in the backlog (a backlog task has no status). A
+single task needs `--epic` to say which epic in that version it lands in.
+
+## List
+
+```bash
+work.py list
+```
+
+Prints the backlog grouped by version, plus any **lint warnings** (queue
+task carrying more than `task.md`, suffix-variant files, research dir without
+`00-report.md`, oversized/headerless handoff). Fix what it flags.
+
+## Run a shift unattended
+
+The loop a schedule drives. Everything in it already exists as an operation below;
+what `next` adds is *choosing*, and what `ask` adds is somewhere to put a question
+so the run never stalls and never quietly decides for the founder.
+
+```bash
+work.py next                      # ONE task, claimed, with its read order printed
+#   … build it, then EITHER prove it:
+work.py verify --task <name>
+work.py observed <name> --ac AC-01 --saw "what you actually saw"
+work.py move <name> complete --delivered "…" --not-included "…"
+#   … OR park what is not yours to decide, and go back to `next`:
+work.py ask <name> --question "…" --options "a | b" --owner founder
+```
+
+1. **`next` chooses; you do not.** It takes the highest-priority queued task whose
+   dependencies are complete, whose `tier:` is at or below `autonomy.ceiling`, and
+   whose `code:` regions no other live instance holds — then claims it with a lease.
+   Nothing eligible prints **why**, per task, so a cron log is diagnostic rather
+   than silent.
+2. **One instance, one task.** A second `next` from the same instance resumes what
+   it holds rather than taking more; three half-finished tasks is what juggling
+   costs, and unattended nobody notices until morning.
+3. **Read what it printed**, in that order — it is the cold-start spine below,
+   computed for this task.
+4. **The moment you reach a product, UX or scope call — `ask`.** Not a guess with a
+   note attached. The question is the deliverable at that point.
+5. **`verify` before you claim anything.** The gate refuses without a passing run
+   at the current commit, and it refuses *before* the folder moves.
+6. **A crashed shift frees its own work** — leases expire and are reaped on read,
+   so nobody is paged at 3am.
+
+`work.py status` is the founder's morning read; `work.py digest --since <date>`
+is what happened while they were away.
+
+## Pick up a task
+
+```bash
+work.py move <name> in-progress
+```
+
+Moves the folder, records the session, and scaffolds a `handoff.md` *template*
+(you only fill it when handing off to a new conversation — see below). If the
+task is already in-progress (fresh session, same task):
+
+```bash
+work.py session <name>
+```
+
+### Read in this order
+
+A cold session reads the spine, top to bottom:
+
+1. **`task.md`** — the brief: problem + acceptance criteria. The spec.
+2. **`handoff.md`** — *where things stand*, IF a prior conversation left one
+   (it exists only when the task was handed off across sessions; an untouched
+   scaffold means the last session didn't hand off — lean on `task.md` + code).
+3. **`plan.md`** — design + as-found + build (exists only if the task has
+   one).
+4. **The rules that constrain it** — `work.py rules --task <name>`
+   derives them from `task.code ∩ system.code`; read each in full where it
+   lives (`work.py where <id>`). A one-line summary is not the rule.
+5. **Parent `epic.md`** — the Plan every sibling task builds against, and the
+   governance the epic has promised to land. Then `version.md` for release
+   context.
+6. **`wireframes/ui.md`** — the UI sections this task touches (UI work only).
+7. **`research/00-report.md`** — the summary, if the task has research; drill
+   deeper only when a question demands it.
+
+Files absent for this task (`plan.md`, `research/`, `ui.md`) simply don't
+exist — skip them.
+
+### Check dependencies
+
+Read `task.md` frontmatter `depends_on:` and surface any incomplete
+dependency before starting — running ahead of one is the fastest way to
+write code that gets thrown away.
+
+## Plan at pickup (analyse → align → plan)
+
+Planning happens **now, with the code in front of you** — never pre-written
+in the queue, where it rots.
+
+1. **`plan.md` `## As-found`** — write the current-state analysis: a raw,
+   factual account of how the in-scope code works today. No opinions. Kept
+   live for the task's footprint (≤40 lines).
+2. **Research (only when needed)** — a single `research.md`, or a `research/`
+   subfolder with a `00-report.md` summary. Raw external findings.
+3. **Align with the user — before writing the architecture.** Surface open
+   questions + a short outline first, work back and forth:
+   - Every question goes through `AskUserQuestion`.
+   - Every product / UX / architecture decision is the user's — present
+     alternatives, recommend one, let them choose. Tiny mechanics don't need
+     sign-off.
+   - Promote durable resolved rules to the domain or system that owns them (the
+     next free number, read off the tree) and cite them by id.
+   - **Governance conflict sweep** (SKILL.md "Governance cuts both ways"):
+     read in full every rule and `<feature>.md` requirement the plan touches;
+     a contradiction either changes the plan or goes to the user as an
+     explicit supersede fork — never both left standing. Cite the
+     constraining ids in `plan.md` so the build can't trip them; if the
+     plan changes direction, sweep + update the briefs/docs it invalidates
+     before building.
+4. **Write the architecture.** `plan.md` `## Architecture` then `## Build` —
+   per [artifacts.md → plan.md](artifacts.md). The moment `plan.md` exists,
+   collapse `task.md`'s `## Approach` to `Approach → plan.md` so the
+   architecture has one owner.
+
+As you go, keep the ownership rules true: live status is the bucket, the
+architecture only in `plan.md`, durable rationale only in the owning domain. If you hit a
+contradiction between files, fix it in the owner and reduce the rest to
+pointers before continuing.
+
+**Native plan mode (cowork / cross-device).** When a plan is authored in
+native plan mode rather than the in-folder `plan.md` — e.g. a desktop or cloud
+session that produces a committed plan file — record the pointer with
+`work.py plan <name> --file <path>` (with `plans.dir` configured, `--file`
+defaults to `<plans.dir>/<name>.md`; with it null, `--file` is required). It appends a dated, deduped entry to the task's
+`plans:` frontmatter; the plan body is **not** copied into the task folder. A
+fresh session reads `task.md`, walks `plans:` newest-first, and re-enters plan
+mode from the first ref that still exists — so plan continuity survives
+desktop↔cloud↔mobile hops.
+
+## Hygiene checkpoint
+
+The "Leave no legacy" rule (in the files `spine.conventions` names) is enforced
+*continuously*. Run this repo's `hygiene.review` (bug pass) and `hygiene.simplify`
+(quality pass) — the `SessionStart` block names them where they are configured, and
+where they are not there is no pass to run and none is invented. Capture their
+findings in native `TodoWrite` and
+work them like a checklist: fix in-scope findings, re-run, iterate. The todo
+list is the working surface — nothing is written into the task folder.
+
+## Complete a task
+
+**`move … complete` is a gate, not a checklist you tick.** It refuses, before the
+folder moves, unless: every acceptance criterion is checked · `verify.*` ran and
+passed at the current commit (`work.py verify --task <name>`) · every `covers:`
+criterion has coverage a run produced *or* a recorded eyes-on (`work.py observed
+<name> --ac AC-01 --saw "…"`) · a tier-3 task carries a human's sign-off. It names
+every gate that held, all at once. `--accept "<reason>" --owner <name>` overrides,
+as a recorded event — never invent an owner for one.
+
+1. Confirm `task.md`'s Acceptance criteria are met (all `- [ ]` checked). (If
+   a `handoff.md` was ever filled for a cross-conversation handoff, stamp its
+   `**Status:**` done — but a task completed within one session needn't have
+   one.)
+2. **Final hygiene gate** — a last run of whatever `hygiene.*` names; clear
+   every in-scope finding. Nothing configured, nothing to run.
+3. **Governance sync gate** (SKILL.md "Governance cuts both ways") — if the
+   task changed behaviour or direction: update the `owner:` `<feature>.md`
+   (description/requirements + `state:` frontmatter) to describe what was
+   BUILT, promote any durable calls made mid-task to the domain that owns them
+   (supersede, never edit, an old entry), and re-check the edit set against the
+   rules the blast-radius sweep surfaced — where `graph.mcp` is set the graph can
+   do this from the diff; where it is null it is a manual re-read.
+   Flag governance the diff touches that the plan never cited. Fix or
+   escalate every flag; a doc describing the retired design blocks
+   completion like a failing test.
+4. **Offer a code review** via `AskUserQuestion`, where `hygiene.review` names
+   one. If yes, run it over the working diff, capture findings in `TodoWrite`,
+   work them. Deeper multi-agent review is user-invoked, never yours to launch.
+5. Move it (warns on leftover unchecked criteria):
+   ```bash
+   work.py move <name> complete
+   ```
+
+## Release a version
+
+When every task is complete:
+
+```bash
+work.py release <v>
+```
+
+It refuses unless every task is complete **and** `version.md` states an
+`outcome:`. It stamps `released: <today>`, prints the outcome, and **deletes
+every `epic.md` in the version** — an epic is temporary by definition,
+and how the work was planned stops being true the moment it ships. The epic
+folders stay as the grouping of what shipped; git holds the plans.
+
+**So distill BEFORE you release, not after** — once `release` runs, the plan
+docs are gone from the working tree:
+
+1. **Land the governance** each `epic.md` promised in **Governance this
+   implies** — it belongs in `product/**` · `architecture/**` ·
+   `quality/**` now, because it is true now.
+2. **Promote durables** — any decision still load-bearing that lives only in an
+   `epic.md`, `handoff.md` or `plan.md` moves to the domain that owns it or its
+   owning `<system>.md`.
+3. **Repoint inbound links** — anything (backlog epics especially) that
+   deep-links into this version's folders repoints to the id.
+4. **Archive** (next section).
+
+Finalise the **Release notes** in `version.md` first.
+
+## Archive a version
+
+After release, strip the bulk — git keeps the full history:
+
+```bash
+work.py archive <v>
+```
+
+For every task in the version it deletes all files except `task.md`, stamps
+`archived: <today>` (with the pre-archive commit sha) in `version.md`, and
+**moves the whole version to `work/archive/versions/<v>/`**. It refuses unless
+the version is released.
+
+**Off the board, not gone.** `list`, the README table and every lint read
+`versions/` only, so the board shows work that is *moving* — the reason this
+move exists is that three live tasks were being read past sixty completed ones.
+`work.py path <v>` and `work.py where <id>` still resolve into the archive.
+
+Run the release distill checklist *first* — once archived, the
+`plan.md`/`handoff.md`/research are gone from the working tree (recoverable
+only via git).