@skitterbyte/skitterspec-linear 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# @skitterbyte/skitterspec-linear
+
+Spec-driven development for [Claude Code](https://claude.com/claude-code), **with
+Linear hybrid-sync**. A strict **superset** of
+[`@skitterbyte/skitterspec`](https://www.npmjs.com/package/@skitterbyte/skitterspec):
+everything in the base filesystem workflow, plus git-like sync between a spec and
+its linked Linear project.
+
+```sh
+npx @skitterbyte/skitterspec-linear init
+```
+
+Install **this OR the base**, never both — this package contains the entire base.
+
+## What the superset adds
+
+On top of the base skills (`/spec`, `/spec-go`, isolation, …):
+
+- **`/spec-status`** — read-only, per-field divergence (local-only / remote-only /
+  conflict / in-sync). Changes nothing.
+- **`/spec-pull [--force]`** — Linear → repo. Applies remote-only fields; refuses
+  to clobber a conflicting local edit unless `--force`.
+- **`/spec-push [--force]`** — repo → Linear. Ownership-respecting,
+  concurrency-checked; refuses if Linear moved since base unless `--force`.
+- **`spec-sync` CLI** (`skitterspec-linear spec-sync …`) — the deterministic
+  engine behind the skills, for CI / local runs.
+
+The shared `/spec` and `/spec-go` skills come composed with the Linear steps
+filled in: `/spec` links a new spec to a Linear Project (a Milestone per phase),
+and `/spec-go` pulls first so you build against the current shared state.
+
+## Opt-in
+
+Linear sync is inert until `specs/.core/linear.config.json` exists — copy the
+scaffolded `linear.config.json.example` and fill in your team / initiative IDs
+(every field is documented in `specs/.core/linear.config.md`). Without it, this
+behaves exactly like the base.
+
+**Mapping** (config-driven): spec folder → Linear **Project**; each phase → a
+**Milestone**; tasks → **Issues**; an optional **Initiative** groups specs.
+**Field ownership** (`both` / `pull` / `push`) collapses conflicts — only a `both`
+field that moved on both sides is a real conflict, and `--force` backs up the
+losing side before winning. **Base sidecars** (`specs/.core/linear-base/`) are
+committed; **backups** (`specs/.core/linear-backups/`) are gitignored.
+
+Branch naming that embeds the Linear id lives in the isolation config
+(`env.config.json` → `branch.pattern` with `{identifier}`, `branch.identifierField:
+"linear_identifier"`), not in `linear.config.json`.
+
+## Migrating from `@skitterbyte/skitterspec` v1
+
+If you used Linear sync on the old base, switch here and re-run `init` — see
+[MIGRATION.md](../../MIGRATION.md). Your `specs/.core/linear.config.json` path is
+unchanged.
+
+MIT © Reuben Greaves

package/assets/claude-md-section.md

@@ -0,0 +1,39 @@
+## Spec workflow
+
+Spec-driven development runs through eight skills — use them so structure and
+lifecycle stay consistent (see `.claude/rules/spec-planning.md`):
+
+| Skill | Action | Status | Folder |
+|-------|--------|--------|--------|
+| `/spec` | (Feature) Grill to a clear shared understanding, then write a concise spec | `Draft` | `specs/backlog/` |
+| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
+| `/spec-ready` | Confirm the spec is groomed (no open questions, phases + tests defined) | `Ready` | `specs/backlog/` |
+| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
+| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason on the header | `Cancelled` | `specs/cancelled/` |
+| `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
+
+Every spec has a **type** (`> **Type:** Feature\|Bug`) and a filename prefix
+(`feat-<name>` / `bug-<name>`) — never `[BUG]` brackets (glob hazard). Specs use
+markdown checkboxes (`- [ ]`) for task tracking and are the single source of
+truth for progress. Every spec is a folder: `00-overview.md` is the dashboard
+(problem, decisions, solution, **phase index**, logs) and **each phase is its own
+file** (`01-<slug>.md`, `02-…`) holding that phase's tasks — never a bare file,
+never phases lumped into the overview. **Every phase ends with creating and
+running tests**; decisions go in the spec's Changelog, state transitions in its
+State log.
+
+> Tailor the per-phase test commands and project conventions referenced by the
+> spec skills to this project's stack (see `.claude/rules/spec-planning.md`).
+
+**Per-spec isolation (adopt once, then default):** with isolation adopted
+(`skitterspec init --isolation`, or `specs/.core/env.config.json` present),
+**`/spec-go`** gives every in-progress spec its own git worktree automatically —
+parallel specs, no stashing, `main` left free. Docker is a **per-spec
+escalation**: `/spec` sets `> **Stack:** worktree` (default) or `worktree +
+docker` when the spec touches the DB / stateful services, and only the latter
+gets a namespaced stack (isolated volumes + reserved port block). **`/spec-env`**
+· **`/spec-env-down`** are the manual engine (escalate Docker later, re-attach,
+tear down — guarding dirty/unpushed work, backing up volumes first). Independent
+of lifecycle status; inactive when `env.config.json` is absent.

package/assets/core/env.config.json.example

@@ -0,0 +1,28 @@
+{
+  "worktree": {
+    "root": "../{repo}-wt",
+    "folderPattern": "{slug}"
+  },
+  "docker": {
+    "enabled": true,
+    "composeFile": "docker-compose.yml",
+    "projectNamePattern": "{repoSlug}_{slug}",
+    "portBase": 3000,
+    "portsPerSpec": 10,
+    "envFile": ".env",
+    "backupCommand": ""
+  },
+  "open": {
+    "command": ""
+  },
+  "registry": ".spec-env/registry.json",
+  "branch": {
+    "pattern": "{type}/{slug}",
+    "identifierField": ""
+  },
+  "baseBranch": "",
+  "guards": {
+    "refuseTeardownIfDirty": true,
+    "refuseTeardownIfUnpushed": true
+  }
+}

package/assets/core/env.config.md

@@ -0,0 +1,99 @@
+# `env.config.json` — per-spec isolation config
+
+Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
+stack + an optional opener per in-progress spec), driven by `/spec-go` and the
+`/spec-env` · `/spec-env-down` skills.
+
+**Once this file is present, isolation is the default policy:** `/spec-go` gives
+**every** in-progress spec its own git worktree automatically. Docker is a **per-
+spec escalation** — a spec brings up a stack only when its `> **Stack:**` header
+is `worktree + docker` (set at `/spec` when it touches the DB / stateful
+services). A `worktree`-only spec takes no registry slot, no port block, and no
+`.env`.
+
+**Adopt it** with `skitterspec init --isolation` (or copy
+`env.config.json.example` → `env.config.json` here) and edit the values. While
+`env.config.json` is absent the feature is simply unused — every skill behaves
+exactly as it does today.
+
+The loader (`src/env/config.js` → `loadEnvConfig`) merges your file over the
+frozen defaults below and returns `{ config, present }`; `present:false` means
+no live `env.config.json` was found.
+
+## Fields
+
+```jsonc
+{
+  // Where sibling worktrees are created and how their dirs are named.
+  "worktree": {
+    "root": "../{repo}-wt",   // dir that holds all spec worktrees; sibling of
+                              // the primary checkout, never nested inside it.
+    "folderPattern": "{slug}" // per-spec worktree dir name.
+  },
+
+  // Per-spec Docker stack. COMPOSE_PROJECT_NAME namespaces containers,
+  // networks, and named volumes; PORT_OFFSET shifts the spec's port block.
+  "docker": {
+    // Master switch: "is Docker escalation available on this project?" — NOT
+    // "always run Docker". true = specs MAY escalate (a spec still needs
+    // `Stack: worktree + docker` to actually get a stack); the default stack is
+    // worktree-only. false = every spec is worktree-only and the escalation is
+    // hidden. (Was "always provision Docker" in the pre-Stack engine.)
+    "enabled": true,
+    "composeFile": "docker-compose.yml",
+    "projectNamePattern": "{repoSlug}_{slug}", // → COMPOSE_PROJECT_NAME
+    "portBase": 3000,          // first port of slot 0's block
+    "portsPerSpec": 10,        // block width; slot n → portBase + n*portsPerSpec
+    "envFile": ".env",         // written into the worktree
+    "backupCommand": ""        // optional pre-teardown backup (e.g. pg_dump);
+                              // empty = no backup, volumes dropped directly.
+  },
+
+  // Optional, editor/terminal-agnostic opener run after `spec-env up`. The
+  // template is expanded with {worktreePath}, {slug}, {branch}, {projectName},
+  // {portOffset}. Empty = nothing is opened (the path is just printed).
+  // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
+  // or a "warp://..." deeplink for Warp users.
+  "open": {
+    "command": ""
+  },
+
+  // Machine-local slot registry (spec → slot index). Resolved against the
+  // primary checkout root, shared by all worktrees, gitignored.
+  "registry": ".spec-env/registry.json",
+
+  // Git branch naming, provider-neutral. `pattern` expands {type} and {slug}
+  // (e.g. "feat/add-widget"). When a ticketing provider is linked and you want
+  // tracker ids in branch names, use {identifier} in the pattern and point
+  // `identifierField` at the 00-overview.md frontmatter field the provider
+  // writes the id into — pushing that branch can then fire the tracker's
+  // automation. Empty `identifierField` (or a spec missing that field) makes a
+  // pattern with {identifier} fall back to {type}/{slug}.
+  "branch": {
+    "pattern": "{type}/{slug}",
+    "identifierField": ""
+  },
+
+  // Integration base branch — the branch specs fork from and land back onto
+  // (used by the teardown "merged?" guard and, later, the integrate step).
+  // Empty = auto-detect: origin/HEAD → main → master. Set it when your default
+  // branch isn't discoverable (e.g. no remote) or differs (trunk, develop).
+  "baseBranch": "",
+
+  // Teardown safety. --force overrides both. refuseTeardownIfUnpushed only
+  // blocks when the commits are ALSO unmerged into the base branch — a branch
+  // already landed on base tears down (and its branch is deleted) without
+  // --force, even with no remote.
+  "guards": {
+    "refuseTeardownIfDirty": true,
+    "refuseTeardownIfUnpushed": true
+  }
+}
+```
+
+## Token expansion
+
+- `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
+- `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
+  (safe for a `COMPOSE_PROJECT_NAME`).
+- `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).

package/assets/core/linear.config.json.example

@@ -0,0 +1,39 @@
+{
+  "linear": {
+    "teamKey": "",
+    "teamId": "",
+    "initiativeId": ""
+  },
+  "mapping": {
+    "specFolder": "project",
+    "phases": "milestone",
+    "tasks": "issue"
+  },
+  "states": {
+    "backlog": "Backlog",
+    "in-progress": "In Progress",
+    "complete": "Done",
+    "cancelled": "Cancelled"
+  },
+  "snapshot": {
+    "overviewFile": "00-overview.md"
+  },
+  "branch": {
+    "pattern": "{type}/{slug}"
+  },
+  "sync": {
+    "baseDir": "specs/.core/linear-base",
+    "backupDir": "specs/.core/linear-backups",
+    "fieldOwnership": {
+      "description": "both",
+      "milestones": "both",
+      "phaseBodies": "both",
+      "acceptanceCriteria": "both",
+      "taskBreakdown": "both",
+      "workflowState": "pull",
+      "priority": "pull",
+      "labels": "pull"
+    },
+    "localOnlySections": ["State log", "Changelog", "Open questions"]
+  }
+}

package/assets/core/linear.config.md

@@ -0,0 +1,121 @@
+# `linear.config.json` — Linear hybrid-sync config
+
+Opt-in config for the git-like Linear sync (`/spec-status`, `/spec-pull`,
+`/spec-push`, and the Linear-aware paths of `/spec` and `/spec-go`). Linear owns
+**status and discussion**; the repo stays the **co-authoring surface for spec
+content**. Sync is bidirectional but git-like: explicit commands, a committed
+**base sidecar** for three-way merge, and no blind overwrites.
+
+**Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
+is absent the feature is simply unused — `/spec`, `/spec-go`, and the CLI's
+`spec-sync` subcommands behave exactly as they do today (local-only). Adopt it by
+copying `linear.config.json.example` → `linear.config.json` here and filling in
+your team / initiative IDs.
+
+The loader (`src/sync/config.js` → `loadLinearConfig`) merges your file over the
+frozen defaults below and returns `{ config, present }`; `present:false` means no
+live `linear.config.json` was found (the opt-in gate — it never throws on
+absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error.
+
+## Fields
+
+```jsonc
+{
+  // Which Linear team/initiative specs sync into. IDs are read by the Phase 2
+  // MCP adapter; leave blank until you connect the `linear` MCP server.
+  "linear": {
+    "teamKey": "",        // human-facing key, e.g. "ENG" (optional)
+    "teamId": "",         // Linear team UUID (create target)
+    "initiativeId": ""    // optional Initiative that groups these specs
+  },
+
+  // How a spec's parts map onto Linear objects. Defaults mirror Decision 7:
+  // spec folder → Project, phases → Milestones, tasks → Issues. `phases` may be
+  // switched to "issue" if your workspace doesn't expose project milestones.
+  "mapping": {
+    "specFolder": "project",
+    "phases": "milestone",   // "milestone" | "issue"
+    "tasks": "issue"
+  },
+
+  // Map the spec's lifecycle bucket → the Linear workflow-state name. Used when
+  // translating workflowState across the boundary (Linear owns status → `pull`).
+  "states": {
+    "backlog": "Backlog",
+    "in-progress": "In Progress",
+    "complete": "Done",
+    "cancelled": "Cancelled"
+  },
+
+  // The spec's entry-point file the local snapshot + frontmatter live in.
+  "snapshot": {
+    "overviewFile": "00-overview.md"
+  },
+
+  // Git branch name derived for a linked spec. Tokens: {type}, {slug},
+  // {identifier} (the Linear issue/project identifier, e.g. ENG-123). Shared
+  // with the isolation engine's branch derivation (src/env/resolve.js).
+  "branch": {
+    "pattern": "{type}/{slug}"
+  },
+
+  // The three-way merge engine's on-disk state.
+  "sync": {
+    // Committed base sidecar dir: the last-synced snapshot per spec, as
+    // {baseDir}/{identifier}.base.json. Committed so each worktree carries its
+    // own base and the divergence check stays accurate.
+    "baseDir": "specs/.core/linear-base",
+
+    // Backup-before-force lands the about-to-be-clobbered side here (the
+    // reflog). --force never destroys without first writing a copy.
+    "backupDir": "specs/.core/linear-backups",
+
+    // Per-field sync direction — collapses which fields can ever conflict:
+    //   "both" — co-authored: push + pull, may conflict (both moved off base).
+    //   "pull" — Linear→local only (e.g. status/priority); a local edit never
+    //            pushes and a conflict resolves to remote-wins.
+    //   "push" — local→Linear only; a remote edit never pulls and a conflict
+    //            resolves to local-wins.
+    // Any field key you add here joins the compared field set; a value outside
+    // both|pull|push is rejected at load time.
+    "fieldOwnership": {
+      "description": "both",
+      "milestones": "both",
+      "phaseBodies": "both",
+      "acceptanceCriteria": "both",
+      "taskBreakdown": "both",
+      "workflowState": "pull",
+      "priority": "pull",
+      "labels": "pull"
+    },
+
+    // Markdown sections of 00-overview.md that are local-only scaffolding and
+    // are stripped from the pushed `description` (never sent to Linear).
+    "localOnlySections": ["State log", "Changelog", "Open questions"]
+  }
+}
+```
+
+## Field ownership & conflicts
+
+The spec is a set of structured fields, most written by only one side. Marking a
+field's owner collapses which fields can genuinely conflict:
+
+- A `pull` field (Linear owns it) never reports as **pushable** — a stray local
+  edit is informational and gets reverted on the next pull.
+- A `push` field (the repo owns it) never reports as **pullable**.
+- Only a `both` field where **both** sides moved off the committed base is a real
+  `conflict` — `/spec-push` / `/spec-pull` refuse it unless `--force` (which
+  backs up the losing side into `sync.backupDir` first).
+
+After any successful pull/push/force the engine **rewrites the base** so the next
+three-way compare starts clean.
+
+## What to commit
+
+- **`sync.baseDir`** (default `specs/.core/linear-base/`) — **commit it.** The base
+  sidecar is the last-synced snapshot the three-way merge compares against; each
+  worktree carries its own base, so it must travel with the branch.
+- **`sync.backupDir`** (default `specs/.core/linear-backups/`) — **gitignore it.**
+  These are `--force` recovery copies (a local reflog), per-machine and not shared.
+  Add `specs/.core/linear-backups/` to your `.gitignore`.

package/assets/rules/spec-planning.md

@@ -0,0 +1,152 @@
+# Spec Planning
+
+Spec-driven development is driven by eight skills — use them rather than
+hand-rolling specs so the structure and lifecycle stay consistent. Each sets a
+status on the spec header (`> **Status:** …`):
+
+| Skill | Purpose | Status | Folder |
+|-------|---------|--------|--------|
+| `/spec` | (Feature) Grill to a clear shared understanding, then write a new spec | `Draft` | `specs/backlog/` |
+| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
+| `/spec-ready` | Confirm it's groomed (no open questions, phases + tests defined) | `Ready` | `specs/backlog/` |
+| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
+| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason on the header | `Cancelled` | `specs/cancelled/` |
+| `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
+
+Status flow: `Draft → Ready → In Progress → Complete` (or `Cancelled` from any
+state). `/spec-ready` is a grooming gate only — it does not move the folder.
+`/spec-bug` is test-first and starts straight in `In Progress` (work begins
+immediately), so it skips Draft/Ready.
+
+**Per-spec isolation (opt-in to adopt, then the default policy).** When a project
+adopts isolation (`skitterspec init --isolation`, or `specs/.core/env.config.json`
+present), `/spec-go` gives **every** in-progress spec its own git worktree
+automatically — several specs run side by side without stashing or clashing, and
+`main` stays free. Docker is a **per-spec escalation**: `/spec` records
+`> **Stack:** worktree` (default) or `worktree + docker` when the spec touches the
+DB / stateful services, and `/spec-go` brings up a namespaced stack only for the
+latter. All housekeeping (the backlog→in-progress move, header edits, the code)
+happens on the spec's branch in the worktree; `main` changes only when it merges.
+`/spec-env` · `/spec-env-down` remain the manual engine (escalate Docker later,
+re-attach, tear down). Isolation is **orthogonal to lifecycle status** and
+inactive when `env.config.json` is absent — every skill then behaves as it does
+today.
+
+**Ticketing-provider sync (opt-in, a separate package).** The base is
+tracker-free: it knows nothing about any specific ticketing system. A
+ticketing provider is installed as its own distribution that plugs into two named
+**seams** in the shared skills (`/spec` Phase E, `/spec-go` step 3b) and fulfils a
+skill-name + CLI contract — it ships `/spec-status` (read-only per-field
+divergence), `/spec-pull` (tracker→repo), and `/spec-push` (repo→tracker), backed
+by a `spec-sync` CLI, three-way merged against a committed base sidecar. When a
+provider is present, `/spec` also links the spec to the tracker and `/spec-go`
+pulls first. With no provider installed the seams are empty and every skill
+behaves as a plain filesystem workflow. See the provider package's own docs for
+its config and field reference.
+
+## Project conventions (fill this in)
+
+The spec skills tell you to run "your project's typecheck and test commands" and
+to "honour project conventions". Make those concrete here so specs stay
+consistent with the codebase:
+
+- **Typecheck command:** `<e.g. npm run typecheck>`
+- **Test command:** `<e.g. npm test>` (single file/dir: `<e.g. npx vitest run path>`)
+- **Lint/format:** `<e.g. npm run lint>`
+- **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
+  (architecture, code style, testing, database, etc.) rather than restating them.
+
+## Spec types — Feature vs Bug
+
+Every spec is one of two types, recorded **both** in the header and the filename:
+
+- **Header field:** `> **Type:** Feature` or `> **Type:** Bug` (authoritative,
+  greppable: `grep -rl 'Type:.*Bug' specs/`).
+- **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs
+  (visible in listings; glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
+
+Both types share the same lifecycle folders below — type is orthogonal to status.
+
+## Header fields & State log (audit trail)
+
+Every spec header carries:
+
+- `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
+  to `git config user.name`).
+- `> **Developer:**` — who implements it (`—` until `/spec-go` starts work, then
+  set to `git config user.name`; `/spec-bug` sets it immediately).
+
+Every spec also has a **State log** table — the audit trail of folder/status
+transitions. Each lifecycle skill appends exactly one row when it changes state:
+
+```
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| 2026-01-01 | Draft | backlog | Jane Dev |
+| 2026-01-02 | In Progress | in-progress | Jane Dev |
+```
+
+Keep the **State log** (state transitions) separate from the **Changelog**
+(decisions and course-corrections) — state moves go in the table, not the
+changelog.
+
+When asked for a plan, implementation strategy, or feature breakdown:
+
+1. Create or update a spec under `specs/` — never plan only in chat.
+2. Reach a clear shared understanding of the requirement AND the proposed
+   solution before writing (the `/spec` skill grills for this).
+3. Use markdown checkboxes `- [ ]` for tasks, `- [x]` when done.
+4. Organise work into phased sections with short goal descriptions.
+5. Tasks must be granular enough to complete in one coding session.
+6. Every phase ends with creating and running tests — a phase is not done until
+   its tests are green (run the project's typecheck + test commands above).
+7. Keep specs **as concise as possible**.
+8. Record decisions and course-corrections in the spec's **Changelog** section.
+
+## Lifecycle folders
+
+```
+specs/backlog/       Draft + Ready specs (/spec, /spec-ready)
+specs/in-progress/   under active implementation (/spec-go, /spec-bug)
+specs/complete/      finished (/spec-complete)
+specs/cancelled/     abandoned, with a reason on the header (/spec-cancel)
+specs/.core/         project rules — ALWAYS APPLY, never moved
+```
+
+Every spec is a **folder** `specs/<bucket>/<name>/` — never a bare file, even for
+simple changes. Inside it:
+
+- `00-overview.md` is the entry point / dashboard: header, Problem, Decisions,
+  Solution overview, the **phase index** (a table linking to each phase file with
+  its status), Open questions, State log, Changelog. **No per-phase task lists
+  live here.**
+- **One file per phase** — `01-<phase-slug>.md`, `02-<phase-slug>.md`, … in
+  execution order. Each holds that phase's goal, its task checkboxes (tests
+  included), and any phase-specific notes. Even a single-phase spec gets `01-….md`
+  — so each phase is easy to open and work on its own.
+
+Keep the index and the phase files in sync (`⬜`/`🔄`/`✅`). Legacy specs may be a
+bare `<name>.md`, or a `00-overview.md` with inline phases — the skills read
+those, but new specs always use the folder + phase-file form.
+
+## Finding specs
+
+The **folder buckets are the source of truth** — a spec's bucket is its status.
+To see the backlog, list `specs/backlog/`; for the latest completed specs, use
+`git log`/mtime on `specs/complete/` or each spec's dated **State log**. Live
+status also lives in the tracker when a ticketing provider is linked. (There are
+no `00-index.md` summary files — the folder tree, headers, and State logs are
+queried directly.)
+
+## Rules
+
+- If a spec already exists, update it — don't rewrite from scratch.
+- Preserve completed `[x]` tasks.
+- Add new tasks to the appropriate phase.
+- Never delete historical notes.
+- The spec file is the single source of truth for implementation progress.
+- Move specs between buckets with `git mv` to preserve history.