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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiny-spec
-Version: 1.0.1
+Version: 1.1.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

{tiny_spec-1.0.1 → tiny_spec-1.1.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

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

@@ -24,7 +24,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 +67,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.1.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
 ---
 
@@ -17,6 +17,9 @@ back to `tiny-spec-build`; return data, not pleasantries.
 - 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 +35,26 @@ 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`.
+
+   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.
@@ -158,7 +177,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.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tiny-spec"
-version = "1.0.1"
+version = "1.1.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.1.0}/tiny-spec-build/SKILL.md

@@ -68,7 +68,11 @@ 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 **previous passed task's `CHANGES` list**, if there is one, labelled as what the
+  last task left behind. Every executor starts cold and re-derives the codebase; naming
+  the files that just moved is the cheapest way to cut that, and you already have the
+  list in hand. Paths only — not the previous task's description, findings, or report.
 
 Do **not** pass the plan, sibling tasks, or other chatter. It returns a structured
 report (`STATUS`, `CHANGES`, `DECISIONS`, `BLOCKER`). A `STATUS: blocked` →
@@ -80,11 +84,29 @@ Spawn one **`tiny-spec-build-reviewer`**, **blind to step 2**, with:
 - 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 +116,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
@@ -274,6 +300,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.1.0}/tiny-spec-plan/SKILL.md

@@ -138,25 +138,59 @@ 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.
+
+**Count is a smell, not a cap.** A story sized the way `tiny-spec-scope` describes
+usually lands in **3–6 tasks**. If you are past about eight, 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 +198,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 +249,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 +276,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.1.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.1.0"