tiny-spec 1.1.0__tar.gz → 2.0.0__tar.gz

{tiny_spec-1.1.0 → tiny_spec-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiny-spec
-Version: 1.1.0
+Version: 2.0.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
@@ -71,13 +71,13 @@ committed.
 That core is **three skills and two agents**. In front of it sit **two front doors** —
 pick the one that matches where you're starting. Over the top sits **one router**,
 `tiny-spec-run`, which drives the chain and, when you ask it to, works a whole list of
-stories through to merged code. No config file, no build step.
+features through to merged code. No config file, no build step.
 
 ```
    GREENFIELD                        BROWNFIELD
    starting from an idea             starting from a codebase
    tiny-spec-scope                   tiny-spec-adopt
-   idea → Features → Stories         real code → constitution
+   idea → Features                   real code → constitution
    BREAKDOWN.md                      constitution.md
             \                         /
              └───────────┬───────────┘
@@ -85,16 +85,16 @@ stories through to merged code. No config file, no build step.
    tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-build
    intent               design + tasks      per-task loop
    SPEC.md              PLAN.md             plan → implement
-                        tasks.md            → review → commit
+                        (+ ## Tasks)        → review → commit
 
    tiny-spec-run      one router. Walks the chain and stops before build —
-                      or, asked to, builds each story and merges it.
+                      or, asked to, builds each feature and merges it.
    tiny-spec-design   optional. Wireframes → tokens + gradeable screens.
 ```
 
 **Pick one front door, once per project.** Starting from an idea with no code yet? Run
 `tiny-spec-scope` — it interviews the idea into a `BREAKDOWN.md`, a flat list of
-Features → Stories with draft acceptance criteria. Working in a codebase that already
+well-defined Features with draft acceptance criteria. Working in a codebase that already
 exists? Run `tiny-spec-adopt` — it reads your repo and derives the constitution from
 what's actually there: your real lint and test commands, your real layout, your real
 conventions. Have a single known ticket in a project that's already set up? Skip both
@@ -110,7 +110,7 @@ receipt rather than the adjective:
 
 | | skills / commands | agents | config | artifacts per feature |
 |---|---|---|---|---|
-| **tiny-spec** | **7** (3 core + 1 router + 3 optional) | **2** | **none** | **`SPEC` `PLAN` `tasks`** |
+| **tiny-spec** | **7** (3 core + 1 router + 3 optional) | **2** | **none** | **`SPEC` `PLAN`** |
 | [GitHub Spec Kit](https://github.com/github/spec-kit) | 10 | — | `specify init` | `spec` `plan` `tasks` `checklist` `constitution` `research` `data-model` `contracts/` `quickstart` |
 | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | 12 | — | `.openspec.yaml` | `proposal` `design` `tasks` `specs/` |
 | [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) | 58 | 5 personas | 35 × `customize.toml` | `PRD` `architecture` `epics` `stories` `UX` `brief` `sprint-plan` |
@@ -197,7 +197,7 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/tiny-spec-scope     # starting from an idea: interview it into stories (BREAKDOWN.md)
+/tiny-spec-scope     # starting from an idea: interview it into features (BREAKDOWN.md)
 /tiny-spec-adopt     # starting from a codebase: derive the constitution from real code
 /tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
 /tiny-spec-plan      # design it, harden the constitution, slice the task list
@@ -219,10 +219,10 @@ forward. It writes nothing itself, it only delegates. By default it **stops befo
 Ask it to build and it goes all the way instead:
 
 ```
-/tiny-spec-run build the backlog     # per story: branch → plan → build → merge → next
+/tiny-spec-run build the backlog     # per feature: branch → plan → build → merge → next
 ```
 
-It reads your `BREAKDOWN.md` (or a list you paste) and works the stories one after
+It reads your `BREAKDOWN.md` (or a list you paste) and works the features one after
 another, merging each finished branch into `main` locally before starting the next —
 until it's done or reaches a **terminal state** it names out loud. See
 [Working a whole list](#working-a-whole-list). Which of the two it does is decided from
@@ -262,8 +262,8 @@ or install one set at a time.
 ### See a finished run first
 
 [`examples/todo-cli/`](examples/todo-cli/) is a real run of the flow on one small
-ticket, committed verbatim — the `TICKET.md` that went in, the `SPEC.md`, `PLAN.md`,
-`tasks.md` and `constitution.md` the suite wrote, and the code and tests it produced.
+ticket, committed verbatim — the `TICKET.md` that went in, the `SPEC.md`, `PLAN.md`
+and `constitution.md` the suite wrote, and the code and tests it produced.
 The tests pass; you can clone it and run the gate yourself.
 
 ## How it works
@@ -464,7 +464,7 @@ 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]
+    SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[PLAN.md ## Tasks<br/>checklist]
 
     TASKS -->|pause: set| H[Halt — paused<br/>task stays unchecked]
     TASKS --> P[Plan task]
@@ -498,17 +498,39 @@ 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 features and works them in batches.
+Per feature 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 feature sees the earlier ones already
+merged — which is what makes an ordered list build correctly.
 
-**The list is `BREAKDOWN.md` by default** — its `- Story:` entries, in file order,
+**Independent features build at the same time.** A feature 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 feature**, three at a time by default.
+The batch merges, then the next one starts.
+
+```
+## Feature: expose both helpers on a CLI     slug: cli
+
+- AC: `textkit slugify "Hi There"` prints "hi-there"
+- needs: slugify, wordwrap
+```
+
+Omit `needs:` when a feature 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 feature that isn't there, stops the run rather
+than being guessed past.
+
+**Tasks *inside* a feature never run in parallel.** They share files and each one assumes
+the last landed, so they stay strictly sequential. Parallelism is across features only.
+
+**The list is `BREAKDOWN.md` by default** — its `## Feature:` entries, in file order,
 each already carrying a `slug:` (the branch and directory name) and `AC:` lines. Paste
 a list at invocation instead and that wins; but a bare feature name has no acceptance
 criteria, so `tiny-spec-create` will interview you when it reaches it. That's the
@@ -518,22 +540,26 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 
 | | |
 |---|---|
-| `done` | every story built **and merged** |
+| `done` | every feature built **and merged** |
 | `blocked` | an upstream document is wrong — go fix the spec or the plan |
 | `exhausted` | a task stayed red past two fix attempts |
 | `paused` | it reached a `pause:` point |
 | `fork` | a real either/or the plan doesn't answer |
-| `conflict` | a story's branch wouldn't merge cleanly |
+| `conflict` | a feature's branch wouldn't merge cleanly |
 
-**Only `done` means the work is built** — and in a story run, that means *all* of them.
-Stopping at story 2 of 7 and reporting "done" is what autonomous loops get wrong most
+**Only `done` means the work is built** — and in a feature run, that means *all* of them.
+Stopping at feature 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 features
+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 feature'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
+**Pause points are technical, not per-feature.** Any task can carry a `pause:` line, and
 the build halts *before* running it:
 
 ```
@@ -545,20 +571,23 @@ the build halts *before* running it:
 `tiny-spec-plan` proposes these for genuinely irreversible work — migrations,
 destructive file operations, a new dependency, an auth boundary, a public API contract.
 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.
-
-**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
+auth") and it gets applied as each feature's tasks are sliced.
+
+**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 feature whose
+ticked `## Tasks` is on `main` is done, a `.spec/<slug>/` with an unchecked task is in
 progress, no directory means not started. Ask again tomorrow in a fresh session and it
 picks up where it stopped. No run-state file, no lock, no budget to configure — the
-story list *is* the budget.
+feature list *is* the budget.
 
 **It never fixes a blocker for you.** A blocker means one of your documents is wrong,
 and a run allowed to rewrite the requirement its own task just failed would be grading
@@ -583,7 +612,7 @@ It is namespaced per ticket, with a shared spine at the root:
   constitution.md           project-wide, shared across tickets
   memory.md                 operational lessons, shared across tickets
   <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)
-    SPEC.md  PLAN.md  tasks.md  decisions.md
+    SPEC.md  PLAN.md  decisions.md     (PLAN.md ends in the ## Tasks checklist)
 ```
 
 `BREAKDOWN.md` and `design/` sit at your project root rather than inside `.spec/`,

{tiny_spec-1.1.0 → tiny_spec-2.0.0}/README.md

@@ -34,13 +34,13 @@ committed.
 That core is **three skills and two agents**. In front of it sit **two front doors** —
 pick the one that matches where you're starting. Over the top sits **one router**,
 `tiny-spec-run`, which drives the chain and, when you ask it to, works a whole list of
-stories through to merged code. No config file, no build step.
+features through to merged code. No config file, no build step.
 
 ```
    GREENFIELD                        BROWNFIELD
    starting from an idea             starting from a codebase
    tiny-spec-scope                   tiny-spec-adopt
-   idea → Features → Stories         real code → constitution
+   idea → Features                   real code → constitution
    BREAKDOWN.md                      constitution.md
             \                         /
              └───────────┬───────────┘
@@ -48,16 +48,16 @@ stories through to merged code. No config file, no build step.
    tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-build
    intent               design + tasks      per-task loop
    SPEC.md              PLAN.md             plan → implement
-                        tasks.md            → review → commit
+                        (+ ## Tasks)        → review → commit
 
    tiny-spec-run      one router. Walks the chain and stops before build —
-                      or, asked to, builds each story and merges it.
+                      or, asked to, builds each feature and merges it.
    tiny-spec-design   optional. Wireframes → tokens + gradeable screens.
 ```
 
 **Pick one front door, once per project.** Starting from an idea with no code yet? Run
 `tiny-spec-scope` — it interviews the idea into a `BREAKDOWN.md`, a flat list of
-Features → Stories with draft acceptance criteria. Working in a codebase that already
+well-defined Features with draft acceptance criteria. Working in a codebase that already
 exists? Run `tiny-spec-adopt` — it reads your repo and derives the constitution from
 what's actually there: your real lint and test commands, your real layout, your real
 conventions. Have a single known ticket in a project that's already set up? Skip both
@@ -73,7 +73,7 @@ receipt rather than the adjective:
 
 | | skills / commands | agents | config | artifacts per feature |
 |---|---|---|---|---|
-| **tiny-spec** | **7** (3 core + 1 router + 3 optional) | **2** | **none** | **`SPEC` `PLAN` `tasks`** |
+| **tiny-spec** | **7** (3 core + 1 router + 3 optional) | **2** | **none** | **`SPEC` `PLAN`** |
 | [GitHub Spec Kit](https://github.com/github/spec-kit) | 10 | — | `specify init` | `spec` `plan` `tasks` `checklist` `constitution` `research` `data-model` `contracts/` `quickstart` |
 | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | 12 | — | `.openspec.yaml` | `proposal` `design` `tasks` `specs/` |
 | [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) | 58 | 5 personas | 35 × `customize.toml` | `PRD` `architecture` `epics` `stories` `UX` `brief` `sprint-plan` |
@@ -160,7 +160,7 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/tiny-spec-scope     # starting from an idea: interview it into stories (BREAKDOWN.md)
+/tiny-spec-scope     # starting from an idea: interview it into features (BREAKDOWN.md)
 /tiny-spec-adopt     # starting from a codebase: derive the constitution from real code
 /tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
 /tiny-spec-plan      # design it, harden the constitution, slice the task list
@@ -182,10 +182,10 @@ forward. It writes nothing itself, it only delegates. By default it **stops befo
 Ask it to build and it goes all the way instead:
 
 ```
-/tiny-spec-run build the backlog     # per story: branch → plan → build → merge → next
+/tiny-spec-run build the backlog     # per feature: branch → plan → build → merge → next
 ```
 
-It reads your `BREAKDOWN.md` (or a list you paste) and works the stories one after
+It reads your `BREAKDOWN.md` (or a list you paste) and works the features one after
 another, merging each finished branch into `main` locally before starting the next —
 until it's done or reaches a **terminal state** it names out loud. See
 [Working a whole list](#working-a-whole-list). Which of the two it does is decided from
@@ -225,8 +225,8 @@ or install one set at a time.
 ### See a finished run first
 
 [`examples/todo-cli/`](examples/todo-cli/) is a real run of the flow on one small
-ticket, committed verbatim — the `TICKET.md` that went in, the `SPEC.md`, `PLAN.md`,
-`tasks.md` and `constitution.md` the suite wrote, and the code and tests it produced.
+ticket, committed verbatim — the `TICKET.md` that went in, the `SPEC.md`, `PLAN.md`
+and `constitution.md` the suite wrote, and the code and tests it produced.
 The tests pass; you can clone it and run the gate yourself.
 
 ## How it works
@@ -427,7 +427,7 @@ 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]
+    SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[PLAN.md ## Tasks<br/>checklist]
 
     TASKS -->|pause: set| H[Halt — paused<br/>task stays unchecked]
     TASKS --> P[Plan task]
@@ -461,17 +461,39 @@ 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 features and works them in batches.
+Per feature 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 feature sees the earlier ones already
+merged — which is what makes an ordered list build correctly.
 
-**The list is `BREAKDOWN.md` by default** — its `- Story:` entries, in file order,
+**Independent features build at the same time.** A feature 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 feature**, three at a time by default.
+The batch merges, then the next one starts.
+
+```
+## Feature: expose both helpers on a CLI     slug: cli
+
+- AC: `textkit slugify "Hi There"` prints "hi-there"
+- needs: slugify, wordwrap
+```
+
+Omit `needs:` when a feature 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 feature that isn't there, stops the run rather
+than being guessed past.
+
+**Tasks *inside* a feature never run in parallel.** They share files and each one assumes
+the last landed, so they stay strictly sequential. Parallelism is across features only.
+
+**The list is `BREAKDOWN.md` by default** — its `## Feature:` entries, in file order,
 each already carrying a `slug:` (the branch and directory name) and `AC:` lines. Paste
 a list at invocation instead and that wins; but a bare feature name has no acceptance
 criteria, so `tiny-spec-create` will interview you when it reaches it. That's the
@@ -481,22 +503,26 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 
 | | |
 |---|---|
-| `done` | every story built **and merged** |
+| `done` | every feature built **and merged** |
 | `blocked` | an upstream document is wrong — go fix the spec or the plan |
 | `exhausted` | a task stayed red past two fix attempts |
 | `paused` | it reached a `pause:` point |
 | `fork` | a real either/or the plan doesn't answer |
-| `conflict` | a story's branch wouldn't merge cleanly |
+| `conflict` | a feature's branch wouldn't merge cleanly |
 
-**Only `done` means the work is built** — and in a story run, that means *all* of them.
-Stopping at story 2 of 7 and reporting "done" is what autonomous loops get wrong most
+**Only `done` means the work is built** — and in a feature run, that means *all* of them.
+Stopping at feature 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 features
+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 feature'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
+**Pause points are technical, not per-feature.** Any task can carry a `pause:` line, and
 the build halts *before* running it:
 
 ```
@@ -508,20 +534,23 @@ the build halts *before* running it:
 `tiny-spec-plan` proposes these for genuinely irreversible work — migrations,
 destructive file operations, a new dependency, an auth boundary, a public API contract.
 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.
-
-**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
+auth") and it gets applied as each feature's tasks are sliced.
+
+**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 feature whose
+ticked `## Tasks` is on `main` is done, a `.spec/<slug>/` with an unchecked task is in
 progress, no directory means not started. Ask again tomorrow in a fresh session and it
 picks up where it stopped. No run-state file, no lock, no budget to configure — the
-story list *is* the budget.
+feature list *is* the budget.
 
 **It never fixes a blocker for you.** A blocker means one of your documents is wrong,
 and a run allowed to rewrite the requirement its own task just failed would be grading
@@ -546,7 +575,7 @@ It is namespaced per ticket, with a shared spine at the root:
   constitution.md           project-wide, shared across tickets
   memory.md                 operational lessons, shared across tickets
   <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)
-    SPEC.md  PLAN.md  tasks.md  decisions.md
+    SPEC.md  PLAN.md  decisions.md     (PLAN.md ends in the ## Tasks checklist)
 ```
 
 `BREAKDOWN.md` and `design/` sit at your project root rather than inside `.spec/`,

{tiny_spec-1.1.0 → tiny_spec-2.0.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 features 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 feature 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,

{tiny_spec-1.1.0 → tiny_spec-2.0.0}/agents/tiny-spec-build-reviewer.md

@@ -13,6 +13,11 @@ 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 features at once. **Never read, write, or run a gate outside the
+  directory you were given**: a sibling worktree holds a different feature 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**
@@ -54,6 +59,18 @@ acceptance and the constitution — verified, not inferred?**
    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,
@@ -78,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
@@ -104,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:

{tiny_spec-1.1.0 → tiny_spec-2.0.0}/docs/eval/README.md

@@ -87,10 +87,10 @@ Each case runs in a throwaway sandbox seeded with `IDEA.md` and the vendored ski
 ### What gets measured
 
 - **structural conformance** (deterministic) — BREAKDOWN has Problem and
-  Goal & non-goals filled, a Decisions block, ≥1 Feature, Stories with a slug and ≥1 AC; the
+  Goal & non-goals filled, a Decisions block, ≥1 Feature, each with a slug and ≥1 AC; the
   planning skills left no `.spec/` behind.
 - **hand-off integrity** (LLM judge) — **coverage** (every PRD capability lands in ≥1
-  story, nothing dropped) and **no fabrication** (every story traces to a capability,
+  feature, nothing dropped) and **no fabrication** (every feature traces to a capability,
   nothing invented). These are the high-value signals; a case PASSes only if structural
   conformance holds *and* the judge confirms both.
 - **quality** (LLM judge, reported not gated) — atomicity / user-observable phrasing,

{tiny_spec-1.1.0 → tiny_spec-2.0.0}/examples/todo-cli/README.md

@@ -10,6 +10,9 @@ workflow generates before you run it on your own work.
 > retouched to match the current artifact formats — a doctored example would defeat
 > the point. Later versions add a `## Design` section to `SPEC.md` (unused here: this
 > is a CLI with no design surface) and richer status flags. The shape is the same.
+> One format move was applied after the fact: in 2.0 the checklist stopped being its
+> own `tasks.md` and became `PLAN.md`'s `## Tasks` section, so the original `tasks.md`
+> was moved there verbatim — same tasks, same ticks, no content edited.
 
 ## What's here
 
@@ -20,14 +23,13 @@ TICKET.md                     the input — a small "todo CLI" ask
                               definition of done, and the verification gate
   todo-cli/
     SPEC.md                   intent + REQ-1..REQ-9 (what "done" means)
-    PLAN.md                   the design and how each requirement is covered
-    tasks.md                  the ordered checklist, all ticked [x]
+    PLAN.md                   the design, how each requirement is covered, and
+                              the ordered ## Tasks checklist, all ticked [x]
 todo.py                       the produced CLI (stdlib only, 117 lines)
 test_todo.py                  the produced end-to-end test (129 lines)
 ```
 
-Read them in flow order: `TICKET.md` → `SPEC.md` → `PLAN.md` → `tasks.md` →
-`todo.py`. The `constitution.md` is the persistent context injected into every task.
+Read them in flow order: `TICKET.md` → `SPEC.md` → `PLAN.md` → `todo.py`. The `constitution.md` is the persistent context injected into every task.
 
 ## It passes its own gate
 

{tiny_spec-1.1.0 → tiny_spec-2.0.0}/pyproject.toml

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