tiny-spec 1.0.1__tar.gz → 1.2.0__tar.gz

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiny-spec
-Version: 1.0.1
+Version: 1.2.0
 Summary: A tiny, opinionated take on spec-driven development.
 Project-URL: Homepage, https://github.com/GrayMa77er/tiny-spec
 Project-URL: Source, https://github.com/GrayMa77er/tiny-spec
@@ -449,10 +449,19 @@ unnoticed.
 1. Plan the task against the constitution (inline, brief).
 2. Implement it with a fresh `tiny-spec-build-executor` agent.
 3. Review it with an independent `tiny-spec-build-reviewer` agent that runs the gate
-   end to end and grades against the constitution and the task's acceptance.
+   and grades against the constitution and the task's acceptance.
 4. On pass, commit the code plus a checklist tick. On fail, loop back to the
    executor with the findings. After two failed attempts the run halts `exhausted`.
 
+Every task's acceptance is exercised end to end, black-box, by the reviewer — that part
+never varies. What does vary is how much of the toolchain gets re-proven around it: a
+clean `install → build` runs on the first task, the last one, anything touching
+dependency or build config, and anything carrying `design:`; in between the reviewer runs
+lint and tests against the existing build. It escalates back to the full gate whenever the
+narrower one can't carry the verdict, and the authoritative clean run happens once more
+over the whole project as the final smoke. Re-installing from scratch on every task
+proved the same thing repeatedly and was the slowest part of the loop.
+
 ```mermaid
 flowchart TB
     SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[tasks.md<br/>checklist]
@@ -460,7 +469,7 @@ flowchart TB
     TASKS -->|pause: set| H[Halt — paused<br/>task stays unchecked]
     TASKS --> P[Plan task]
     P --> I[Implement<br/>executor]
-    I --> R[Review + run gate<br/>reviewer]
+    I --> R[Review + run gate<br/>full or scoped<br/>reviewer]
     I -->|blocker| B
     R -->|pass| C[Commit + tick]
     C --> TASKS
@@ -489,15 +498,38 @@ resumes from the checklist state.
 ### Working a whole list
 
 Ask `/tiny-spec-run` to build — "build the backlog", "work through the breakdown",
-"spec it out and build it" — and it takes a list of stories and works them one after
-another. Per story it does the same four moves:
+"spec it out and build it" — and it takes a list of stories and works them in batches.
+Per story it does the same four moves:
 
 ```
 cut a branch from main  →  walk the chain  →  tiny-spec-build  →  merge back to main
 ```
 
-Then the next story. Each branch is cut **fresh from main**, so story 3 sees stories 1
-and 2 already merged — which is what makes an ordered list build correctly.
+Each branch is cut **fresh from main**, so a later story sees the earlier ones already
+merged — which is what makes an ordered list build correctly.
+
+**Independent stories build at the same time.** A story can declare what it must follow
+with a `needs:` line in `BREAKDOWN.md`; everything with no unmet `needs:` forms a batch
+and builds **concurrently, one git worktree per story**, three at a time by default.
+The batch merges, then the next one starts.
+
+```
+## Feature: interface
+
+- Story: expose both helpers on a CLI     slug: cli
+  - AC: `textkit slugify "Hi There"` prints "hi-there"
+  - needs: slugify, wordwrap
+```
+
+Omit `needs:` when a story stands alone — that's the common case, and the field is meant
+to be rare. A `needs:` you didn't need costs you parallelism forever; one you missed
+costs a single merge conflict, which the run already catches and halts on. You can also
+just name the set yourself at invocation ("build these three at once"), which overrides
+the graph. A cycle, or a `needs:` naming a story that isn't there, stops the run rather
+than being guessed past.
+
+**Tasks *inside* a story never run in parallel.** They share files and each one assumes
+the last landed, so they stay strictly sequential. Parallelism is across stories only.
 
 **The list is `BREAKDOWN.md` by default** — its `- Story:` entries, in file order,
 each already carrying a `slug:` (the branch and directory name) and `AC:` lines. Paste
@@ -520,9 +552,13 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 Stopping at story 2 of 7 and reporting "done" is what autonomous loops get wrong most
 often, so the state is always named alongside what merged and what's still untouched.
 
-**A halt stops the whole run, not just that story.** Later stories in a list you wrote
-top to bottom usually assume the earlier ones landed, so skipping ahead past a failure
-just produces a second, more confusing failure downstream.
+**A halt stops the lane it happened in, and ends the run after that batch.** Its siblings
+were declared independent, so they finish and merge — killing working lanes because one
+failed throws away good work. But the run does not start the next batch: later stories
+usually assume the earlier ones landed, so skipping ahead past a failure just produces a
+second, more confusing failure downstream. With more than one lane you get each story's
+own state, and the run's state is the worst of them — four green lanes and one `blocked`
+is a `blocked` run.
 
 **Pause points are technical, not per-story.** Any task can carry a `pause:` line, and
 the build halts *before* running it:
@@ -538,12 +574,15 @@ destructive file operations, a new dependency, an auth boundary, a public API co
 You can also give the run a standing policy up front ("halt before anything that touches
 auth") and it gets applied as each story's tasks are sliced.
 
-**What it will not do to your repo.** It runs exactly five git commands — `switch`,
-`switch -c`, `merge --no-ff`, `merge --abort`, and reads. It refuses to start on a dirty
-tree. It **never pushes**, never rebases, never resets, never deletes a branch, and
-never opens a PR. Merges are local, so a bad run is one `git reset` away; publishing
-stays yours. If the gate goes red after a merge it leaves the merge alone and tells you
-the undo command rather than running it.
+**What it will not do to your repo.** It runs exactly seven git commands — `switch`,
+`switch -c`, `merge --no-ff`, `merge --abort`, `worktree add`, `worktree list`, and
+reads. It refuses to start on a dirty tree, or if a worktree path it needs already
+exists. It **never pushes**, never rebases, never resets, never deletes a branch, never
+removes a worktree, and never opens a PR. Merges are local, so a bad run is one
+`git reset` away; publishing stays yours. If the gate goes red after a merge it leaves
+the merge alone and tells you the undo command rather than running it — and it hands
+back the `git worktree remove` commands for the lanes instead of running those either,
+since a halted lane's worktree is the tree you need to look at.
 
 **Walk away and come back.** Progress isn't written down, it's derived: a story whose
 ticked `tasks.md` is on `main` is done, a `.spec/<slug>/` with an unchecked task is in

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/README.md

@@ -412,10 +412,19 @@ unnoticed.
 1. Plan the task against the constitution (inline, brief).
 2. Implement it with a fresh `tiny-spec-build-executor` agent.
 3. Review it with an independent `tiny-spec-build-reviewer` agent that runs the gate
-   end to end and grades against the constitution and the task's acceptance.
+   and grades against the constitution and the task's acceptance.
 4. On pass, commit the code plus a checklist tick. On fail, loop back to the
    executor with the findings. After two failed attempts the run halts `exhausted`.
 
+Every task's acceptance is exercised end to end, black-box, by the reviewer — that part
+never varies. What does vary is how much of the toolchain gets re-proven around it: a
+clean `install → build` runs on the first task, the last one, anything touching
+dependency or build config, and anything carrying `design:`; in between the reviewer runs
+lint and tests against the existing build. It escalates back to the full gate whenever the
+narrower one can't carry the verdict, and the authoritative clean run happens once more
+over the whole project as the final smoke. Re-installing from scratch on every task
+proved the same thing repeatedly and was the slowest part of the loop.
+
 ```mermaid
 flowchart TB
     SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[tasks.md<br/>checklist]
@@ -423,7 +432,7 @@ flowchart TB
     TASKS -->|pause: set| H[Halt — paused<br/>task stays unchecked]
     TASKS --> P[Plan task]
     P --> I[Implement<br/>executor]
-    I --> R[Review + run gate<br/>reviewer]
+    I --> R[Review + run gate<br/>full or scoped<br/>reviewer]
     I -->|blocker| B
     R -->|pass| C[Commit + tick]
     C --> TASKS
@@ -452,15 +461,38 @@ resumes from the checklist state.
 ### Working a whole list
 
 Ask `/tiny-spec-run` to build — "build the backlog", "work through the breakdown",
-"spec it out and build it" — and it takes a list of stories and works them one after
-another. Per story it does the same four moves:
+"spec it out and build it" — and it takes a list of stories and works them in batches.
+Per story it does the same four moves:
 
 ```
 cut a branch from main  →  walk the chain  →  tiny-spec-build  →  merge back to main
 ```
 
-Then the next story. Each branch is cut **fresh from main**, so story 3 sees stories 1
-and 2 already merged — which is what makes an ordered list build correctly.
+Each branch is cut **fresh from main**, so a later story sees the earlier ones already
+merged — which is what makes an ordered list build correctly.
+
+**Independent stories build at the same time.** A story can declare what it must follow
+with a `needs:` line in `BREAKDOWN.md`; everything with no unmet `needs:` forms a batch
+and builds **concurrently, one git worktree per story**, three at a time by default.
+The batch merges, then the next one starts.
+
+```
+## Feature: interface
+
+- Story: expose both helpers on a CLI     slug: cli
+  - AC: `textkit slugify "Hi There"` prints "hi-there"
+  - needs: slugify, wordwrap
+```
+
+Omit `needs:` when a story stands alone — that's the common case, and the field is meant
+to be rare. A `needs:` you didn't need costs you parallelism forever; one you missed
+costs a single merge conflict, which the run already catches and halts on. You can also
+just name the set yourself at invocation ("build these three at once"), which overrides
+the graph. A cycle, or a `needs:` naming a story that isn't there, stops the run rather
+than being guessed past.
+
+**Tasks *inside* a story never run in parallel.** They share files and each one assumes
+the last landed, so they stay strictly sequential. Parallelism is across stories only.
 
 **The list is `BREAKDOWN.md` by default** — its `- Story:` entries, in file order,
 each already carrying a `slug:` (the branch and directory name) and `AC:` lines. Paste
@@ -483,9 +515,13 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 Stopping at story 2 of 7 and reporting "done" is what autonomous loops get wrong most
 often, so the state is always named alongside what merged and what's still untouched.
 
-**A halt stops the whole run, not just that story.** Later stories in a list you wrote
-top to bottom usually assume the earlier ones landed, so skipping ahead past a failure
-just produces a second, more confusing failure downstream.
+**A halt stops the lane it happened in, and ends the run after that batch.** Its siblings
+were declared independent, so they finish and merge — killing working lanes because one
+failed throws away good work. But the run does not start the next batch: later stories
+usually assume the earlier ones landed, so skipping ahead past a failure just produces a
+second, more confusing failure downstream. With more than one lane you get each story's
+own state, and the run's state is the worst of them — four green lanes and one `blocked`
+is a `blocked` run.
 
 **Pause points are technical, not per-story.** Any task can carry a `pause:` line, and
 the build halts *before* running it:
@@ -501,12 +537,15 @@ destructive file operations, a new dependency, an auth boundary, a public API co
 You can also give the run a standing policy up front ("halt before anything that touches
 auth") and it gets applied as each story's tasks are sliced.
 
-**What it will not do to your repo.** It runs exactly five git commands — `switch`,
-`switch -c`, `merge --no-ff`, `merge --abort`, and reads. It refuses to start on a dirty
-tree. It **never pushes**, never rebases, never resets, never deletes a branch, and
-never opens a PR. Merges are local, so a bad run is one `git reset` away; publishing
-stays yours. If the gate goes red after a merge it leaves the merge alone and tells you
-the undo command rather than running it.
+**What it will not do to your repo.** It runs exactly seven git commands — `switch`,
+`switch -c`, `merge --no-ff`, `merge --abort`, `worktree add`, `worktree list`, and
+reads. It refuses to start on a dirty tree, or if a worktree path it needs already
+exists. It **never pushes**, never rebases, never resets, never deletes a branch, never
+removes a worktree, and never opens a PR. Merges are local, so a bad run is one
+`git reset` away; publishing stays yours. If the gate goes red after a merge it leaves
+the merge alone and tells you the undo command rather than running it — and it hands
+back the `git worktree remove` commands for the lanes instead of running those either,
+since a halted lane's worktree is the tree you need to look at.
 
 **Walk away and come back.** Progress isn't written down, it's derived: a story whose
 ticked `tasks.md` is on `main` is done, a `.spec/<slug>/` with an unchecked task is in

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/agents/tiny-spec-build-executor.md

@@ -15,6 +15,12 @@ pleasantries.
 
 Everything you need and nothing you don't:
 
+- **the working directory** to operate in. Every path you read, write, or run a command
+  against resolves against it. It may be a **git worktree** rather than the main checkout
+  — a build can run several stories at once, each in its own worktree. **Never read or
+  write outside the directory you were given**, and never `cd` to a sibling worktree to
+  "check something": another story is being built there right now, and what you find will
+  be wrong by the time you act on it;
 - the **task id**, **description**, and **acceptance** (the outcome that proves it done);
 - a **`files:` hint** — likely paths to touch (guidance, not a hard boundary);
 - the full **constitution** (`constitution.md`): Style, Engineering standards,
@@ -24,7 +30,10 @@ Everything you need and nothing you don't:
   so you don't re-learn a pitfall a past run already paid for;
 - **if the task carries `design:`** — that screen's `D<n>` entry from `SPEC.md` and
   the path to its committed export;
-- the specific existing files that are your starting point, named explicitly.
+- the specific existing files that are your starting point, named explicitly;
+- sometimes, **the files the previous task left behind** — paths only. Start there when
+  orienting: it is the most recently moved ground in the codebase and the most likely
+  place your task connects to.
 
 You are **blind to the workflow, not to the codebase.** You don't get the plan,
 other tasks, or shared state. But the named files are a launch point, not the whole
@@ -64,7 +73,11 @@ violated.
 6. You MAY run a **narrow self-check** of your own work (the one test file you
    wrote, a syntax/import check). You do **not** need to run the full gate — the
    independent **reviewer** runs the authoritative Verification commands next.
-   Leave the tree in a clean, buildable state for it.
+   **Leave the tree in a clean, buildable, installed state for it** — the reviewer may
+   run against the existing build rather than rebuilding from scratch, so a tree you
+   left half-migrated or with a stale artifact costs the task a review cycle. If you
+   changed dependencies or build configuration, apply them (install, regenerate the
+   lockfile) rather than leaving it for someone else, and say so in `CHANGES`.
 
 ## Hard constraints
 

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/agents/tiny-spec-build-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-build-reviewer
-description: Independently reviews a single finished task — runs the project's real gate end-to-end and checks the code against the constitution and the task's acceptance. Blind to how the code was written. Returns PASS/FAIL plus findings. Spawned (one per task) by tiny-spec-build. Does not fix code, plan, spawn agents, or invoke skills.
+description: Independently reviews a single finished task — runs the project's real gate at the scope it was given (full or scoped, escalating when scoped can't carry the verdict), exercises the acceptance end-to-end, and checks the code against the constitution. Blind to how the code was written. Returns PASS/FAIL plus findings. Spawned (one per task) by tiny-spec-build. Does not fix code, plan, spawn agents, or invoke skills.
 tools: Read, Write, Edit, Bash, Grep, Glob
 ---
 
@@ -13,10 +13,18 @@ back to `tiny-spec-build`; return data, not pleasantries.
 
 ## What you receive (the context contract)
 
+- **the working directory** to operate in — every path and every gate command resolves
+  against it. It may be a **git worktree** rather than the main checkout, since a build
+  can run several stories at once. **Never read, write, or run a gate outside the
+  directory you were given**: a sibling worktree holds a different story mid-build, and
+  measuring it would make your verdict meaningless;
 - the **task id**, **description**, and **acceptance** (the outcome that must hold);
 - the full **constitution** (`constitution.md`) — especially **Guiding invariants**,
   **Definition of Done**, and **Verification commands**, plus the **Design system**
   token table if the project has one;
+- the **gate scope** for this task — `full` or `scoped`. `tiny-spec-build` sets it; it
+  knows where this task sits in the run and you don't. If the brief names no scope,
+  treat it as `full`;
 - the project's **memory** if any (`memory.md`) — operational lessons (e.g. the
   gate needs the package installed first); honor them so you don't false-fail on a
   known precondition;
@@ -32,10 +40,38 @@ acceptance and the constitution — verified, not inferred?**
 1. **Read the changed code.** Check it against the constitution: does it honor the
    **Guiding invariants**, match the **Style** and **Layout**, meet the
    **Definition of Done**? Note any violation as a finding.
-2. **Run the real gate.** Execute the constitution's **Verification commands**
-   end-to-end (install → lint → test → build → run, as applicable) from a clean
-   state, after the documented setup — not a test-runner shortcut. Capture the
-   real output.
+2. **Run the real gate, at the scope you were given.** Capture the real output either
+   way — never a test-runner shortcut, never an inferred result.
+
+   - **`full`** — execute the constitution's **Verification commands** end-to-end
+     (install → lint → test → build → run, as applicable) from a clean state, after the
+     documented setup.
+   - **`scoped`** — run `lint:` and `test:` against the working tree, and rely on the
+     existing install/build state rather than rebuilding it from clean. Step 3 below is
+     **not** scoped: you still exercise the acceptance end-to-end, black-box, with real
+     input. A scoped gate skips re-proving the toolchain; it never skips proving the task.
+
+   **Escalate rather than guess.** Move a `scoped` gate up to `full` the moment the
+   narrower one can't carry the verdict — you need a build artifact that isn't there or
+   looks stale, `install`/`build` state seems inconsistent with the changed files, a
+   command fails in a way that might be environmental, or you simply cannot exercise the
+   acceptance without building. Escalation is always allowed and always safe. **Passing a
+   task on evidence you found insufficient is not** — that is the one thing this whole
+   role exists to prevent. Never narrow a `full` gate to `scoped`.
+
+   **A Verification command that cannot run in this environment is a `FAIL` and a
+   blocker — never a `PASS`.** If a documented command is red for a reason the task's
+   code cannot fix (the interpreter is too old, a tool isn't installed, the command was
+   never runnable as written), say exactly that in `GATE:`, return `FAIL`, and name the
+   **constitution** as the upstream document to fix. Proving the task green *somewhere
+   else* — a fresh venv, a container, an install you fixed by hand — is **not** a pass:
+   you verified a different environment than the one the gate names, and the next task
+   will hit the identical red. Diagnosing the cause and demonstrating the task's own code
+   is sound is genuinely useful; put it in `FINDINGS` so the fix is cheap. It does not
+   change the verdict. A constitution whose gate cannot run is the single most dangerous
+   file in the project, because every later task inherits the same false signal.
+
+   Say which scope you actually ran in `GATE:`, including that you escalated and why.
 3. **Exercise the acceptance.** Trigger the task's stated outcome the most
    black-box way available (CLI > HTTP > public API) with realistic input,
    including a negative case if the acceptance implies a boundary or rejection.
@@ -59,25 +95,23 @@ acceptance and the constitution — verified, not inferred?**
    - **A selector that matches nothing is a `FAIL`, never a skip.** Either the code
      didn't build the element or it named it something else — both are real, and both
      are invisible if you quietly move on. Report the selector and that it was absent.
-   - Compare each element's numbers to the tokens its row names. Report concrete
-     deltas ("heading is 28px, `type.heading.lg` is 24px"; "padding 19px is not on
-     the `space.*` scale"). **Do not pixel-diff the screenshot** — font antialiasing
-     makes image comparison flaky enough that the check gets ignored, which is
-     exactly how visual gates die.
-   - **Check `layout:`** — the arrangement, max width, and the **order** it names.
-     Use the bounding rectangles: elements listed in order should appear in that
-     order down the page (or across it, for a row). Every token can be correct on an
-     element that is in the wrong place.
-   - **Exercise every state the entry names** — empty, loading, error, success.
-     Drive the UI into each one and observe what changes; **finding the word in the
-     source is not evidence**, and it false-passes routinely (a comment saying the
-     loading state is missing contains "loading"). A surface that renders its happy
-     path and nothing else is a fail, not a nit.
-   - Finally, **judge the render against the export.** Everything above proves the
-     numbers are right. None of it can see an element that is present, on-token, and
-     invisible — so now look. `Read` each `SCREENSHOT <state> <path>` the `visual:`
-     command printed, `Read` the `D<n>`'s `export:` image, and grade **every state you
-     have a screenshot for**, not just the happy path, on four lines:
+   - Compare each element's numbers to the tokens its row names, reporting concrete
+     deltas ("heading is 28px, `type.heading.lg` is 24px"; "padding 19px is not on the
+     `space.*` scale"). **Do not pixel-diff the screenshot** — font antialiasing makes
+     image comparison flaky enough that the check gets ignored, which is how visual
+     gates die.
+   - **Check `layout:`** — the arrangement, max width, and the **order** it names, from
+     the bounding rectangles. Every token can be correct on an element in the wrong place.
+   - **Exercise every state the entry names** — empty, loading, error, success. Drive the
+     UI into each one and observe what changes; **finding the word in the source is not
+     evidence**, and it false-passes routinely (a comment saying the loading state is
+     missing contains "loading"). A surface that renders its happy path and nothing else
+     is a fail, not a nit.
+   - Finally, **judge the render against the export.** Everything above proves the numbers
+     are right; none of it can see an element that is present, on-token, and invisible —
+     so now look. `Read` each `SCREENSHOT <state> <path>` the `visual:` command printed
+     and the `D<n>`'s `export:` image, and grade **every state you have a screenshot
+     for**, not just the happy path, on four lines:
 
      1. **Presence** — is every `elements:` row actually *visible* in the render? At
         `opacity: 0`, zero height, clipped out of view, hidden behind a sibling, or the
@@ -85,24 +119,21 @@ acceptance and the constitution — verified, not inferred?**
         not there. **FAIL** — this is why the step exists.
      2. **Legibility & occlusion** — text clipped, truncated mid-word, overlapping
         another element, or on a background it can't be read against. **FAIL.**
-     3. **Correspondence** — does the render show the same screen as the export: the
-        same regions, in the reading order `layout:` names? A whole region missing is a
-        **FAIL**; a stylistic difference is a **flag**.
+     3. **Correspondence** — the same regions as the export, in the reading order
+        `layout:` names? A whole region missing is a **FAIL**; a stylistic difference is
+        a **flag**.
      4. **Hierarchy & polish** — emphasis, balance, crowding, alignment. **Always a
         flag**, never a fail.
 
-     Three rules bound it:
-
-     - **The numbers beat your eye on anything they already measured.** Padding that is
-       on the `space.*` scale but looks cramped is a `flag:`. A color that is exactly
-       its token but looks washed out is a `flag:`. You may fail only on what
-       measurement *cannot* see. Contradicting your own numbers sends the executor a
-       task it cannot fix, and the loop is bounded at two attempts.
-     - **This is still not a pixel diff.** The export is usually a wireframe — judge
-       structure and legibility, never visual identity.
-     - **Cite what you saw.** Name the state whose screenshot the finding came from and
-       what was in it ("state `error`: caption present in DOM but renders at opacity 0").
-       An uncited visual claim reads as an opinion and gets ignored.
+     Three rules bound it. **The numbers beat your eye on anything they already
+     measured** — on-scale padding that looks cramped, or an exact token that looks
+     washed out, is a `flag:`; you may fail only on what measurement *cannot* see, since
+     contradicting your own numbers sends the executor a task it cannot fix and the loop
+     is bounded at two attempts. **This is still not a pixel diff** — the export is
+     usually a wireframe, so judge structure and legibility, never visual identity. And
+     **cite what you saw**, naming the state the finding came from ("state `error`:
+     caption present in DOM but renders at opacity 0") — an uncited visual claim reads as
+     an opinion and gets ignored.
 
      **If the command printed no `SCREENSHOT` line**, do not run this sub-step and do
      not eyeball a substitute. Grade on steps 1–3 above, write `judge: not run — visual:
@@ -158,7 +189,8 @@ Never spawn subagents or invoke skills.
 ```
 TASK: <task id>
 VERDICT: PASS | FAIL
-GATE: <the Verification commands you ran + the real result (pass/fail + key output)>
+GATE: <scope: full | scoped (+ "escalated from scoped: <why>" if you moved it up);
+  the Verification commands you ran + the real result (pass/fail + key output)>
 ACCEPTANCE: <how you exercised it + the observed effect, or why you couldn't>
 DESIGN: <omit unless the task carried `design:`. The D<n> checked, the measurements
   you read back vs the tokens they should match, and which states you exercised —

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tiny-spec"
-version = "1.0.1"
+version = "1.2.0"
 description = "A tiny, opinionated take on spec-driven development."
 readme = "README.md"
 requires-python = ">=3.9"

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/tiny-spec-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-build
-description: Build the spec — run the per-task loop plan→implement→review→commit, one task at a time. Implements with a fresh executor, grades with an independent reviewer running the real gate, commits per passed task, keeps a lean memory. Halts on a blocker, a spent convergence budget, a task's pause: point, or a genuine fork, and names which. Resumes from the checkbox state.
+description: Build the spec — run the per-task loop plan→implement→review→commit, one task at a time. Implements with a fresh executor, grades with an independent reviewer running the real gate, commits per passed task, keeps a lean memory. Can be handed several lanes (one worktree + slug per independent story) and runs them concurrently, one task at a time within each. Halts on a blocker, a spent convergence budget, a task's pause: point, or a genuine fork, and names which. Resumes from the checkbox state.
 ---
 
 # tiny-spec-build
@@ -19,16 +19,14 @@ alongside this skill (see the suite README).
 
 ## Inputs
 
-1. **Resolve the active ticket dir** from the current git branch: the `.spec/<slug>/`
-   whose slug matches the branch name (one branch per ticket). If none matches, use
-   the sole ticket dir if there's exactly one; else ask which. Call it `<active>`.
-   **Two cases pre-empt that order — ask instead of applying it:** more than one dir
-   matches the branch (there is no defined tie-break, and inventing one here would
-   silently disagree with every other skill), or ticket dirs exist while you are on
-   `main`/`master` with no name match (the usual cause is a forgotten `git switch`, and
-   the sole-dir fallback would otherwise swallow it). Detached HEAD or no git repo is a
-   **degraded** case, not an ask case — branch match is simply unavailable, so fall
-   through to sole-dir and ask as written.
+1. **Resolve the active ticket dir** (call it `<active>`), in order: the `.spec/<slug>/`
+   whose slug matches the current git branch (one branch per ticket); else the sole
+   ticket dir if exactly one exists; else ask. **Ask instead** when more than one dir
+   matches the branch, or when ticket dirs exist while you are on `main`/`master` with no
+   name match — neither has a safe tie-break. Detached HEAD or no git repo is
+   **degraded**, not an ask: fall through to sole-dir and ask as written.
+   In **multi-lane mode** (below) this step does not run: each lane is handed its
+   worktree and slug explicitly.
 2. Read `.spec/constitution.md` (**the shared constitution**), `.spec/memory.md` if
    it exists (**shared**), and `.spec/<active>/tasks.md`. The constitution + memory
    get injected **whole** into every executor and reviewer. Also note the `ticket`
@@ -37,6 +35,52 @@ alongside this skill (see the suite README).
    `tiny-spec-plan` to reconcile first.
 4. Pick the **first unchecked `[ ]`** task. If all are `[x]`, jump to **Completion**.
 
+## Multi-lane mode (optional — several stories at once)
+
+A caller may hand you **lanes** instead of a single active dir: one or more
+`(worktree path, slug)` pairs, each an independent story in its own git worktree.
+`tiny-spec-run` does this for a batch of stories whose `needs:` say they don't depend on
+each other. **With one lane, or none, everything below is inert and this skill behaves
+exactly as it always has** — that is the common case and it must not drift.
+
+Given lanes, run them **in rounds**:
+
+1. For every live lane, pick its first `[ ]` task and build the executor brief exactly as
+   step 2 describes — resolved against **that lane's worktree**, not the main checkout.
+2. **Dispatch every lane's executor in one message**, so they run concurrently.
+3. **Dispatch every lane's reviewer in one message**, once the executors are back.
+4. Commit and tick per passing lane, in that lane's worktree.
+
+Then start the next round with whichever lanes are still live. A fast lane waits at the
+round boundary for a slow one; that barrier is deliberate, and much simpler to follow than
+letting lanes free-run.
+
+**Within a lane nothing changes.** Tasks still run one at a time, top to bottom, with the
+same convergence bound, the same gate scope rules, and the same halting states. There is
+no parallelism *inside* a story and no `owns:` contract — tasks in one story share files
+and assume their predecessors landed, which is exactly why they stay sequential.
+
+**A halt stops that lane only.** The other lanes run to completion; you report each lane's
+terminal state separately. The stories were declared independent, so killing working lanes
+because one failed throws away finished work for nothing.
+
+**Every dispatched agent is told its working directory**, and that all paths resolve
+against it. An executor or reviewer must never read or write another lane's worktree.
+
+### `memory.md` in multi-lane mode
+
+`.spec/memory.md` is **shared at the `.spec/` root**, and step 6 below writes to it. Two
+lanes appending to their own copy in their own worktree would conflict on *every* parallel
+batch — a guaranteed merge failure that has nothing to do with the code.
+
+So: **in multi-lane mode, lanes do not write `memory.md` at all.** Collect each lane's
+distilled lessons as it goes, and write them **once, in the main checkout on the
+integration branch, after the batch has merged** — pruning superseded entries there, as
+step 6 describes. Single-lane runs are unaffected and write it in place as before.
+
+The other artifacts are safe and need no special handling: `tasks.md` and `decisions.md`
+are per-story, and `constitution.md` is read-only for the whole build.
+
 ## The per-task loop
 
 For the selected task, run these steps in order. **Do not tick a task until its
@@ -60,6 +104,9 @@ it short and concrete.
 ### 2. IMPLEMENT (dispatch `tiny-spec-build-executor`)
 Spawn one **`tiny-spec-build-executor`** with a fresh, self-contained prompt:
 
+- **the working directory** it must operate in — this lane's worktree, or the project
+  root in a single-lane run. Every path resolves against it, and it must never read or
+  write another lane's worktree;
 - the task id, description, and **acceptance**;
 - the `files:` hint;
 - the **whole** `.spec/constitution.md`;
@@ -68,7 +115,16 @@ Spawn one **`tiny-spec-build-executor`** with a fresh, self-contained prompt:
   `.spec/<active>/SPEC.md` plus its `export:` path, so the executor can look at the
   design instead of guessing at it;
 - only the specific existing files the task starts from, named explicitly (so it
-  edits with the real current contents, not blind).
+  edits with the real current contents, not blind);
+- the **accumulated `CHANGES` paths from every passed task in this story so far**,
+  labelled as the ground this story has already moved. Every executor starts cold and
+  re-derives the codebase from scratch — that re-derivation is the **largest single cost
+  in the loop**, far larger than the prompt text around it — and naming the files this
+  story has already touched is the cheapest way to cut it. You already have the lists in
+  hand. **Paths only**, deduplicated, most-recently-touched first — never the earlier
+  tasks' descriptions, findings, or reports. (The reviewer does *not* get this list: it
+  is scoped to the task's own changed files on purpose, and widening it would dilute the
+  independence that makes its verdict worth anything.)
 
 Do **not** pass the plan, sibling tasks, or other chatter. It returns a structured
 report (`STATUS`, `CHANGES`, `DECISIONS`, `BLOCKER`). A `STATUS: blocked` →
@@ -77,14 +133,34 @@ report (`STATUS`, `CHANGES`, `DECISIONS`, `BLOCKER`). A `STATUS: blocked` →
 ### 3. REVIEW (dispatch `tiny-spec-build-reviewer` — independent)
 Spawn one **`tiny-spec-build-reviewer`**, **blind to step 2**, with:
 
+- **the working directory** it must operate in — this lane's worktree, or the project
+  root in a single-lane run. It runs the gate there and touches no other lane;
 - the task id, description, and **acceptance**;
 - the **whole** `.spec/constitution.md`;
 - the list of changed files (from the executor's `CHANGES`) to read;
-- the **Verification commands** from the constitution to run;
+- the **Verification commands** from the constitution to run, and the **gate scope**
+  for this task — `full` or `scoped` (decide it as below; you have the run context,
+  the reviewer does not);
 - **if the task has a `design:` field** — the same `D<n>` entry and `export:` path
   you gave the executor, so it grades against the contract rather than its taste.
 
-It runs the real gate end-to-end, checks the code against the constitution's
+**Gate scope.** A clean `install → build` proves the same thing on task 7 that it proved
+on task 1 unless a task changed what it installs or builds, so running it every time buys
+little and costs the most wall-clock in the loop. Name the scope in the brief:
+
+- **`full`** — the whole gate from a clean state (install → lint → test → build → run).
+  Use it on: the **first** task of this run; any task whose `CHANGES` touch dependency or
+  build configuration (`package.json`/lockfiles, `pyproject.toml`, `go.mod`, `Cargo.toml`,
+  `Dockerfile`, CI config, build scripts); any task carrying `design:`; and the **last**
+  task in `tasks.md`.
+- **`scoped`** — otherwise. `lint:` + `test:` plus the acceptance exercised end-to-end,
+  black-box, exactly as on a full gate. The acceptance exercise is never scoped away; it
+  is the whole reason the reviewer exists.
+
+The reviewer may **escalate** `scoped` to `full` on its own and will say so — that
+direction is always safe. It may never go the other way.
+
+It runs the gate at the scope you named, checks the code against the constitution's
 **Definition of Done** and **invariants**, confirms the **acceptance** actually
 holds (exercised, not inferred), and returns `VERDICT: PASS | FAIL` + findings.
 On a `design:` task it also runs the constitution's `visual:` command, measures the
@@ -94,11 +170,15 @@ numbers can't reach, like an element that measures perfectly and shows up invisi
 It fails on what it measured or saw, and merely flags what is taste.
 
 > Why independent: unit-green ≠ working, and the author is the worst judge of its
-> own blind spots. The reviewer running the gate from a clean state is the
-> safeguard that keeps scope and quality honest without an ownership contract.
+> own blind spots. The reviewer exercising the acceptance black-box — on every task,
+> at either scope — is the safeguard that keeps scope and quality honest without an
+> ownership contract.
 
 ### 4. CONVERGE (on FAIL)
-Re-dispatch the **executor** with the reviewer's findings appended to its brief.
+Re-dispatch the **executor** with the reviewer's findings appended to its brief, then
+review again — recomputing the **gate scope** from the fix's `CHANGES`, and using `full`
+if the failure was in the gate itself or the reviewer escalated last time. A task that
+already failed once has earned the wider check.
 Bound this to **2 fix attempts**. If it still fails after that, stop and **halt
 `exhausted`** (see **Halting** below) — don't keep grinding or hand-fix past the loop
 silently. `exhausted` is recorded as a blocker, because a task that three attempts
@@ -143,6 +223,9 @@ entry to the **shared** `.spec/memory.md` (the root — lessons are project-wide
 pruning any entry the new one supersedes. Skip code-style rules (→ shared
 `constitution.md`) and one-off history (→ the ticket's `decisions.md`). Keep it lean.
 
+**In multi-lane mode, do not write the file here.** Hold the entry and write it once
+after the batch merges — see **Multi-lane mode** above for why.
+
 On first use, create the file with this structure:
 
 ```markdown
@@ -186,7 +269,8 @@ way, which is why a loop and a hand-driven build can't drift apart.
 ## Halting
 
 Every build run ends in exactly **one** of five terminal states. Name it out loud in
-the closing report:
+the closing report — **per lane**, when there is more than one; a lane's halt never
+rounds up into another lane's `done`, and the run's own state is the worst of them:
 
 | State | Cause |
 |---|---|
@@ -274,6 +358,12 @@ When every task in `tasks.md` is `[x]`:
    setup — install/build, not a test-runner shortcut). There is no separate
    verify skill — this final smoke confirms the requirements actually work end-to-end, not
    just that tasks are ticked.
+
+   **This is the authoritative clean-state run for the whole build**, and it is never
+   scoped or skipped. Per-task gates run at the scope step 3 named; this one always runs
+   everything from clean. A build or install regression that a `scoped` task gate did not
+   re-prove surfaces here — which is why a red final smoke is a gap to fix or route
+   upstream, never a pass and never `done`.
 2. **Report** — the terminal state by name (`done` here, since every task is `[x]`
    and the smoke passed), what was built, the commits made (with the branch), and any
    open `decisions.md` items (blockers, tasks unchecked by a reconcile). If the final

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/tiny-spec-plan/SKILL.md

@@ -18,19 +18,15 @@ sets `tasks.md`'s `status:`.
 
 Artifacts live under `.spec/`: the **shared** constitution at the root
 (`.spec/constitution.md`), the per-ticket `SPEC.md`/`PLAN.md`/`tasks.md` under
-`.spec/<slug>/`. **Resolve the active ticket dir** from the current git branch: the
-`.spec/<slug>/` whose slug matches the branch name (one branch per ticket). If none
-matches, use the sole ticket dir if there's exactly one; else ask which. Both skeletons
-are inline below — write them from there, no file to read. Requires
-`.spec/<active>/SPEC.md`.
-
-**Two cases pre-empt that order — ask instead of applying it:** more than one dir
-matches the branch (there is no defined tie-break, and inventing one here would
-silently disagree with every other skill), or ticket dirs exist while you are on
-`main`/`master` with no name match (the usual cause is a forgotten `git switch`, and
-the sole-dir fallback would otherwise swallow it). Detached HEAD or no git repo is a
-**degraded** case, not an ask case — branch match is simply unavailable, so fall
-through to sole-dir and ask as written.
+`.spec/<slug>/`. Both skeletons are inline below — write them from there, no file to
+read. Requires `.spec/<active>/SPEC.md`.
+
+**Resolve the active ticket dir**, in order: the `.spec/<slug>/` whose slug matches the
+current git branch (one branch per ticket); else the sole ticket dir if exactly one
+exists; else ask. **Ask instead** when more than one dir matches the branch, or when
+ticket dirs exist while you are on `main`/`master` with no name match — neither has a
+safe tie-break. Detached HEAD or no git repo is **degraded**, not an ask: branch match is
+simply unavailable, so fall through to sole-dir and ask as written.
 
 ## Step 1 — harden the constitution (`constitution.md`)
 
@@ -138,25 +134,68 @@ past it into a task list — say what's unresolved and route back to `tiny-spec-
 ## Step 3 — slice the approach into tasks
 
 Walk the `## Approach` you just wrote and break it into tasks. No waves, no
-parallelism, no `owns:` contracts — tasks run one at a time, top to bottom. Each task is:
-
-- **Small and independently checkable** — one slice a single executor can finish and a
-  reviewer can grade in one pass. If you can't write a one-line acceptance for it, it's
-  too big — split it.
+parallelism, no `owns:` contracts — tasks run one at a time, top to bottom.
+
+**The unit is one coherent commit** — what a competent engineer does in one focused
+sitting and commits as a single unit of work. That typically touches several files and
+often satisfies several `REQ-N` at once. It is the size you would open as one reviewable
+change, not the smallest thing you could name.
+
+**Know what a task costs, so size has something to trade against.** Every task you write
+spends two cold-start agents that must re-orient in the codebase from scratch, a reviewer
+that runs the gate and exercises the acceptance end-to-end, and two commits. That
+overhead is **fixed** — it does not shrink for a small task. A task the executor
+finishes in thirty seconds still pays all of it. Size each task so the work inside it
+clearly outweighs the machinery around it.
+
+So:
+
+- **Split on independent failure, not on sentence length.** Split a task when it carries
+  two **unrelated** observable outcomes that could fail independently of each other. Do
+  **not** split because the acceptance got long — a good acceptance is usually several
+  clauses covering the happy path *and* its negatives. See `T4` in the `examples/todo-cli`
+  task list: two CLI commands, four requirements, and three negative cases, in one task,
+  with one acceptance. That is the calibration point, not the exception.
+- **One task may satisfy several `REQ-N`** — `req:` takes a list. Coverage means every
+  requirement has a *home*, not that every requirement gets its *own* task. **A 1:1
+  REQ→task mapping is the single most common way this list comes out too granular.**
+  Group the requirements that one coherent change delivers together.
 - **Ordered so each builds on the last.** Tasks run sequentially, so a later task may
   freely assume an earlier task's code already exists. Put foundational work (types,
   schema, scaffolding) first. Order by dependency, not by guesswork.
-- **Right-sized, not fragmented.** Don't split a cohesive change into five files' worth
-  of micro-tasks just to look granular. Earned ceremony: fewer, meaningful tasks beat
-  many trivial ones.
+
+**Smells that mean you sliced below the commit line** — fold each of these back into the
+task it belongs to:
+
+- a task that only defines types, interfaces, or schema with no behavior behind them;
+- a task that only adds tests for the task before it (the constitution's **Definition of
+  Done** already requires the tests to ship with the code);
+- one task per file, or one task per function;
+- a "wire it up" / "integrate the pieces" task trailing the pieces it wires;
+- a **leading pure-scaffold task** — a skeleton, a dispatch stub, a module that imports
+  cleanly and does nothing. Fold it into the first task that gives it behavior;
+- a **trailing end-to-end verification task**. `tiny-spec-build`'s Completion step already
+  runs the whole gate against the whole project from a clean state, exercised the way a
+  user would. A task that re-does it buys nothing and costs the full per-task overhead.
+
+The shipped `examples/todo-cli` task list predates these two smells and shows both: its
+`T1` is a pure scaffold and its `T5` is an end-to-end verification pass. Today `T1` folds
+into `T2` and `T5` doesn't exist. Read that list for `T4`'s sizing, not for its edges.
+
+**Count is a smell, not a cap.** A story sized the way `tiny-spec-scope` describes
+usually lands in **2–4 tasks**. If you are past about six, re-read the list: you have
+either sliced below the commit line, or the story itself was too big and should have been
+split upstream. Check the list against that; do **not** enforce a number, and never drop
+or merge coverage just to hit one.
 
 For each task, write:
 
 ```
 - [ ] T<n> — <imperative description>
-  - acceptance: <one user-observable outcome that proves it's done>
+  - acceptance: <one user-observable outcome that proves it's done — happy path and the
+                 negatives that bound it, in one entry>
   - type: feat            # optional; Conventional Commit type (defaults to feat)
-  - req: REQ-n            # optional; the REQ-N this task delivers
+  - req: REQ-n, REQ-n     # optional; the REQ-N this task delivers — a list, not one
   - design: D-n           # optional; the SPEC.md D<n> screen this task builds — arms the visual gate
   - pause: <why>          # optional; halt the build before this task so a human looks first
   - files: <comma-separated hint of files it will touch>
@@ -164,7 +203,11 @@ For each task, write:
 
 The **acceptance** is what the reviewer checks against — make it observable
 ("`spec --version` prints the version and exits 0"), not internal ("version logic
-added"). **type** picks the Conventional Commit type `tiny-spec-build` uses for this
+added"). It states **one outcome**, but one outcome is not one clause: spell out the
+happy path and the negatives that bound it in the same acceptance, separated by
+semicolons. A long acceptance is a well-specified task, not an oversized one — it is the
+*number of unrelated things that could fail* that decides whether to split, not the
+length of the line. **type** picks the Conventional Commit type `tiny-spec-build` uses for this
 task's code commit (`feat | fix | docs | refactor | test | chore | build | ci | perf | style`);
 set it when the task is clearly not a feature, otherwise omit and it defaults to `feat`.
 **req** ties the task to the requirement it satisfies (traceability). The **files** line
@@ -211,7 +254,9 @@ anyway. A policy that matches nothing here is not an error — say so and move o
 than stretching a task to fit it.
 
 Cover **every** part of the approach — together the tasks must deliver all `REQ-N`.
-Don't leave a requirement with no task. Likewise, if `SPEC.md` has a `## Design`
+Don't leave a requirement with no task. Coverage is about requirements having a home,
+not about the shape of the mapping: several `REQ-N` on one task is the normal case, and
+a task per requirement is the anti-pattern. Likewise, if `SPEC.md` has a `## Design`
 section, every `D<n>` in it needs at least one task carrying that `design:` reference —
 a screen nobody is graded against is a screen that will be built wrong.
 
@@ -236,25 +281,31 @@ updated: <ISO date>
 
 ## Tasks
 
-- [ ] T1 — <one small, independently-checkable slice of work>
-  - acceptance: <one user-observable outcome that proves T1 is done>
+- [ ] T1 — <one coherent commit's worth of foundational work; usually several files>
+  - acceptance: <the observable outcome; happy path; and the negative case that bounds it>
   - type: feat            # optional; Conventional Commit type for this task's commit (defaults to feat)
-  - req: REQ-1            # optional; the REQ-N this task delivers
-  - files: <path, path>
+  - req: REQ-1, REQ-2     # optional; the REQ-N this task delivers — several is normal
+  - files: <path, path, path>
 
-- [ ] T2 — <next slice; assume T1's code exists>
-  - acceptance: <observable outcome>
+- [ ] T2 — <next coherent change; assume T1's code exists>
+  - acceptance: <observable outcome; plus what it rejects and how it fails>
   - type: feat
-  - req: REQ-2
+  - req: REQ-3, REQ-4, REQ-5
   - design: D1            # optional; only on tasks that build the visible surface
   - files: <path, path>
 
 - [ ] T3 — <…>
   - acceptance: <observable outcome>
+  - req: REQ-6
   - pause: <optional; what to check before this runs — irreversible work only>
   - files: <path, path>
 ```
 
+The `req:` lists above are the shape to aim for, not filler: a handful of tasks each
+carrying the requirements one coherent change delivers. A skeleton filled in as
+`REQ-1`, `REQ-2`, `REQ-3` down a column of single-requirement tasks is the granularity
+failure described in Step 3.
+
 ## Update mode (SPEC changed → PLAN and tasks are stale)
 
 When `PLAN.md` or `tasks.md` is `status: stale`, reconcile **both in one pass** — they

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/tiny-spec-run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-run
-description: The one router — read each artifact's status flag to work out where work stands, then invoke the skill that moves it forward. Two stop points, chosen once at the start: by default it walks tiny-spec-adopt/create → design → plan and STOPS before tiny-spec-build; asked to build ("spec it out and build it") or handed a story list, it drives each story branch → plan → build → merge until the list ends or something halts it. Use for "run the spec flow", "pick the chain back up", "build the backlog", "work through the breakdown". NOT for a single stage — for that invoke tiny-spec-create, tiny-spec-plan, or tiny-spec-design directly.
+description: The one router — read each artifact's status flag to work out where work stands, then invoke the skill that moves it forward. Two stop points, chosen once at the start: by default it walks tiny-spec-adopt/create → design → plan and STOPS before tiny-spec-build; asked to build ("spec it out and build it") or handed a story list, it drives each story branch → plan → build → merge until the list ends or something halts it. Independent stories — grouped by their BREAKDOWN.md needs: field, or named by the user — build concurrently, one git worktree per lane, merging batch by batch. Use for "run the spec flow", "pick the chain back up", "build the backlog", "work through the breakdown". NOT for a single stage — for that invoke tiny-spec-create, tiny-spec-plan, or tiny-spec-design directly.
 ---
 
 # tiny-spec-run
@@ -53,8 +53,8 @@ return to Step 2 after a stage, or between stories.
    the branch for the user.
 
 2. **Resolve the story list** (below) and play it back in order — slug and title — with
-   the state you derived for each. This is the user's chance to reorder, drop, or narrow
-   before anything is cut.
+   the state you derived for each, **grouped into the batches you will run**. This is the
+   user's chance to reorder, drop, narrow, or correct a dependency before anything is cut.
 
 3. **Take the pause policy.** Ask for, or accept, standing technical stop points for
    this run — *"halt before anything that touches auth"*, *"stop before any schema
@@ -63,6 +63,17 @@ return to Step 2 after a stage, or between stories.
    **technical**, not per-story: the thing worth looking at is a migration or an auth
    boundary, not a feature heading.
 
+4. **Fix the lane count.** Default **3**; take a number from the user if they gave one.
+   This is a concurrency limit on the machine, not a budget — the story list is still the
+   budget, and a batch wider than the lane count simply runs in successive fills. **One
+   lane must stay available**: any phrasing asking for one story at a time ("one at a
+   time", "no parallelism", "serially") sets it to 1, which collapses Step 4 to the
+   sequential behavior — no worktrees, no batching.
+
+   Then check one more precondition, once you know the slugs in the first batch: **no
+   target worktree path already exists.** Name the collisions and stop; do not reuse or
+   remove a directory you found.
+
 ## Step 1 — resolve the scope
 
 ### Stop-before-build: the active ticket dir
@@ -126,7 +137,26 @@ on the integration branch at all, so "does the directory exist" can't tell "not
 apart from "built on a branch you haven't merged" — reading each ref explicitly can.
 Sourcing step 1 from the integration branch is also what survives a deleted branch: once
 a story is merged, its ticked task list is part of `main` whether or not the branch that
-built it still exists.
+built it still exists. **This survives parallelism unchanged** — a worktree is just a
+branch, so a story built in a worktree but not yet merged lands on rule 2 exactly as one
+built in place.
+
+**Group the remaining stories into batches.** Level 0 is every unbuilt story whose
+`needs:` are empty or already built-and-merged; level 1 is every story whose `needs:` are
+all in level 0; and so on. Batches run **in order**; the stories inside one batch run
+**concurrently**, capped at the lane count.
+
+- **A parallel set the user named at invocation overrides the graph** for this run —
+  "build these three at once", or a pasted list they called independent. Explicit beats
+  derived, the same way a pasted story list already wins over `BREAKDOWN.md`. Say that you
+  are overriding, and name what the graph would have done.
+- **A cycle in `needs:` is a stop.** Print the cycle and stop. Never break it by picking
+  an order — `tiny-spec-scope` says two stories that need each other are really one, and
+  choosing for the user hides a carve that needs fixing.
+- **A `needs:` naming a slug that isn't in the list is a stop**, not a shrug. It is either
+  a typo or a story someone dropped, and both want a human.
+- **A batch of one is the sequential behavior** — Step 4 collapses to exactly what it did
+  before lanes existed. This is the common case for a single ticket and must not change.
 
 ## Step 2 — the ladder
 
@@ -146,67 +176,62 @@ re-evaluate against the new state on disk.
 | — | **no rung matched** | **stop** — report the exact state you found and ask; never improvise a stage |
 
 **Upstream beats downstream — that is what the table order encodes.** Always fix the
-earliest artifact in the chain that needs attention, whether it's stale *or* missing.
-Deriving a task list from a design you already know is wrong wastes the run, and then
-the reconcile has to uncheck completed work all over again.
+earliest artifact in the chain that needs attention, stale *or* missing. Deriving a task
+list from a design you already know is wrong wastes the run, and the reconcile then has
+to uncheck completed work all over again.
 
 **L0/L1 carry the greenfield/brownfield fork.** "Does this repo already contain source?"
-means: is there real code here beyond config and docs? If yes, the constitution should
-be *derived from that code* (`tiny-spec-adopt`) rather than interviewed out of the user
-— an interviewed constitution on an existing codebase is how you get a gate that names
-commands the project doesn't have. If the user is starting from an idea with no code
-yet, `tiny-spec-scope` is theirs to run first; it is not in the ladder (see below).
-
-**L1 is a reseed, not a fresh start.** The constitution is project-wide, so it can go
-missing while a perfectly good `SPEC.md` sits next to it. Invoke the chosen skill in
-**reseed/refresh mode** — say so explicitly, and add: *do not re-interview from scratch,
-do not create a ticket dir, and do not touch `SPEC.md`.* If the constitution still
-doesn't exist afterwards, stop and tell the user; do not loop.
-
-**L1 outranks L2** — a constitution gets reseeded even when the ticket dir or `SPEC.md`
-is also missing. The next pass then lands on L2 and creates the spec properly — and
-because that's a *different rung*, the same-skill bound below does not fire.
-
-**L3 is a stop, not a stage.** Nothing in the suite ever *sets* `SPEC.md` to stale — it
-is the root of the chain. A stale SPEC means someone hand-edited it, so surface it and
-offer `tiny-spec-create` in update mode rather than assuming intent. If the user says go
-ahead **in the same turn**, invoke it and carry on down the ladder — the stop is there
-to get a human decision, not to force a second command. (Update mode *clears* the flag
-on its way out, so this rung resolves rather than repeating.)
-
-**L4 is the one thing `run` checks that isn't a `status:` flag** — and it is
-deliberately *not* a validator. For each `D<n>` in the active `SPEC.md`, run
-`shasum -a 256 <export>` and compare with the `sha256:` the entry declares. You are
-checking whether an anchor still points at what it says it points at, not inferring
-whether two documents agree. A design that moved under a finished spec is otherwise
-completely invisible — no status flips, and the build reviews against a screen that no
-longer exists.
+means: real code beyond config and docs. If yes, the constitution must be *derived from
+that code* (`tiny-spec-adopt`) rather than interviewed out of the user — an interviewed
+constitution on an existing codebase is how you get a gate that names commands the
+project doesn't have. Starting from an idea with no code yet, `tiny-spec-scope` is the
+user's to run first; it is not in the ladder (see below).
+
+**L1 is a reseed, not a fresh start**, and it **outranks L2**. The constitution is
+project-wide, so it can go missing while a perfectly good `SPEC.md` sits next to it.
+Invoke the chosen skill in **reseed/refresh mode** — say so explicitly, and add: *do not
+re-interview from scratch, do not create a ticket dir, and do not touch `SPEC.md`.* If the
+constitution still doesn't exist afterwards, stop and tell the user; do not loop. The next
+pass lands on L2 and creates the spec properly — a *different rung*, so the same-skill
+bound below does not fire.
+
+**L3 is a stop, not a stage.** Nothing in the suite ever *sets* `SPEC.md` to stale — it is
+the root of the chain — so a stale SPEC means someone hand-edited it. Surface it and offer
+`tiny-spec-create` in update mode rather than assuming intent. A go-ahead **in the same
+turn** is enough to invoke it and carry on down the ladder; the stop exists to get a human
+decision, not to force a second command. (Update mode *clears* the flag on its way out, so
+this rung resolves rather than repeating.)
+
+**L4 is the one thing `run` checks that isn't a `status:` flag**, and it is deliberately
+*not* a validator: for each `D<n>` in the active `SPEC.md`, run `shasum -a 256 <export>`
+and compare with the `sha256:` the entry declares. You are checking whether an anchor
+still points at what it says it points at, not inferring whether two documents agree. A
+design that moved under a finished spec is otherwise completely invisible — no status
+flips, and the build reviews against a screen that no longer exists.
 
 - **Mismatch** → `tiny-spec-design` in re-anchor mode.
 - **Missing file** → **stop and tell the user**, naming the entry and the path. Don't
-  route it: a deleted export can mean a rename, a move, or a design that was withdrawn,
-  and each wants a different answer. Never quietly drop the entry.
+  route it: a deleted export can mean a rename, a move, or a withdrawn design, and each
+  wants a different answer. Never quietly drop the entry.
 - No `## Design` section, or every hash matches → the rung doesn't fire; fall through.
 
 **Any `status:` that isn't exactly `current`** — `stale`, missing, unreadable, or an
 unrecognized value like `draft` — counts as **stale**, on `SPEC.md`, `PLAN.md`, and
-`tasks.md` alike. Say so out loud. For `PLAN.md`/`tasks.md` that means reconciling
-(update mode preserves existing ids, so it's the non-destructive way to be wrong); for
-`SPEC.md` it means L3 — stop and ask.
+`tasks.md` alike. Say so out loud. `PLAN.md`/`tasks.md` → reconcile (update mode preserves
+existing ids, the non-destructive way to be wrong); `SPEC.md` → L3, stop and ask.
 
-**A `tasks.md` with no tasks at all is not "built"** — that's why L6 and L7 both require
-at least one task, and why an empty checklist matches neither. It means the
-`tiny-spec-plan` run produced nothing, so L5 catches it. If it comes back empty a second
-time, stop and tell the user — the plan has nothing derivable in it.
+**A `tasks.md` with no tasks at all is not "built"** — L6 and L7 both require at least one
+task, so an empty checklist matches neither and L5 catches it. Empty a second time → stop
+and tell the user; the plan has nothing derivable in it.
 
 `run` trusts the `status:` flags. It does **not** second-guess hand edits, diff
-timestamps, or validate the chain — there is no validator in this suite by design. (L4
-is not an exception: a hash is a value the spec itself declares about a file it names,
-so checking it is reading state, not judging consistency. Do not use it as a precedent
-for adding cross-document checks.) That means it inherits each stage's propagation: if
-`tiny-spec-plan` update mode doesn't flip `tasks.md`, `run` will walk right past it.
-That trust is the price of having no validator; when a run's result looks wrong, suspect
-the stage's propagation before the ladder.
+timestamps, or validate the chain — there is no validator in this suite by design. (L4 is
+not an exception: a hash is a value the spec itself declares about a file it names, so
+checking it is reading state, not judging consistency. Not a precedent for adding
+cross-document checks.) So it inherits each stage's propagation: if `tiny-spec-plan`
+update mode doesn't flip `tasks.md`, `run` walks right past it. That trust is the price of
+having no validator; when a run's result looks wrong, suspect the stage's propagation
+before the ladder.
 
 **`tiny-spec-scope` is not in the ladder.** It is a pre-spec on-ramp that writes
 `BREAKDOWN.md` at the project root, carries no `status:` frontmatter, and is the user's
@@ -253,39 +278,60 @@ to enter `tiny-spec-build` in a stop-before-build run.**
 ## Step 4 — build-through only: build and merge
 
 Reached only when Step 0 fixed the stop point at build-through and the ladder is at L6
-(or L7 with an unmerged branch). For the first story that isn't already built and merged:
-
-1. **Branch.** `git switch <slug>` if it already exists; otherwise
-   `git switch -c <slug> <integration>` — cut **fresh from the integration branch** so
-   this story sees every story merged before it. That is what makes an ordered list
-   build correctly: story 3 gets stories 1 and 2 already in its tree.
-
-2. **Ladder.** Walk Steps 1–3 for this story until it reaches L6. If it stops anywhere
-   else, that is a halt — report and stop the whole run. **Never walk the ladder twice
-   to push past its own stop:** each of those is a human decision it deliberately
-   declined to make, and running it again declines again.
-
-3. **Build.** Invoke **`tiny-spec-build`**, once, briefed to run it through. It owns the
-   per-task loop and writes its own halt record. Anything other than `done` halts the
-   whole run — **do not merge a story that didn't finish**, and do not invoke build a
-   second time: it resumes from the checkbox state, so it lands on the very task that
-   just halted and halts there again.
-
-4. **Merge — only on `done`.** In order:
+(or L7 with an unmerged branch). Work **one batch at a time**, in batch order. For every
+story in the current batch that isn't already built and merged:
+
+1. **Lane.** Give each story its own **git worktree**, so lanes cannot collide on the
+   filesystem: `git worktree add ../<repo>-<slug> -b <slug> <integration>`, or
+   `git worktree add ../<repo>-<slug> <slug>` when the branch already exists. Cut **fresh
+   from the integration branch** so the story sees every story merged before it — that is
+   what makes an ordered backlog build correctly, and it is why batches merge before the
+   next one starts.
+
+   With a single lane you may stay in the main checkout and `git switch` as before; a
+   worktree is only required when a batch has more than one story.
+
+2. **Ladder.** Walk Steps 1–3 for each story, in its own worktree, until it reaches L6.
+   A story that stops anywhere else does **not** enter the build — its lane is halted;
+   see the halt rule below. **Never walk the ladder twice to push past its own stop:**
+   each of those is a human decision it deliberately declined to make, and running it
+   again declines again.
+
+3. **Build.** Invoke **`tiny-spec-build`** **once for the whole batch**, briefed to run
+   through, and hand it every live lane as a `(worktree path, slug)` pair. It owns the
+   per-task loop, runs the lanes concurrently, and writes each story's halt record.
+   Do not invoke it a second time for a lane that halted: it resumes from the checkbox
+   state, so it lands on the very task that just halted and halts there again.
+
+4. **Merge — only the lanes that returned `done`, one at a time, in batch order.**
+   For each, in the main checkout:
    - `git switch <integration>`
    - `git merge --no-ff <slug>` — the merge commit keeps each story legible in history.
-   - **Conflict** → `git merge --abort`, then halt `conflict`.
-   - **Run the constitution's Verification commands on the merged result**, exercised
-     the way a user would. A story that was green alone can still break against work
-     merged before it, and that is exactly what this catches. Red → halt `blocked`.
+   - **Conflict** → `git merge --abort`, halt that story `conflict`, and carry on with
+     the rest of the batch. Report every conflicted story at the end.
+   - **Run the constitution's Verification commands on the merged result**, exercised the
+     way a user would. Red → halt `blocked`. **This check is load-bearing under
+     parallelism and is never skipped:** every lane gated against a tree that did not
+     contain its siblings, so the merged result is the first time they meet.
    - **Never push.** Merging locally keeps a bad run one `git reset` away; sending it to
      a remote is the user's call, and this suite makes no network calls.
 
-5. **Next story.** Return to Step 1. Do not re-run Step 0.
+5. **Next batch.** If **every** lane in this batch merged cleanly, return to Step 1 for
+   the next batch. Do not re-run Step 0. **If any lane halted, stop the run here** — a
+   later batch may well depend on the story that failed, and working out which stories
+   are still safe is exactly the machinery this suite refuses to grow. Report and let the
+   user decide.
+
+6. **Leave the worktrees.** Do **not** run `git worktree remove`. Cleanup is the user's,
+   for the same reason branch deletion is — a halted lane's worktree holds the tree they
+   need to look at. List every path you created in the closing report, with the
+   `git worktree remove` commands, and let them run it.
 
-**A halt stops the whole run**, not just the current story. Later stories in a list
-written top to bottom usually assume the earlier ones landed, so skipping ahead past a
-failure produces a second, more confusing failure downstream.
+**A halt stops the lane it happened in, and ends the run at the end of that batch.**
+Within a batch the other lanes run to completion: the stories were declared independent,
+so stopping the ones that are working buys nothing and throws away finished work. Across
+batches the old rule stands unchanged — later stories usually assume earlier ones landed,
+so never skip ahead past a failure.
 
 `tiny-spec-build` records its own halts (`blocked`, `exhausted`, `fork`) in the story's
 `decisions.md`. **You record nothing** — the merge-stage halts are already legible
@@ -309,11 +355,15 @@ L3 or on a bound, say exactly what stopped you and what the user needs to decide
 **Build-through.** Name, in this order:
 
 1. **The terminal state** — exactly one of `done`, `blocked`, `exhausted`, `paused`,
-   `fork`, `conflict`. Use the word.
-2. **Stories built and merged**, in order, with their merge commits.
-3. **The story it stopped on**, the task within it, and why in one line.
+   `fork`, `conflict`. Use the word. With more than one lane, report **each story's own
+   state**, and give the run's state as the **worst** of them: four green lanes and one
+   `blocked` is a `blocked` run, never a `done` one with a footnote.
+2. **Stories built and merged**, in batch order, with their merge commits.
+3. **The story or stories it stopped on**, the task within each, and why in one line.
 4. **Stories never started** — say how many are left, by name.
-5. **The one command that resolves it** — `tiny-spec-create`/`tiny-spec-plan` in update
+5. **Worktrees left on disk**, with the `git worktree remove` command for each. You do
+   not run them.
+6. **The one command that resolves it** — `tiny-spec-create`/`tiny-spec-plan` in update
    mode for `blocked`/`exhausted`, this skill again for `paused`, the decision the user
    owes you for a `fork`, or the conflicted paths for a `conflict`.
 
@@ -338,9 +388,11 @@ ticket that legitimately has no visual surface.
 - **Never write, edit, or flip anything.** No `status:`, no checkbox, no `decisions.md`
   entry, no code, no `BREAKDOWN.md` edit. Delegate or stop. A router that regenerates
   documents is a second source of truth.
-- **Never push, force, rebase, reset, or delete a branch.** The only git commands this
-  skill issues are `switch`, `switch -c`, `merge --no-ff`, `merge --abort`, and
-  read-only queries. Everything outward-facing or destructive is the user's.
+- **Never push, force, rebase, reset, delete a branch, or remove a worktree.** The only
+  git commands this skill issues are `switch`, `switch -c`, `merge --no-ff`,
+  `merge --abort`, `worktree add`, `worktree list`, and read-only queries. Everything
+  outward-facing or destructive stays the user's — `worktree remove` included, which is
+  why Step 4 hands those commands over instead of running them.
 - **Never merge a story whose build didn't return `done`.**
 - **Never invoke `tiny-spec-run`.** Re-entering means re-reading these steps, not
   calling yourself. Self-invocation compounds context and does not terminate.

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/tiny-spec-scope/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-scope
-description: The greenfield on-ramp — turn a rough idea, or an existing PRD, into BREAKDOWN.md at the project root - a flat list of Features → user Stories, each with draft acceptance criteria and a slug, plus a shared Decisions block. The one skill that works from a blank page. Does not scaffold .spec/ or touch the constitution — tiny-spec-create reads BREAKDOWN.md in seeded mode and does that. For an existing codebase use tiny-spec-adopt instead. The suite works without either.
+description: The greenfield on-ramp — turn a rough idea, or an existing PRD, into BREAKDOWN.md at the project root - a flat list of Features → user Stories, each with draft acceptance criteria, a slug, and an optional needs: naming the stories it must follow, plus a shared Decisions block. The one skill that works from a blank page. Does not scaffold .spec/ or touch the constitution — tiny-spec-create reads BREAKDOWN.md in seeded mode and does that. For an existing codebase use tiny-spec-adopt instead. The suite works without either.
 ---
 
 # tiny-spec-scope
@@ -135,6 +135,7 @@ Write `BREAKDOWN.md` at the **project root** (the user's cwd) with the structure
 - Story: <one user-observable capability>     slug: <ado-__ | kebab>
   - AC: <a single user-observable, testable outcome — becomes REQ-1 in this story's SPEC.md>
   - AC: <another — keep each atomic; no "and" hiding two capabilities>
+  - needs: <slug, slug>   <!-- optional; stories this one must be built after. Omit when independent. -->
   - design: <path(s) to the wireframe(s) covering this story — omit if it has no visual surface>
 - Story: <one user-observable capability>     slug: <ado-__ | kebab>
   - AC: <…>
@@ -171,6 +172,24 @@ story it belongs to, so `tiny-spec-design` knows which files to open for that sp
 instead of re-deriving the mapping from filenames. A wireframe covering several stories
 is listed on each of them.
 
+**`needs:` is what lets stories build in parallel — so keep it honest and keep it rare.**
+It names the stories this one must be built *after*. `tiny-spec-run` uses it to group the
+backlog into batches: stories with no unmet `needs:` build concurrently, each in its own
+git worktree, and the next batch starts once they merge. Three rules:
+
+- **Name a story only for a real code dependency** — this story reads or edits files that
+  one writes, or builds on a schema, API, or type it introduces. A shared theme, a shared
+  `## Feature:` heading, or "it feels like it comes second" is **not** a dependency.
+- **When unsure, omit it.** The two errors are not symmetric. A `needs:` you didn't need
+  costs parallelism on every future run of this backlog, silently and forever. A `needs:`
+  you missed costs one merge conflict, which `tiny-spec-run` already detects and halts on.
+- **Never point across a cycle.** If two stories each need the other, they are one story —
+  merge them, or split the shared part out into a third that both need.
+
+A `## Feature:` heading carries no `needs:` — it is a grouping, not a work item. Most
+backlogs need the field on a minority of stories; a `needs:` on nearly every story means
+the carve is really a sequence, and you should say so rather than encode it here.
+
 **Slugs** mirror `tiny-spec-create`: derive from the platform key when bound — ADO
 `AB#77`→`ado-77`, GitHub `#42`→`gh-42`, Monday item→`monday-<id>`, Jira `PROJ-123`
 verbatim; **ad-hoc** → a short kebab-case slug (`email-login`). The tracker id is

{tiny_spec-1.0.1 → tiny_spec-1.2.0}/tiny_spec/__init__.py

@@ -5,4 +5,4 @@ into your Claude Code config directory (``~/.claude/`` by default). It adds no
 runtime behavior to the suite itself.
 """
 
-__version__ = "1.0.1"
+__version__ = "1.2.0"