@appchy/jarvis 0.1.37 → 0.1.39

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

@@ -0,0 +1,539 @@
+# Artifacts — file format specs
+
+The on-demand reference for every file this skill scaffolds, reads or
+maintains. Load this when writing or editing a `task.md`, `epic.md`,
+`handoff.md`, `plan.md`, a domain's hosted rules, `version.md`, `<feature>.md`,
+`design.md` or `architecture.md`.
+
+`SKILL.md` carries the workflow + the ownership rules; this file carries the
+contracts. Keep both in sync with the templates under `assets/`.
+
+## Conventions
+
+- Frontmatter is YAML between `---` fences.
+- File-level title is `# Title` on the first body line.
+- Names (task, epic and version) are kebab-case and globally unique across all three.
+- Dates are `YYYY-MM-DD` (today's, when the file is created or updated).
+- Files marked **scaffolded** are written by `work.py` from `assets/`
+  templates. Everything else is created by hand — only when the state needs
+  it, never pre-emptively.
+
+## `task.md` — the brief (the only file that survives archive)
+
+The single source of truth for a task's scope. **There is no length cap** (the
+old ≤30 was removed 2026-08-02): a brief is read by a session starting cold, so
+front-load the hard reasoning, the dead ends and the big-picture traps rather
+than making it re-derive them. What must NOT appear is a competing plan — the
+design is settled once, in `epic.md` §Plan, and a `plan.md` in a queue folder is
+still a lint. Length was never the failure; a second design doc is.
+
+```yaml
+---
+priority: P1            # P0 now · P1 next · P2 later
+depends_on: [other-task-name]
+tags: [engine]          # optional — area tags; the vocabulary is `tags.allowed` in config
+owner: lesson-flow          # a bare <feature> or org-domain — expected on every task (lint)
+code: [renderer, compose]     # optional, multi-valued — durable code-locality, see below
+covers: [AC-01, AC-02]        # optional, multi-valued — the feature's AC ids this task satisfies
+start: 2026-08-01       # optional — YYYY-MM-DD
+end: 2026-08-10         # optional — YYYY-MM-DD, must be >= start
+created: 2026-05-22
+updated: 2026-05-22
+sessions:               # added by work.py — never by hand
+  - 2026-05-22  <session-id>
+plans:                  # added by `work.py plan` — pointers to native-mode plans
+  - 2026-05-22  <plans.dir>/<slug>.md
+completed: 2026-05-22   # added by `work.py move … complete`, absent otherwise
+---
+```
+
+Recognised keys: `priority`, `depends_on`, `tags`, `product`, `code`,
+`covers`, `start`, `end`, `created`, `updated`, `sessions`, `plans`,
+`completed`. `sessions:`, `plans:` and `completed:` are written by `work.py`
+— leave them alone.
+
+`owner: <feature>` or `owner: <domain>` bridges an engineering task to
+the product layer — the sole owner of the task↔feature link (see the
+Ownership table in `SKILL.md`). **There is no app tier** while `product.tiers` is
+`flat`: the repo is ONE product,
+so a feature name is globally unique and `product/<feature>.md` is its
+whole address. Set it with `work.py new --owner
+<feature>|<domain>` or by hand; format-checked (kebab segments) but never
+existence-checked at write time — a stale or not-yet-scaffolded reference
+surfaces as a `work.py list` lint warning instead of a refusal. **Every task
+is expected to carry one** — a task with no `owner:` also surfaces as
+a lint warning. No reciprocal `tasks:` list on the feature side — that
+link is always a query over this field, never hand-maintained on the other
+end.
+
+**A bare `owner: <domain>`** — `operations`, `quality`, `harness`… — is how a
+task with **no user-facing feature** links: the harness itself, the docs tooling,
+CI, the deploy pipeline. It satisfies the link requirement without inventing a
+fake feature, and it **retired the old `product: infra` sentinel**, which modelled
+infrastructure as an app so the lint would pass. Infrastructure is a domain
+(`work/operations/`), not an app. Product-building tasks still take a real
+`<feature>`.
+
+`code: [<region>, …]` (optional, multi-valued) — a durable,
+cross-version code-locality tag, ORTHOGONAL to `owner` (code-locality ≠
+behaviour). The vocabulary is **derived**: a region is valid because some
+`work/architecture/<system>.md` declares it in its `code:`. There is no
+hand-curated list to keep in sync — `work.py new --code a,b` dies on a region no
+system owns. Query every task touching a region with `work.py code <region>`,
+and the rules it drags in with `work.py rules --task <name>`.
+
+`covers: [AC-nn, …]` (optional, multi-valued) — which of the linked
+feature's `AC-nn` acceptance criteria this task satisfies. Set via `work.py
+new --covers AC-01,AC-02`; format-checked at write time (`AC-\d+`), and
+existence-checked (does that AC actually exist in the linked `<feature>.md`) as
+a `work.py list` lint warning. A feature's coverage — which `AC-nn` are
+covered by a COMPLETED task's `covers:` — rolls up automatically; a `shipped`
+feature with an uncovered AC is a lint warning.
+
+`start` / `end` (optional, `YYYY-MM-DD`) — a task-level date window. Set
+via `work.py new --start/--end`; validated as dates, and `start <= end` when
+both are present.
+
+Body sections, in order:
+
+1. `# Title` — kebab-derived human title.
+2. **Problem** — what's wrong / what's needed. One or two paragraphs;
+   enough to start cold.
+3. **Context & findings** — investigation notes (root cause, `path:line`
+   refs, what was ruled out). Empty until investigated.
+4. **Approach** — fill in *only once agreed*, and **omit the heading until
+   then**. Once the goal is planned this collapses to one line —
+   `Approach → epic.md` (or `→ plan.md` in the rare task-local case) — so the
+   architecture has a single owner.
+5. **Acceptance criteria** — checkable outcomes (`- [ ] …`), one concrete
+   line each. These are the task's intent in checkable form; tests trace
+   back to them via a `covers()` call or a Playwright tag — never a comment.
+6. **Open questions** — unknowns to resolve at pick-up.
+
+There is no "Plans & analysis" section and no task-level `stories.md`: the
+design lives in `epic.md` §Plan, written once for the goal; live status is the
+task's bucket.
+
+Scaffolded by `work.py new <name>`. Template:
+[`../assets/task-template.md`](../assets/task-template.md).
+
+## `handoff.md` — the CROSS-CONVERSATION continuity file (not a per-session journal)
+
+Write/refresh this **only when you hand the task to a fresh conversation** —
+you're wrapping up, or the user asks to continue elsewhere. **You do NOT touch
+it while actively working the task in one conversation**; a task can complete
+within a single session having never had a filled handoff. `work.py move …
+in-progress` scaffolds the template so it's ready, but an empty/untouched
+scaffold mid-work is fine. When you do write it, it's the one file the next
+session reads to know *where things stand*. **Hard cap 80 lines** —
+prune-on-absorb when over (move durable facts to `plan.md` / the owning domain,
+drop the oldest log entries).
+
+```
+# handoff — <task>
+
+**Status:** <one line: where the task is right now>
+**NEXT:** <one line: the single next action to take>
+
+## Read order
+<the files a cold session reads, in order — e.g. task.md → plan.md → the governing rules>
+
+## Log
+- 2026-06-12  <what happened this session, ≤3 lines, latest first>
+- 2026-06-11  <older entry>
+
+## Decisions
+- <id>: <title>            # promoted to the owning domain — pointer only
+- <small, task-local decision that didn't earn a D-number>
+```
+
+Rules:
+
+- `**Status:**` and `**NEXT:**` capture the in-flight snapshot *for the next
+  conversation*; they're written at handoff, never duplicated into `task.md`,
+  `plan.md` or `version.md`. The always-true live status is the task's bucket.
+- `## Log` is dated and **latest-first**; the top line is always the freshest
+  truth. Pruning removes from the bottom.
+- `## Decisions` holds small task-local calls as bullets (only worth recording
+  if you're handing off). A durable one goes to the domain that owns it and is
+  reduced here to `<id>: <title>`.
+
+Scaffolded by `work.py move … in-progress` / `work.py handoff <name>`.
+Template: [`../assets/handoff-template.md`](../assets/handoff-template.md).
+
+## `plan.md` — the EXCEPTION, not the norm (task-level, in-progress only)
+
+**The design lives in `epic.md` §Plan**, written once for the whole goal. A task
+gets a `plan.md` only when pickup surfaces a call that document did not settle —
+and that is a **gap in the epic plan**, so the usual fix is to settle it *there*
+and let every sibling inherit it. `work.py list` warns when a task inside an epic
+carries one. Keep it only for a call genuinely nobody else needs.
+
+(Everything below is the format for that case, and for a task in a
+grandfathered flat version that has no epic.) One living file, written **at
+pickup, never in the queue**, and the **sole owner** of whatever design it
+does hold. Plan mode is a *drafting tool*, not a storage location: its plan lives
+in the conversation and is discarded once settled — the durable design (the
+*why-this-shape*, which has no other home) is what lands in `plan.md`. The older
+`work.py plan` → the `plans:` pointer into `plans.dir` is at most an
+**archival snapshot** of a native-mode plan (useful for the D172 web/cowork
+handoff), never a second source of truth: if `plan.md` exists, it wins.
+
+**Decision-complete before you build.** No *decision* is ever handed to a subagent —
+the brain decides, and a delegate only types out edits already settled to the exact
+string (SKILL.md §Model routing) — so the reader of this plan is the session that
+picks the task up, possibly days later with none of today's context.
+Before it is a plan:
+- **Resolve every open question** with the founder first. A plan with an
+  unresolved fork is NOT ready — settle it, don't carry it forward.
+- **Make every input explicit** so nothing has to be inferred twice: the exact
+  files / `path:line` to touch, the rule ids / `<feature>.md` requirements to honour,
+  the edge cases + failure behaviour, data shapes, and the `AC-nn` it satisfies.
+- If a reader would have to ask *"how should this work?"*, the plan is
+  incomplete — finish that thinking here.
+
+The test is the same one the founder call rests on: work that would *surface*
+decisions while being built (an unproven approach, runtime-only correctness,
+intricate logic) is not settled, however complete the plan looks.
+
+```
+# plan — <task>
+
+## As-found              (≤40 lines)
+<raw, factual account of how the in-scope code works today — no opinions.
+ This replaces the old state.md; it lives here, beside the architecture it informs.>
+
+## Architecture           (≤80 lines)
+  ┌─ diagram ─┐   …rationale…   …pseudo-code for the load-bearing pieces…
+  └───────────┘
+
+## Build
+<steps / phases / prose — whatever fits. Anchor-link what each step
+ implements ([→ Architecture §…], [wireframes/ui.md → Mixer]).>
+
+## Completion
+<acceptance criteria met · hygiene clean · tests green>
+```
+
+- **`## As-found`** — the as-found baseline (former `state.md`). Kept live
+  for the task's footprint: extend as scope grows; don't rewrite an entry as
+  the code changes.
+- **`## Architecture`** — lead with a diagram, then rationale (*why* this
+  shape, alternatives weighed), then pseudo-code for the load-bearing pieces.
+  For UI work keep this to the *technical* shape and anchor-link
+  `wireframes/ui.md` for what the user sees. Link code paths; never paste code.
+- **`## Build`** — lay it out however's clearest. The only hard rule is at
+  the task level: when it lands the repo is green and integrated;
+  intermediate states are not separately shippable.
+
+Only create `plan.md` when the task genuinely needs a design — a one-line fix
+doesn't. Refactor-natured work is its own commit, kept separate from feature/fix
+work.
+
+## Hosted rules — `architecture/<system>.md` and the org-domain READMEs
+
+A lightweight ADR ledger — **only** the business / product / high-level
+architecture decisions that set lasting direction and must not regress.
+Not a log of plan-level choices (those live in code + git history), and
+never a duplicate of current operating truth (that's the files `spine.standards`
+and `spine.conventions` name, and the code).
+
+Shape: an `## Index` of one-line titles up top (scannable without reading
+the body), then entries grouped by area (`## Direction` / `## Architecture`
+/ `## Engine model` / `## Agent & editing` / `## Product & UX` /
+`## Decided, not built`).
+
+```
+### <id> — <the rule, in one line>
+The engine core stays a vector IR; glTF-export and Three.js-preview are
+additive backends, not the render pipeline. Why: keeps assets portable and
+the core small. Supersedes: <id>.
+```
+
+Rules:
+
+- **Significance gate.** Add an entry only when a decision sets lasting
+  direction and isn't self-evident from the code. "Would a future session
+  regress this without the entry?" — if no, don't add it.
+- **Append-only, immutable.** A change of mind is a NEW entry marking the
+  old one `Superseded by <id>` — never edit history.
+- **2–6 lines per entry**: the decision + the why (+ `Supersedes:`). Keep
+  the index line in sync.
+- This is the only file others deep-link for rationale — cite the id,
+  never restate.
+
+## `version.md` — the RELEASE record
+
+One per version, scaffolded by `work.py version-new`. **A version is a release**
+and `version-new` enforces both halves of that: it **refuses without
+`--outcome`**, and it **refuses while any earlier version is still unreleased**.
+If you cannot state the outcome, the work is an epic until you can.
+
+```yaml
+---
+created: 2026-05-22
+updated: 2026-05-22
+order: 10                # roadmap sort order — optional; see derivation below
+outcome: a teacher can publish a lesson under their own name   # REQUIRED
+start: 2026-06-01        # optional — YYYY-MM-DD
+end: 2026-06-30          # optional — YYYY-MM-DD, must be >= start
+target: 2026-06-30      # optional; line absent when no target
+released: 2026-06-30    # absent until `work.py release`
+archived: 2026-07-02    # absent until `work.py archive`
+---
+```
+
+`outcome` (**required**) — ONE line, in user terms, saying what someone can newly
+**do** when this ships. Not a task summary and not a component list. It is
+printed by `list` and by `release`, rendered into the README table, and lint-
+checked on every mutation. The honest one is better than the flattering one:
+`16-mcp-package`'s reads *"nothing user-visible — a refactor released as a
+version, the exact shape the release gate now refuses"*, which is precisely why
+the gate exists.
+
+`order` (optional, int) — the roadmap's legible sort key, read at every
+site that lists versions (`list`, the README table, `code`). Set via
+`work.py version-new --order N`; derived when absent: an explicit `order:`
+frontmatter value wins, else a leading numeric prefix on the version's own
+name (`80-scene-generator` → 0, `100-poc-map` → 3), else `9999` (unordered
+versions sort last, never breaking the roadmap). A name with a numeric prefix
+and an explicit `--order` that disagree is refused at scaffold time.
+
+`start` / `end` (optional, `YYYY-MM-DD`) — a version-level date window
+for the roadmap timeline. Set via `work.py version-new --start/--end`;
+validated as dates, and `start <= end` when both are given. Distinct from
+`target` (the release-date estimate) and `released` (the actual ship date).
+
+Body: `# Title` · **Goal** (the capability in user terms — expands `outcome:`,
+never contradicts it) · **Scope** (narrative reasoning for why these epics ship
+together — the live task list is the README table, don't mirror it) · **Release
+notes** (finalised at release).
+
+Template: [`../assets/version-template.md`](../assets/version-template.md).
+
+## `epic.md` — the plan-it-together doc (TEMPORARY)
+
+One per epic, scaffolded by `work.py epic-new`. An **epic** is the tier between
+version and task: the coherent goal you plan as a whole, and the
+folder holding the tasks that deliver it.
+
+```yaml
+---
+type: epic
+created: 2026-08-01
+updated: 2026-08-01
+covers: [profiles/AC-03, sharing/AC-01]   # FEATURE-QUALIFIED
+---
+```
+
+`covers` — the feature acceptance criteria this epic moves, each **qualified by
+its feature**. That is the one format difference from a task's bare `covers:
+[AC-01]`, and it exists because an epic **spans features** by design (the org
+tier touches `profiles`, `sharing`, `content-trust` and `accounts` at
+once), so a bare id would name several criteria at the same time. An epic with
+no `covers:` is a lint: work that moves no stated criterion is work nobody can
+tell is finished.
+
+Body: `# Title` · **Goal** (what a user can newly do, one paragraph) · **Plan**
+(see below — THE design) · **Governance this implies** · **Non-goals**.
+
+**`## Plan` is the design, written ONCE for the whole goal, and it replaced the
+per-task `plan.md`.** As-found (`path:line`, confirmed by the sweep) · target
+architecture + the shared seams every task builds against · the constraining
+rules (`work.py rules --task` over the union of the tasks' `code`
+regions) · the slices in landing order · the forward-compat pass. Budgets are the
+ones `plan.md` used to carry: As-found ≤40 lines, Architecture ≤80.
+
+This is the tier's whole purpose. Before it, every small task re-ran the same
+as-found, the same blast-radius sweep and the same seam argument — expensive, and
+worse, two tasks that analysed separately reached two different answers. A task
+now **executes** this plan. It gets a `plan.md` of its own only for a call this
+document did not settle, and that is a **gap here**: settle it and write it back
+up, so the next task inherits the answer rather than re-deriving it.
+
+**`## Governance this implies` is plan-then-apply.** `work/product/**`,
+`work/architecture/**` and `work/quality/**` describe what is true NOW, never a
+proposal — so the domain-doc edits this epic will make are listed here, one
+line each naming the owner file and the change, and applied when the work lands.
+If the epic implies no governance change, say so explicitly.
+
+**Lifetime: `work.py release` DELETES this file.** How the work was planned
+stops being true the moment it ships; the folder stays as the grouping of what
+shipped, and git holds the text. So anything durable in **Plan** or
+**Governance this implies** must have landed in its owner doc *before* release.
+
+Where it lives: **in the backlog by default** (`epic-new <name>` with no
+`--version`). A version is expensive to open and its boundary is known only the
+day it opens, so an epic is planned first and promoted with `work.py pull <epic>
+--version <v>` — which moves the folder whole and gives its tasks the `queue/`
+bucket they had no need of in the backlog.
+
+Template: [`../assets/epic-template.md`](../assets/epic-template.md).
+
+## `stories.md` — RETIRED (was version-level)
+
+**Retired 2026-07-17.** Stories now live per-feature in
+`work/product/**.md` (§`<feature>.md`), the durable owner of behaviour —
+release/priority tooling *references* behaviour, it never owns it. New versions
+no longer scaffold a `stories.md`; a `version.md`'s **Scope** links the feature
+stories in the cut. Existing files carry a dated deprecation pointer and stay
+for history (git). There is no task-level stories.md either — a task's intent is
+its acceptance criteria in `task.md`, which cite the feature `AC-` ids they serve.
+
+## `design.md` — claude.ai/design UI brief ONLY (conditional, version-level)
+
+Scaffolded only with `work.py version-new --design` — UI-bearing versions
+need it; an engine-only version doesn't. **This is the claude.ai/design UI
+brief and nothing else** — the version's technical design lives in
+`architecture.md` (below). Sections: `# Title — claude.ai/design brief` ·
+**Goal** · **User stories** (lifted from `stories.md`) · **Audience** ·
+**Workflow** (the two-pass + cleanup instructions that produce
+`wireframes/project/` and `wireframes/ui.md`).
+
+The Workflow section is load-bearing — edit it only if the design workflow
+itself changes. Template:
+[`../assets/design-template.md`](../assets/design-template.md).
+
+## `architecture.md` — version-level technical brief (conditional, version-level)
+
+Scaffolded only with `work.py version-new --architecture` — a version whose
+tasks share seams/contracts a single technical brief should own; a small or
+single-task version doesn't need one. **Not** a UI brief (that's `design.md`)
+and not a duplicate of per-task design: it owns the *cross-task* technical
+design (the "plan FROM this" doc — shared architecture, phased build order,
+rules) while each task's own `plan.md` still owns that task's own
+As-found/Architecture at pickup. Sections: `# Title — technical architecture
++ phased plan` · **As-found** · **Target architecture** · **Code map** · **Phases**
+(each independently shippable) · **Risks**. The **Code map** is one block
+per `code` region the version touches — its **seam**, **known-next constraints**,
+**consumers** (features/tasks), and **foundation task** — a MAP of
+seams/decisions/links (never a code dump) where Pass-1 topology + the architect's
+foundation reasoning land (`SKILL.md` §Two-pass decomposition). Template:
+[`../assets/architecture-template.md`](../assets/architecture-template.md).
+
+## `wireframes/ui.md` — canonical per-page UI spec
+
+Produced by Claude Design from `design.md`, in `wireframes/ui.md` (sibling to
+`work/`, alongside `wireframes/project/`). Per changed page: **Layout**
+(ASCII before → after) · **Changed elements** (Does / Looks / Relates to /
+Blast radius, one per changed element) · **Backend changes deduced** (the
+bridge into each task's `plan.md`). Scope tightly — only changed elements
+appear. A task may anchor-link sections of this from its `plan.md`.
+
+## `work/product/` — the product layer (orthogonal to `versions/`)
+
+A **separate, sibling tree** to `versions/` — not nested under a version, because a
+feature is a durable product concept that can span many release cuts (idea → defined
+in one, building → shipped over several more), while a version is one time-boxed
+cut. The only bridge between the two trees is `task.md`'s `owner:` field (above) —
+one-directional, so nothing here ever lists its tasks back.
+
+```
+work/product/
+├── README.md                    — what this domain owns (the product, described)
+├── <feature>.md                 — the durable behaviour spec
+└── wireframes/<feature>/        — appears only once a wireframe exists; never scaffolded
+```
+
+**There is no app tier, and no folder tier.** The repo is ONE product, so a feature
+is a FILE directly under `product/`, its name is globally unique, and `owner:` is a
+bare feature name. `app-new` and `feature-new --app` are gone with it.
+
+**And the path is permanent.** A spec is never a folder holding one file: a folder
+that appears the day a sibling arrives is a path that changes on file count, which
+breaks every inbound citation on a day unrelated to the content. So a sibling goes
+in a KIND folder next to the spec (`product/wireframes/<feature>/`), the way a
+version's wireframes already sit beside `version.md` rather than inside it.
+
+### `<feature>.md` — the durable behaviour spec
+
+**The sole source of truth for what a feature should do**, independent of the
+code. If code and this file disagree, the code is what's wrong (see `SKILL.md`
+§The spec may say the code is wrong). Stories live HERE, next to the feature —
+not at the version level (retired).
+
+```yaml
+---
+type: feature
+state: defined          # idea | defined | building | shipped | retired — evidence-derived
+depends_on: [other-feature]   # optional, multi-valued — an enabler feature this one needs first
+log:
+  - 2026-08-01 defined (created)   # the state TIMELINE — one dated line per transition
+---
+```
+
+`depends_on` (optional) — a **bare `<feature>`**; there is no app tier to
+qualify against, and an app-qualified value is itself a lint warning.
+Existence-checked as a `work.py list` lint warning, same as `owner:` on tasks.
+
+No `# Title` heading (unlike every other spine file) — a feature's display name is
+its kebab-case folder name. Body sections, in order:
+
+1. **Problem** — what's wrong or needed, in product language.
+2. **Stories** — the value/context lens (user story *or* job story), NOT the
+   container. Each story points at the `B-`/`AC-` ids it frames. Intent, not a
+   backlog — one or a few.
+3. **Behaviour** — `B-nn` observable rules: what the app DOES, phrased
+   independent of implementation. Links the feature's own `wireframes/` folder
+   once one exists (via `artifact-design`) rather than restating it.
+4. **Acceptance criteria** — `AC-nn` checkable conditions that bound "done"
+   (observable condition → outcome, incl. failure/edge). Plain IDed bullets by
+   default; Given/When/Then only where a gnarly rule earns it. **The trace
+   unit**: a task's `owner:` cites the AC ids it implements, and a test declares
+   them with `covers("<feature>/AC-nn")` or `{ tag: ["@<feature>/AC-nn"] }` — a
+   binding the runner reads, so it cannot outlive the test that carries it.
+5. **Non-goals** — what the feature deliberately does NOT do (bounds the spec).
+
+`B-`/`AC-` ids are unique **within the feature**; never reuse an id after ship.
+
+`state` is EVIDENCE-DERIVED, not hand-mood (see `SKILL.md` §Feature state):
+`idea` (open product questions) → `defined` (all sections complete) →
+`building` (an in-progress task targets it) → `shipped` (every in-scope AC has
+passing evidence + a release ref) → `retired` (a durable rule says it's gone). It describes **what is true now**, never an
+intention — an AC that states a plan belongs in the plan until the
+evidence exists.
+`work.py list` lints the bookkeeping (id uniqueness, valid links, no `shipped`
+without evidence).
+
+Feature names are **globally unique**, like every other name in `work/` — there is
+no app tier to scope them within, which is exactly why `owner:` is a bare
+feature name and `product/<feature>.md` is a feature's whole address.
+
+Scaffolded by `work.py feature-new <feature> [--state ...]`. Template:
+[`../assets/feature-template.md`](../assets/feature-template.md).
+
+No product-decision ledger: rationale for a feature lives inline in its own
+`<feature>.md` prose, the same way a task's rationale lives in `task.md` — never a
+second ledger-shaped file.
+
+## Conditional task-level files
+
+Created only when the state needs them; never pre-emptively. **One canonical
+home each — no suffix variants** (`plan-x.md`, `state-y.md` are lint errors;
+a task that needs two plans is two tasks).
+
+- **Research** — *either* a single `research.md` (raw external findings:
+  quotes, links, data) *or*, when it's large, a `research/` subfolder with a
+  mandatory `00-report.md` (≤30 lines, decisions-relevant findings only) plus
+  the raw notes. Never both forms, never topic-suffixed siblings. The read
+  order points at the summary; drill into the rest only when a question
+  demands it.
+- **`ui.md`** — task-scoped per-page UI spec (same format as
+  `wireframes/ui.md`); folded back into the canonical spec when the task
+  settles.
+Working checklists (`hygiene.*` findings) are **not** task
+files — they live in native `TodoWrite`. Work them off the todo list, not a
+`slop.md` / `review.md` in the folder (those were retired).
+
+There is no task-level `decisions.md` and no version-level `HANDOFF.md` /
+`roadmap.md`: durable rules live in the domain that owns them (small task-local
+ones only surface in a `handoff.md` if you're handing off), and live status is
+the README table + each task's bucket.
+
+## `work/research/<dir>/` — shared research pool
+
+Cross-task research (engine audits, market analysis, prior art) lives here,
+one subfolder per topic. **Each subfolder carries a `00-*.md` summary**
+(canonically `00-report.md`; `00-synthesis.md` / `00-analysis.md` etc. also
+count), ≤30 lines, as its distilled entry point — that's what the read order
+points at; the numbered files behind it are drilled into only when needed.