@appchy/jarvis 0.1.36 → 0.1.39

package/harness/presets/appchy/PRESET.md

@@ -0,0 +1,717 @@
+---
+name: work
+description: This skill should be used when the user wants to pick up, resume, plan, organize or complete a piece of coding work in this repo — anything that names a task, references the backlog (`work/`), asks for a plan, or wraps up a change. Work lives as task folders grouped under versions in `work/`.
+---
+
+# Work
+
+**This is the method this organisation works by, and it is one document.** It ships inside
+`@appchy/jarvis` and is INJECTED at session start rather than loaded as a Claude Code skill —
+so it reaches a Codex or Cursor session on the same terms, and a repo customises it through
+`instructions.preset` / `instructions.extend` in its own `.claude/work.config.json` rather than
+by forking it. The mechanics `work.py` enforces, the method
+this organisation works by, and the things true only in a repo that serves its own board over MCP —
+all of it here, resolved, with nothing layered on top and nothing correcting it from below.
+
+It was three files until 2026-08-25: a generic engine, one organisation's preset, and a repo-local
+file that corrected the middle one. The split existed so a stranger could take the engine and decline
+the opinions, and it cost every session three reads to assemble one answer — in the one repo where
+the harness and the product are the same thing. `appchy:work` still ships that split for the repos
+that have not migrated. This one names its own tools.
+
+## What this is
+
+A **lean harness for coding sessions**. Each non-trivial piece of work is a task folder under
+`work/`. The harness delivers:
+
+- **Continuity (across conversations only)** — when you hand a task to a *fresh conversation* (you're
+  wrapping up, or the user asks to continue in a new session), a templated `handoff.md` carries
+  status + next step + a dated log so the next session is oriented in one read. **You do NOT maintain
+  it during a single working session** — write/update it only at the handoff moment. Mid-session, the
+  task's bucket + `task.md` + code are the truth.
+- **Safety** — work ships as small, reviewable, end-to-end increments.
+- **No drift** — every fact has one owner file (§Ownership); everyone else links to it, never
+  restates it.
+- **Plan ONCE, per epic — never per task.** The design, the blast-radius grind and the seam calls
+  happen **once for the whole goal**, in `epic.md`. A task then *executes* it. Re-deriving the
+  architecture for each small task is the cost this tier exists to remove — it burns tokens, and
+  worse, two tasks that re-analysed separately reach two different answers.
+
+Drive everything through **`work`** — it is on PATH and it owns status, links and the README table,
+and it lints for drift. Never edit `work/` by hand.
+
+## Plan against the graph — the loop, with the real tool names
+
+This repo is **also one queryable graph**, served over MCP by its own engine, beside the board on the
+same surface. It is the fast path for planning and it is faster and more complete than grep. Every
+repo here has ONE server named `jarvis` and it is that repo's own — a checked-in `.mcp.json` running
+`jarvis serve`.
+
+**The loop, in order:**
+
+1. **`map_brief {}`** — orient. What is in flight, the most-cited rules, health, and **whether the
+   index is fresh**.
+2. **`map_scope {task}`** — the task in words → the edit set, the governing rules, the covering tests
+   and the blast radius, in one call. This IS the planning step; asking its pieces separately is the
+   slow path. For a BUILD-NEW task the code does not exist yet — use `map_search` + `map_read`.
+3. **`map_read {id}`** — the FULL text of every rule it surfaced. **A one-line summary is not the
+   rule.** Not delegable, not skippable: this is where a plan meets the constraint that rewrites it.
+4. **Draft**, citing the ids you read so the builder cannot trip them.
+5. **`map_scope {edits}`** — before committing, ask what governance the diff touches that the plan
+   never cited. The mirror of step 2, and the one that catches a rule you never knew applied.
+
+`map_search` finds a node by concept when you do not know the path; `map_connections` says why a file
+exists or where a rule is enforced; `map_connections` and `map_graph` give neighbours, impact, paths
+and coupling hotspots. Reach for them when `map_scope` is not enough.
+
+**Two things before you trust an answer.** The map is **95% code** — ~3,600 code nodes against ~290
+knowledge artifacts — so `map_search` for a concept and `map_connections` for why a file exists both earn
+their place. And **the index goes stale, loudly and often**: `stale` means *graph.json older than
+HEAD*, and this repo commits on every board write, so a `jarvis work move` marks the code graph stale
+without changing a line of code. Read the freshness, do not read the *word* — a graph one commit
+behind a `docs(work):` commit is fine; one that predates the code you are about to edit is not.
+`jarvis build graph` rebuilds it — incrementally — and nothing does it for you.
+
+**Delegate the grind, never the reading.** A grind hands back a map of pointers; you open the files
+and the rule text it points at and reason over those primary sources. If you could plan off the
+report without opening a file, it laundered a paraphrase into your plan. The graph calls above stay
+**yours**: a cheap delegate rarely has the map's tools at all, so run them here and hand over the
+results as a seed set.
+
+The plan's *As-found* must say what the sweep confirmed — the callers, where the seam lives, what
+stays clean — not "probably".
+
+## Two doors onto the board, and they read different checkouts
+
+- **`work` on PATH reads the clone you are standing in** — this repo, this branch, whatever your
+  working tree says right now. Use it for anything beyond the five agent-facing tools: `verify`,
+  `observed`, `handoff`, `move`, `where`, `rules`, `align`, `coverage`, `sync`.
+- **`work_*` over MCP resolves to the workspace's own machine** and reads *its* clone.
+
+**A read does not pull.** `work_list` parses the tree as it stands, and that checkout may be behind or
+on another branch. A write refreshes first; a read does not. **`jarvis work sync`** forces a fresh pull and
+changes nothing — run it when you are not sure something moved under you. Branches are allowed to
+differ, and that is not a bug: a branch's board describes that branch's world and merges when the
+branch does.
+
+## How to work here
+
+<!-- applies:begin -->
+**The seven no gate can catch.** This is the index, not the argument — each one is worked out
+somewhere below, and the section that owns it is the one to read. It is deliberately terse because
+it arrives a second time, mid-run, when you are about to write a file: a rule read at the top of a
+session is a rule forgotten by the time it bites.
+
+1. **Align before you plan** — open questions and an outline, never a finished plan. (*How to work
+   here*)
+2. **Product, UX and architecture calls are the user's** — `AskUserQuestion`. Mechanics are yours.
+   (*How to work here*)
+3. **Park what you cannot answer** — `work_update {id, question}`; it never blocks. Deciding
+   because asking felt expensive is the failure. (*Running unattended*)
+4. **Cite only rules you opened** — a summary is not the rule. (*Governance cuts both ways*)
+5. **One goal per task, cut downward** — never a layer sliced across and the rest stranded.
+   (*Two-pass decomposition*)
+6. **No legacy left behind.** (*Building*)
+7. **Report what happened, not what you meant** — failures shown, skips named, and *verified* only
+   of something you watched pass. (*Output budgets*)
+<!-- applies:end -->
+
+**Read the standards before planning — hard pre-step, not a suggestion.** Before you propose *any*
+plan: the standards and conventions the `SessionStart` hook named under *read before planning* —
+it lists them from this repo's own config — plus the governing rules in
+`work/architecture/README.md` and the org-domain READMEs (`jarvis work where <id>` resolves any id to its
+home). The plan must fit the existing conventions, package layout and the dependency rule, and must
+not regress a rule.
+
+**Work back and forth with the user. Never jump to a plan.** Surface the open questions and an
+outline first, ask through `AskUserQuestion`, and route every product, UX or architecture decision
+through them. In every repo this harness runs, that is a durable RULE with an id of its own, not a
+preference — `jarvis work where` resolves it. Tiny mechanics need no sign-off.
+
+### Governance cuts both ways
+
+1. **Guardrail — protect the direction.** Before finalizing ANY plan, sweep it against the durable
+   rules and the task's `owner:` `<feature>.md`: read **in full** every rule the plan's edit set
+   touches (`jarvis work rules --task <name>` derives the ones its regions are subject to; `map_scope`
+   surfaces the cited ones; a wide sweep of the domain tree catches the uncited rest). A plan that
+   contradicts a rule has exactly two legal outcomes: **change the plan**, or **the user explicitly
+   supersedes** — route the conflict through `AskUserQuestion` (old direction vs new, with what each
+   costs), and record the call as a NEW rule marking the old one `Superseded by <new id>`. Never
+   silently violate; never quietly re-argue a decision inside a plan file. Cite the constraining ids.
+2. **Sync — plan-then-apply, never mid-build.** `work/product/**`, `work/architecture/**` and
+   `work/quality/**` describe **what is true NOW** — never a proposal, never the future tense. So a
+   governance edit is **stated in the plan first**: `plan.md` (or the epic's §Governance this
+   implies) names the owner file and the change it will make, the user approves the whole thing, and
+   it lands **with the code or not at all**. When direction changes mid-session, update the
+   governance in the SAME session, then **sweep what it invalidates**: queued briefs, `version.md`,
+   `epic.md`, in-flight `plan.md` / `handoff.md`, and every `<feature>.md` that now describes the old
+   world. A stale brief is a trap for the next session — treat "docs describe a retired design" as a
+   bug with the priority of a failing test.
+3. **Forward-compat — protect the future.** A plan correct in isolation can still be a trap. Before
+   finalizing a non-trivial one, run three explicit tests against the current + next 1–2 versions:
+   **Known-next** — can every later task sharing this task's `code` region extend the proposed seam
+   *without replacing this task's core*? **Option / LRM** — which *irreversible* choices does this
+   make now, and is this their Last Responsible Moment? Leave the reversible rest open on purpose and
+   say so. **Consumer** — a piece pitched as a *foundation* must name **≥2 near-term consumers**; one
+   or none is premature or mis-scoped. Foundation-before-feature ordering is an INFERENCE you draw
+   from `jarvis work code <region>` overlap and the feature graph, not a lint. A cheap reshape happens in
+   the plan; a real trade-off routes through `AskUserQuestion` and lands as a new rule.
+
+The completion gate enforces all three: a task that changed behaviour is not complete until every
+`AC-nn` it targeted has passing evidence, `<feature>.md` (+ its `state:`), the durable rules and any
+touched briefs match what was actually built. `map_scope {edits}` over the edit set flags governance the
+diff touches that the plan never cited.
+
+**Feature state is evidence-derived.** `idea → defined → building → shipped → retired` follows
+evidence, not mood: `defined` once Problem + Stories + Behaviour + Acceptance criteria are complete;
+`building` once an in-progress task names it in `owner:`; `shipped` once every in-scope `AC-nn` has
+passing evidence + a release reference; `retired` once a durable rule says the behaviour is gone.
+
+**The spec may say the code is wrong.** `<feature>.md` is the source of truth for what the app should
+*do*; code, tests and screenshots are evidence about what it *does*. When they conflict, the code is
+the bug — never infer intended behaviour from buggy code, and never edit `<feature>.md` to match what
+the code happens to do.
+
+### Building
+
+**Leave no legacy.** No deprecated paths, no compat shims, no dead code, no `@deprecated`
+re-exports. Boy-scout as you go.
+
+**The task is the shippable unit — nothing inside it is.** Keep going until the task lands green,
+consistent and integrated end-to-end. A task cuts *down* through every layer it needs (types → db →
+API → UI); it never cuts *across* one layer and strands the rest.
+
+**Two-pass decomposition — plan the epic DEEP, then execute.** **Pass 1 (the epic)** is where the
+thinking happens, once: the as-found, the blast radius, the shared seams, the slice order, the
+governance implied. Story-map the goal into vertical e2e slices; tag each slice's `code` region +
+`owner:` feature + the `AC-nn` it `covers`; pick a **walking-skeleton** first slice (thin end-to-end,
+not a foundation *layer* built ahead of a consumer); record each region's seam + known-next +
+consumers in `epic.md` §Plan. The sibling sweep (`jarvis work code <region>`) belongs here, done once for
+every task in the goal. **Pass 2 (pickup)** *reads* Pass 1 and builds — it does not re-derive it. If
+pickup finds the epic plan didn't settle something, that is a **gap in the epic plan**: settle it and
+write it back UP, so the next task inherits the answer.
+
+**Refactor work is its own commit.** Restructuring existing code *without changing behaviour* is its
+own phase and its own commit — never mixed with a feature or fix.
+
+**Tests trace to feature acceptance criteria — through a TAG, never a comment.**
+
+```ts
+covers("sessions/AC-01", "sessions/AC-04");                   // vitest, file- or suite-scoped
+test.describe("…", { tag: ["@sessions/AC-01"] }, () => {…})   // Playwright
+```
+
+The trace unit is the feature's `AC-nn` in the task's `owner:` `<feature>.md`, always
+**feature-qualified** — a bare `AC-01` names a different criterion in each feature file. **Never
+write the binding in a comment**: a `// Covers:` header survives the test being renamed, skipped or
+deleted, so the criterion goes on claiming evidence no run produces. A tag cannot outlive its test.
+Describe titles stay human-readable — product behaviour, not file paths, and no bare ids. Comments
+obey the comment rule in this repo's standards and carry no wiring: the non-obvious WHY, nothing
+else, and **no governance ids in code**.
+
+## Sessions — handing work on, and starting one beside you
+
+**A session that runs out of room continues on the same item.** When you wrap:
+
+1. `jarvis work handoff <task>` and fill it, bring the docs current, move what finished.
+2. **Hand back a continuation prompt for the person to paste.** `jarvis work kickoff <task>` derives it —
+   never hand-write it. It
+   also prints the **name** to pass, which is what makes a session findable: without one Claude Code
+   derives a name from the FOLDER, identical for every run in a repo.
+3. **Do NOT start it yourself.** See below — this reversed on 2026-09-03.
+
+**Starting a session is the person's call, not the wrap's** (founder, 2026-09-03). This document said
+the opposite for weeks — that starting the successor was "the default, not an option to offer" — and
+the measured result was a machine nobody could keep track of: _"i think we are kinda abusing the
+jarvis start session, it's kinda hard to keep track on it, and sometimes i get a duplicate and hard
+to keep track. it should happen only when i ask for it."_
+
+So: **`session_start` runs when the person asks for it and at no other time.** Not on a wrap, not for
+side work, not to hand something on. What a wrap owes is the prompt and a clear statement of where
+things stand; what happens to that prompt is the person's business. The old reasoning — that a
+started session "replaces the paste" and saves somebody typing — was real and was outweighed: a
+session nobody asked for is a session nobody is expecting, and several of those at once is a board
+you cannot read.
+
+The rest of what was here still holds when a person DOES ask for one: a session started against a
+stale `handoff.md` is worse off than one that was pasted a prompt, because it believes the file. And
+**never start one onto work somebody is already doing** — if the item is already in progress under
+another session, the board names its holder; hand it the handoff and say so.
+
+**Side work is written down, not started.** When the person asks for something outside what you hold,
+`work_create` it and say so. It costs this session nothing and it costs them no session to track.
+
+**It waits for the person, and that is the point.** A started session runs with this machine's
+permission settings, so it works until it reaches something that needs a person and then parks,
+holding its place. It is not stalled and it has not failed.
+
+**Opening a running session in a second local client forks it.** Measured 2026-08-22: a jarvis-started
+session opened in the VS Code panel starts a **second** `claude --resume` process on the same id, both
+alive, both appending to one transcript, both running the work. Reaching it from Remote Control — the
+phone, claude.ai — costs the session nothing. Know which door you are walking through.
+
+**What the board never works out for itself:** the link between a session and the item it worked.
+Nothing infers it. An item whose `sessions:` is empty while a run is working it is a run nobody can
+find tomorrow.
+
+## Three tiers: version, epic, task
+
+| Tier | What it is | Rule | Lifetime |
+|---|---|---|---|
+| **Version** | A **RELEASE** | states a user-visible `outcome:`; **cannot open while an earlier one is unreleased** | permanent record |
+| **Epic** | A folder inside a version holding its tasks | owns `epic.md` — *the* plan-it-together doc; **usually ≥3 tasks** | **archived at release** |
+| **Task** | **ONE goal**, end-to-end, internally phased | never shredded; never loose — it always names an epic | archived at release |
+| **Feature** | The durable spec — behaviour, `AC-nn`, `state:` | permanent, and orthogonal to all three | forever |
+
+```
+versions/01-one-board/
+  version.md                       the RELEASE — outcome: what a user can newly do
+  sessions-you-can-walk-away-from/ EPIC — plan it together
+    epic.md
+    in-progress/name-the-sessions/
+    queue/stop-and-reap/
+```
+
+> A task is **independently shippable**: when it's done the repo is green, consistent and integrated —
+> never a broken intermediate.
+
+**Feature ⟂ epic.** A **feature is permanent** (the WHAT: `AC-nn`, `state:`). An **epic is temporary**
+(the HOW-NOW: the work moving one *or more* features in one release). An epic *may span features*,
+which is why its `covers:` ids are **feature-qualified** (`sessions/AC-03`) while a task's are bare.
+
+**An epic usually holds AT LEAST THREE tasks**, and `work` warns below it. The tier exists so the
+design is done ONCE for a whole goal; at one or two tasks there is no "whole goal" to plan and
+`epic.md` degenerates into a second copy of the task brief.
+
+- **One task → it is not an epic.** Put it in an existing epic. Group by the surface and the audience,
+  not by which package the diff touches.
+- **Two tasks → the same, UNLESS more work is genuinely anticipated** — meaning the epic's §Plan can
+  *name* the slices it has not cut yet, not that more might turn up.
+- **Under the floor with real depth behind it → cut the tasks, don't merge.** An epic whose Plan lists
+  five slices and has one folder is *under-cut*. An epic with **zero** tasks is the worst case: a goal
+  nobody has cut work for has not been planned, only wished.
+- **The floor is a floor, not a target.** A long-running epic at nine tasks is fine.
+
+**Merging epics is prose work, not folder work.** Moving the folders takes one `mv`; what matters is
+that the surviving `epic.md` absorbs every settled call from the ones being dissolved *before* their
+files are deleted. **Read a dissolving `epic.md` in full first** — a thin epic is exactly where a
+fully-planned, deliberately-deferred goal hides.
+
+A version's status is derived: **planned** until tasks start, **current** while any is in-progress,
+**released** once `jarvis work release` stamps it. Release **flattens the done tier**, removes each
+`epic.md`, then `work archive` strips each task to its `task.md` and moves the version to
+`work/archive/versions/<v>/`.
+
+**Archived is off the board, not gone.** `list`, the README table and every lint see only `versions/`.
+`jarvis work path <v>` and `jarvis work where <id>` still resolve into the archive.
+
+**A finished epic goes off the board too**: an epic whose every task is complete drops into
+`<v>/complete/` and prints as one `DONE` line. It is **derived and materialized, never declared** —
+settled after every mutation, in BOTH directions, so reopening one task lifts its epic straight back.
+
+**Epics are planned in the backlog and pulled into a cut when it opens.** `jarvis work epic-new <name>` with
+no `--version` is the normal move; `jarvis work place <epic> --version <v>` promotes the whole epic.
+
+## Artifact model
+
+A task carries different files at each state. **Never create a file before its state** — a queue task
+is a brief and nothing else.
+
+| State | Files | Budget |
+|---|---|---|
+| queue / backlog | `task.md` only | no length cap — carry what a cold reader needs |
+| in-progress | `task.md` — the design is in `epic.md` §Plan and is not restated here. (`plan.md` **only** for a call the epic plan left unsettled; `handoff.md` **only** when handing to a new conversation) | handoff ≤80 |
+| complete (version unreleased) | same; if a handoff exists, stamp it DONE | — |
+| archived (version released) | `task.md` only | — |
+
+**A task is ONE goal, phased internally — never shredded.** If it spans **3+ `code` regions** the lint
+says so, and it is right: that is an epic wearing a task costume. Split it by *goal*, not by layer.
+
+`epic.md` is mandatory for an epic and owns three things nothing else does — the **Goal** in user
+terms, the **Plan** every task builds against, and **Governance this implies**. It is **removed by
+`jarvis work release`**.
+
+`handoff.md` is the **cross-conversation** artifact, not a per-task journal: **not** scaffolded on
+pickup — create it with `jarvis work handoff <name>` only when handing the task to a fresh session. A task
+can complete within one session having never had a handoff.
+
+Conditional extras: `research.md` **or** a `research/` subfolder with `00-report.md` — never both,
+never topic-suffixed siblings; `ui.md` for UI work. Working checklists live in native `TodoWrite`, not
+in the task folder.
+
+Version-level: `version.md` is mandatory; `design.md` and `architecture.md` are conditional. Version
+`stories.md` is **retired** — stories live per-feature. Full format specs:
+[`references/artifacts.md`](references/artifacts.md).
+
+Durable rules live in **the domain or system that owns them** — `work/architecture/<system>.md` for
+how something is built, or an org-domain's `README.md` for what it does, how it looks, how we know
+it's good, what keeps it safe, how we run it, how users get unblocked, how we reach users, or what
+binds us. **There is no central ledger.** `jarvis work where <id>` resolves any id to its home, and an id is
+permanent — only the home moves. Never link into a task folder for a rule.
+
+## Layout
+
+```
+work/
+├── README.md            overview + auto-generated table (work owns it)
+├── ROADMAP.md           the release sequence — order, never status
+├── versions/<v>/
+│       ├── version.md                              (mandatory; `outcome:`)
+│       ├── design.md · architecture.md             (conditional)
+│       ├── <epic>/epic.md + {queue,in-progress,complete}/<task>/
+│       └── complete/<epic>/                        every task done — off the board, still in the cut
+├── backlog/<epic>/<task>/   epics planned but not yet in a cut — NO buckets here
+├── archive/versions/<v>/    released + archived cuts
+├── research/<dir>/      shared research (each has a 00-report.md summary)
+├── product/README.md    what this domain owns + its rules; behaviour specs sit beside it
+│   ├── <feature>.md     what the app does — bridged to versions/ via task.md's `owner:`
+│   └── wireframes/<feature>/
+└── architecture/ design/ quality/ security/    the other eight org-domains, each
+    operations/ support/ commercial/ legal/     hosting the rules it owns
+```
+
+**Nine org-domains, and every one may host rules** — what it does → how it's built → how it looks →
+how we know it's good → what keeps it safe → how we run it → how users get unblocked → how we reach
+and earn → what binds us. `product/` holds `<feature>.md` behaviour specs *and* a `## Rules` section:
+a feature spec says what the app does today and can be retired; a product rule says what the product
+*is* and outlives any feature expressing it. A domain declares itself with `type: domain` frontmatter,
+never by filename, and never declares a `code:` region — regions belong to systems, one region to
+exactly one owner.
+
+A task's status is its bucket; never a frontmatter field — which is why `backlog/` has no buckets at
+either tier. Its **epic is derived from where it sits**. Names are globally unique across tasks, epics
+*and* versions, so `pull`/`rehome`/`path` dispatch on what the name IS.
+
+**There is no app tier** — this repo is ONE product, so a feature sits directly under `product/`.
+
+## Operations
+
+`work` regenerates `work/README.md` after every mutating command. Run it from anywhere.
+
+**An agent reaches the board through TOOLS; the CLI is the person's door and the harness's**
+(founder, 2026-08-28). The CLI is not a fallback — where a row below has a tool, use it, and where
+a row is marked *a person's* it is not yours to run: raise it instead. Measured over 30 days across
+four repos, sessions made 4,686 CLI calls against 851 tool calls, because until 2026-09-06 the tool
+surface could not prove an item and therefore could not finish one. It can now.
+
+### The loop, as an agent runs it
+
+| Operation | Tool |
+|---|---|
+| See what exists, and what is free | `work_list` · `{takeable: true}` for what nobody holds |
+| Pick up a task | `work_take {id, actor, sessionId}` — it never refuses because somebody else is on it; you are told who |
+| **Park a question** | `work_update {id, question: {question, options, owner}}` — parks the item until a person answers |
+| **Record an eyes-on** | `work_update {id, observed: {ac, saw}}`, or pass `observed` straight to `work_complete` |
+| **Prove it** | `work_verify {id}` — runs every configured gate. It does NOT block: ask again for progress, and again for the result |
+| Complete a task | `work_complete {id, delivered, notIncluded}` — refuses unless the gates passed at this commit |
+| Record work you found | `work_create {name, epic, …}` — for something outside what you hold, never to track your own steps |
+| How work is done here | `work_start` — once. `{method: true}` for this document |
+| Finish the session | `work_wrap` — what is uncommitted, what is in flight, what the tree disagrees about, and the next session's prompt |
+| Look up a rule | `map_read {id}` — the full text AND where it lives. This is what `where` did |
+| Plan a change | `map_scope {task}` → `map_read` each rule → draft → `map_scope {edits}` |
+
+### The CLI, which is a person's door
+
+Run these yourself only when you are the person at the keyboard. An agent that finds one of these is
+the only way forward has hit a real gap: **park a question, do not shell out.**
+
+| Operation | Command | Whose |
+|---|---|---|
+| Create a version | `jarvis work version-new <v> --outcome "…" [--title] [--order] [--design] [--architecture]` | a person's |
+| Create an epic | `jarvis work epic-new <name> [--version <v>] [--covers <feature>/AC-01,…] [--owner <feature>\|<domain>]` | a person's |
+| Create a feature | `jarvis work feature-new <feature> [--state …]` | a person's |
+| Place work in a cut | `jarvis work place <epic> --version <v>` · `jarvis work place <task> --version <v> --epic <e>` | a person's |
+| Take it back out | `jarvis work place <name> --backlog --epic <e>` | a person's |
+| Carry an epic forward | `jarvis work epic-new <name> --version <v> --continues <earlier epic>` | a person's |
+| Release / archive | `jarvis work release <v>` · `jarvis work archive <v>` | a person's |
+| Answer a parked question | `jarvis work needs` → `jarvis work answer <task> --choose "…"` | a person's |
+| Read the shift | `jarvis work status` · `jarvis work digest --since YYYY-MM-DD` | a person's |
+| Config | `jarvis work config` | a person's |
+| Create a task | `jarvis work new <name> --epic <e> [--priority] [--depends] [--owner] [--code] [--covers]` | either — `work_create` is the tool |
+| List | `jarvis work list` | either — `work_list` is the tool |
+| Pick up / complete | `jarvis work move <name> in-progress\|complete --delivered "…" --not-included "…"` | either — `work_take` / `work_complete` |
+| Prove it | `jarvis work verify --task <name>` (blocks) · `--async` (what the tool uses) | either — `work_verify` |
+| Record an approved plan | `jarvis work plan <name> [--file <path>]` | either |
+| Hand off | `jarvis work handoff <name>`, then fill it | either — **no tool yet**; the prose is judgement |
+| Open the NEXT session | `jarvis work kickoff <name>` — never hand-write the prompt | either — `work_wrap` embeds it |
+| Take work unattended | `jarvis work next [--instance <id>] [--peek]` | an automation's |
+| Get the board fresh | `jarvis work sync` | either |
+| Path / rule lookup | `jarvis work path <name>` · `jarvis work where <id>` · `jarvis work rules --task <name>` · `jarvis work code <region>` | either — `map_read` / `map_scope` |
+| Hygiene checkpoint | `/code-review` (bugs) and `/simplify` (quality) | either |
+
+Playbooks (cold-start read order, decomposition, plan-at-pickup, archive):
+[`references/operations.md`](references/operations.md).
+
+**`jarvis work list` and every mutation print the shape lints**: a task spanning **3+ `code` regions** (it is
+an epic, not a task), an epic **under 3 tasks** (fold it into one that fits), an epic with no
+`covers:`, a version with no `outcome:`, and a task left loose in a version that has adopted epics.
+The two task-count rules are one rule from both ends: **a task is one goal, an epic is several**. A
+**done** epic is exempt from the floor; it is history, not a plan.
+
+`jarvis work align` reports every misalignment class — dangling citation · orphan/uncovered AC · unenforced
+rule · retired concept still named live · complete-but-unreleased version · an `epic.md` surviving a
+release. Report-only, exit 0.
+
+## Every board write lands in git
+
+**Where `git.commit` is on — it is in jarvis, and `jarvis work config` says for any repo** — a board write
+**pulls, writes, commits and pushes**, and the
+commit is what makes the write unloseable, so it happens the moment the change does. There is no
+debounce and no window: an item created inside such a window existed in **no git history anywhere**
+and had to be recovered by hand, which is the failure this closes. Only the push may fail; when it
+does you are told plainly, the change is still committed, and `jarvis work sync` sends it later.
+
+**The commit's trailers ARE the activity record**, so there is no `work/.events.jsonl` here — that
+file records a session id rather than a machine or a branch, and it appends at the end, so two active
+branches conflict on it every time. `status`, `log` and `digest` read `git log` instead.
+
+```
+docs(work): moved name-the-sessions
+
+moved  from=queue · to=in-progress
+
+Work-Item: name-the-sessions
+Work-Event: moved
+Work-Machine: <host>
+Work-Session: <the run that made the change>
+```
+
+Four keys and no more: who, when and which branch are git's own, and a second copy of a fact is a
+second thing to drift. Two things never reach git — a **hold** (`.claim`), because coordination that
+replicates is two machines holding one item with neither knowing, and a **refused completion**,
+because nothing changed for a commit to carry.
+
+**One consequence worth holding on to**: most commits in this repo are board writes that change no
+code, and `stale` is defined as *graph older than HEAD*. See §Plan against the graph.
+
+## Somebody else is on it
+
+The harness knows who else is working — a `.claim` carries an instance id and a machine, a board
+commit carries `Work-Session` and `Work-Machine`. Where that matters it says **whether you can reach
+them**:
+
+| You see it | When |
+|---|---|
+| `next` skips a task | its `code:` regions are held by another session |
+| `move <name> in-progress` | a live claim on it belongs to somebody else — a **note**, not a refusal |
+| `status` → IN FLIGHT | a task is held by a session that is not you |
+| any write | a pull brought board changes in: *the board moved under you — <what> · from <who>* |
+
+- **`— this machine`** → that session is addressable. `ListAgents` lists it, `SendMessage` reaches it.
+  Use it when the plan has to change and waiting for a lease to expire is the wrong answer.
+- **`— another machine`** → it cannot be reached from here. The board is the only thing you share, so
+  say it on the board: `ask`, a `handoff`, or a task note.
+
+**The harness never messages anyone.** It reports who and whether they are reachable; opening the
+conversation is your call. A `move` that warns still moves — `next` is the door that declines held
+work.
+
+**Two things about holds.** A hold belongs to a **person**, not a machine — so a session you start can
+update and complete an item you are holding, and two of your own sessions never lock each other out.
+And a hold is **time-bounded and lives in the daemon's memory**: it does not survive a restart and is
+not written into the tree. Take an item when you are about to start it, not to reserve it.
+
+## Running unattended — what you decide, and what you park
+
+Everything above assumes someone is in the chair. **On a schedule, nobody is** — and *route every
+product, UX or architecture decision through the user* then has two readings, both wrong: block
+forever on a question nobody is awake to answer, or decide it yourself and leave no trace that a call
+the founder owned was made without them. The second is what actually happens, and it is invisible. So
+the boundary is a value, not a habit.
+
+**Every task carries a `tier:`** — what its blast radius IS, not its size (`code:` region count
+already measures that):
+
+| Tier | What it means |
+|---|---|
+| 0 | reversible and local — a typo, a comment, a test name |
+| 1 | an ordinary change behind existing tests |
+| 2 | new behaviour, a new seam, or a reversible migration |
+| 3 | **irreversible**, or it touches money, secrets, personal data or the law |
+
+The tier is **derived** where the tree already knows it — an `owner:` of `security` / `legal` /
+`commercial` floors a task at 3 — and may be **raised by hand, never lowered**. A run that can talk
+its own blast radius down has no ceiling at all.
+
+**At or below `autonomy.ceiling` (2 unless the repo raises or lowers it) you decide inside the plan. Above it, and for every product
+or UX call at any tier, you ASK — and move on.**
+
+```
+work_update {id: "<task>", question: {question: "…", options: ["a", "b"], owner: "founder"}}
+```
+
+Parking writes the question, puts the task in `blocked/`, and **never fails**. It does not stall the shift:
+take the next task. The founder answers the batch on their own clock (`jarvis work needs` is their one
+screen — a person's door), and a question whose answer belongs in a domain rule is one nobody
+should have to ask twice.
+**Never** substitute your own judgement for a question you were about to ask — that is the one failure
+this section exists to prevent, and nothing downstream can detect it.
+
+**The loop a scheduled instance runs:**
+
+```
+jarvis work next                      # take ONE task, claim it, print the read order
+#   … read what it printed, build, and then, through TOOLS:
+work_verify {id}                      # runs every gate; ask again until it is finished
+work_complete {id, delivered, notIncluded, observed}
+#   … or, when you hit something that is not yours to decide:
+work_update {id, question: {…}}       # park it and go back to `next`
+```
+
+`next` is the one step with no tool: claiming work unattended is a scheduler's job, not a session's.
+Everything after it is a tool call, and a session that cannot finish through them has found a gap
+worth parking a question about.
+
+`next` refuses a task whose dependencies are unmet, whose tier is above the ceiling, or whose `code:`
+regions another live instance holds — so two instances never collide, and never reach two different
+answers to the same seam.
+
+**Completion is a run, not a claim.** `work_complete` (and `move … complete`) is a gate that **refuses**: every acceptance
+criterion checked, `verify.*` actually executed and passing at the current commit, and every `covers:`
+criterion carrying either coverage a run produced or a recorded eyes-on (`jarvis work observed <task> --ac
+AC-01 --saw "…"` — what you *saw*, not a checkbox). A tier-3 task needs a human's name on it. When a
+human genuinely accepts the risk, `--accept "<reason>" --owner <name>` records it as an event; there
+is no silent override, and you must never invent an owner for one.
+
+**State `--not-included` every time.** It is what stops a shipped task reading as more than it is, and
+it is the one field nothing else can infer for you.
+
+## Model routing — the brain decides, and nothing it delegates to judges
+
+**The brain decides, and delegation is for finding and typing.** Whatever your client gives you to
+delegate with — a subagent, a cheaper model, a second session — it gets retrieval or already-decided
+edits, and never a judgement. Planning, deciding and verifying happen in the main session, in front
+of the user.
+
+This is a founder call with a history. Two goal-given agents, `worker` (implementation) and
+`architect` (design + doc alignment), both existed and both were deleted: the token saving was real
+but the output was sloppy, the work happened where the founder could not see it, and a subagent that
+makes a judgement call makes it with less context than the session that briefed it. **Do not propose
+re-adding an agent that is given a goal.** If handing down a *judgement* feels tempting, that is a
+signal the plan is not decision-complete — finish the thinking.
+
+Two named subagents, `donkey` and `grinder`, carried the two halves below until 2026-09-03, when they
+went with the Claude Code plugin this product stopped requiring. **A Claude-Code-only affordance
+cannot be part of a method meant to run anywhere**, so the names are gone and the discipline is not.
+Both halves are written below as what you do, not who does it — apply them to whatever you actually
+have.
+
+**Decided work is a pair of hands, not a junior.** Hand down only what is **already decided** — a
+diff in prose, never a goal: exact old→new strings, an exact file list that is the whole of its
+world, an exact verify command. It touches code and never governance (`work/**`, `STANDARDS.md`,
+`CLAUDE.md`, `.claude/**`), never git, no migration, no database, no dev server, and it **stops with
+a question** rather than deciding anything. Delegate when the job is fully specified, bulky or
+repetitive, and the brief costs less than the edit would. **Announce what you are handing down before
+you dispatch**, then don't block on it — and **read the diff yourself afterwards**, because the
+report claims the brief was applied, never that the change was right. The safety argument is entirely
+that there was nothing left to decide, so it is **exactly as safe as your brief**: write it as if the
+reader has no context, no taste and no authority, because that is the correct model of it.
+
+**Retrieval is an indexing job, not a summarizing one.** A grind returns a **map** — `path:line`
+pointers, the blast radius, the governing ids, and a coverage ledger that includes the queries which
+found nothing. It says *where to look and why it matched*; it must never say *what the file means*,
+because then the brain trusts a paraphrase and stops reading, and a cheap paraphrase silently drops
+the qualifier, contradiction or ordering the whole plan turns on. **Read the primary sources
+yourself.** Grind wide and surface it all: a pointer the brain discards costs nothing, a pointer the
+grind pruned is invisible.
+
+So the split is: **something cheap finds and types, the brain decides what any of it means.**
+
+**Model policy — Opus default, Fable explicit-only.** The brain runs on **Opus**. **Fable is never a
+default** — only a deliberate ask: `/model fable`, or a one-off `model: fable` override for heavy
+design.
+
+Where your client can hold a delegate open, keep it **warm**: send follow-ups to the same one rather
+than starting again, so a refined grind — or a hand stopped on a question — needs no re-brief.
+
+**Research is the one thing that leaves the session** — it goes to `codex:codex-rescue`. A same-model
+researcher is allowed and costs the independent read. The take file is named for whoever wrote it, so
+a second model can go over the same raw sources later and file its opinion beside the first
+([`references/research.md`](references/research.md)).
+
+**Plan mode is optional.** The plan→approve→implement gate is a conversation: propose a plan (in chat,
+or a task `plan.md`), the user approves, THEN build. Run normal + auto permission mode for speed;
+reach for plan mode (Shift+Tab) only when the user wants the brain hard-blocked from editing until
+they have read the whole plan.
+
+## Ownership — one writer per fact
+
+Every fact has exactly **one owner file**. Every other file links to it, never restates it. A session
+reading the spine never meets two competing versions of the same fact.
+
+| Fact | Sole owner | Everyone else |
+|---|---|---|
+| Scope + acceptance criteria | `task.md` | link it, never repeat criteria |
+| Technical design + as-found, for the whole goal | **`epic.md` §Plan** — written ONCE, before the tasks are cut | a task READS it and does not restate it |
+| A design call one task had to make that the epic plan did not settle | that task's `plan.md` — **the exception, not the norm** | if it affects a sibling it is folded UP into `epic.md` immediately |
+| The governance edits work will make | the plan (`epic.md` §Governance this implies, or `plan.md`) **until they land** | domain docs are current state and never carry a proposal |
+| What a release delivers | `version.md`'s `outcome:` + §Goal | ROADMAP.md carries the *order*, never the status |
+| Live status | the task's **bucket** | never a frontmatter copy — an epic's tier is derived FROM these |
+| Which epic a task belongs to | **where the folder sits** | never a frontmatter field |
+| Status + next step **for a new conversation** | `handoff.md` top two lines | written only at handoff |
+| Durable rule + rationale | the **domain or system that owns it** | cite the id, one line; `jarvis work where` resolves it |
+| What the app should do (behaviour, `AC-nn`) | `<feature>.md` | link it + cite `AC-nn`, never restate |
+| Feature state | `<feature>.md` frontmatter | never a task/version-side copy |
+| Task ↔ feature link | `task.md`'s `owner:` — a bare `<feature>` or org-domain | `<feature>.md` never lists tasks back |
+| Which `AC-nn` a task satisfies | `task.md`'s `covers:` | `<feature>.md` owns the text; coverage rolls up as a query |
+| Code-locality of a task | `task.md`'s `code:` — vocabulary **derived** from each `work/architecture/<system>.md` | query via `jarvis work code <region>`; never a side registry |
+| How a system is built | `work/architecture/<system>.md` — `### <id>` + `enforced_by` | cite the id |
+| The product, described | `work/product/README.md` | ROADMAP.md's framing can stay outward-facing |
+
+Four rules keep it true:
+
+1. **Approach hand-over.** `task.md`'s `## Approach` exists only until the goal is planned. Once
+   `epic.md` §Plan covers it, Approach collapses to one line: `Approach → epic.md`.
+2. **Rule promotion.** A durable rule goes straight to the domain or system that owns it, with the
+   next free number **read off the tree** (never remembered — concurrent sessions allocate too).
+   Rationale never lives in two places.
+3. **Scope change is one-directional.** Edit acceptance in `task.md` → adjust `plan.md`. Never the
+   reverse, never partial.
+4. **Contradiction = fix now.** Meet a clash between spine files? Resolve it in the owner file and
+   reduce the others to pointers *before* continuing.
+
+## Output budgets
+
+The spend is authored prose. Keep it tight:
+
+- **Link code, never restate it.** Reference `path:line`, don't paste code.
+- **Bullets over prose.** Caps: `handoff.md` ≤80 lines · `plan.md` As-found ≤40 · Design ≤80.
+  **`task.md` has NO cap** — a brief is read by a session starting cold, and the findings, dead ends
+  and warnings that make that cheap are exactly what a length rule deletes.
+- **Research is read by summary.** Every research dir carries a `00-report.md` (≤30 lines,
+  decisions-relevant only); read that, drill into the rest only when a question demands it.
+- **Prune-on-absorb.** When `handoff.md` hits its cap, move durable facts into the owning domain's
+  rules and drop the log tail.
+
+## Pitfalls
+
+- **Queue / backlog tasks are briefs only.** A `plan.md`/`handoff.md` in a queue folder is a lint.
+- **A task inside an epic should not need a `plan.md`** — the design was settled once, in `epic.md`
+  §Plan. One is a lint: fold it up, or keep it and accept that the epic plan had a gap.
+- **`handoff.md` caps at 80 lines** and must keep its `**Status:**` / `**NEXT:**` header lines.
+- **Cannot `new` without `--epic`.** Create the epic first — with no `--version` it lands in the
+  backlog, which is usually right.
+- **Don't reach for `epic-new` to house one task.** Ask which existing epic it belongs to first;
+  create a new one only when you can name the slices that follow it.
+- **Cannot `version-new` while an earlier version is unreleased**, or without `--outcome`. If the work
+  has no stateable release outcome yet, it is an epic.
+- **Cannot `move` a backlog task** — `pull` it into a version first.
+- **Cannot `move … complete` on an unproven task.** The gate refuses *before* the folder moves.
+- **Cannot `move … blocked`.** A blocked task with no recorded question is one nobody can unblock.
+  Use `ask`.
+- **Cannot lower a task's `tier:`** below the floor its `owner:` derives.
+- **A `verify.*` command containing `&&`, `;`, `|`, `>` or `$()` is refused at config load.** They run
+  without a shell, so a shell operator would be passed to the first binary as a literal argument — a
+  gate reporting PASS because its second half never ran. Put the composition in a script.
+- **Cannot `new` or `epic-new` into a released version.**
+- **Cannot `release`** a version with incomplete tasks, zero tasks, or no `outcome:`. **Cannot
+  `archive`** one that isn't released.
+- **`release` deletes every `epic.md`.** Anything durable in an epic's §Plan or §Governance must have
+  landed in its owner doc before you release — git keeps the text, but nobody will look.
+- **Names are globally unique across tasks, epics and versions.** Renaming = move the folder by hand +
+  update any `depends_on:`.
+- **`README.md` BACKLOG markers are load-bearing** — preserve them if you hand-edit around the table.
+- **A task's `covers:` is bare (`AC-01`); an epic's is feature-qualified (`sessions/AC-03`).**
+- **An epic that moves no product criterion sets `owner:` to an org-domain** instead of leaving
+  `covers:` empty. The domain IS the stated finish line, and it is checked.
+- **`owner:` is format-checked only** — a dangling reference is a lint warning, not a refusal.