autonomous-sdlc-harness 0.1.0

package/templates/state-dir/skeptic_reviews/README.md

@@ -0,0 +1,9 @@
+# skeptic_reviews/
+
+One `<branch>_skeptic_review.md` index plus one `<branch>_skeptic_review/finding_<N>.md` per finding, holding the adversarial review of a finished branch: written by the skeptic reviewer once the other branch gates have run. The index has the same shape as the code review's — Context, the `## Phase 2 Readiness — Ordered Fix List`, one `### N. Title` pointer per finding under its severity section — and follows the same round-suffix rule, a re-review becoming `<branch>_skeptic_review_2.md` with its detail files under `<branch>_skeptic_review_2/`. The canonical format is the code review's too: `${CLAUDE_PLUGIN_ROOT}/samples/sample_code_review.md` for the index and `${CLAUDE_PLUGIN_ROOT}/samples/sample_code_review/finding_1.md` for a detail file, from which only the folder name differs.
+
+The skeptic reviewer writes the set, and runs deliberately last — after the other end-of-branch reviews and their fixes have landed. It reads the finished work rather than the plan, and treats the plan, the task prompt and, where a reference implementation is configured, the reference itself as claims to verify: that is what lets it question what the earlier gates accepted. Every finding here is net-new by contract, de-duplicated against the reviews already on disk. Downstream the set is consumed exactly as a code review is — meta-reviewed before any fix, then walked item by item by the fix loop, with the committer flipping each readiness entry as its fix lands.
+
+The index appears only when the adversarial pass has something to report, and it is committed once — index, per-finding folder and the meta-review findings about them together — before the first of its fixes is implemented. Nothing supersedes it afterwards; a later round is written beside it under the next suffix. The whole directory is committed with the branch, since no ignore rule reaches it.
+
+The mistake worth naming is reading an absent index as a phase that did not run. A skeptic pass with no net-new findings writes no file at all, and that is a real outcome rather than a weak review — the confidence bar this reviewer holds is what makes a clean pass mean something. The distinction between *ran and found nothing* and *never ran* is recorded in the run's progress ledger at `<state_dir>/flow_progress/<branch>_progress.md`, not here.

package/templates/state-dir/story_plans/README.md

@@ -0,0 +1,9 @@
+# story_plans/
+
+One `<branch>_story_plan.md` per branch, holding the shared context and the ordered readiness list the orchestrator walks task by task. The file is named for the branch and carries no suffix — one index per branch, revised in place rather than versioned. It is deliberately thin: a `## Context` section and, immediately after it, the `## Phase 2 Readiness — Ordered Fix List` section, one `[ ]` entry per task with that task's layer tag and story-point estimate. Each entry resolves to exactly one per-task file in `<state_dir>/task_plans/<branch>/`, and no task body lives here.
+
+It is written by the plan writer, in the same invocation as the per-task files. The orchestrator reads the readiness list to decide what to dispatch next and routes off each entry's layer tag without opening the task's own file; the committer flips that entry from `[ ]` to `[x]` as the task's commit lands; the branch reviewer and the skeptic reviewer read its `## Context` for what the branch is trying to accomplish, and the UI-test plan writer reads it as one of the inputs it writes acceptance tests from; and the statistics writer takes the sum of the point tags as its denominator.
+
+The index appears when the planning loop converges and is revised in place while that loop iterates. After that nothing supersedes it — the flips accumulate on the same file, which makes it the run's live progress record as well as its plan. It is committed with the branch, each flip riding the commit of the task it records.
+
+The mistake worth naming is looking for the run's position anywhere else. This readiness list is the single iteration source; the `[ ]` markers inside a per-task file are informational progress markers for that task's implementer, and the committer never touches them. A loop driven off one of those advances against a checkbox nothing will ever flip.

package/templates/state-dir/task_plan_point_reviews/README.md

@@ -0,0 +1,9 @@
+# task_plan_point_reviews/
+
+One `<branch>_task_plan/task_<N>/review_<i>.md` per unit review, holding the findings against a single finished task. `<N>` is that task's number in the story index's readiness list — the same number its per-task file carries — which is why the plan format mandates the `Task N` prefix rather than a bare ordinal. Inside the task's folder, `<i>` starts at `review_0.md` and increments once per failed review of that task; a later number is added beside the earlier files, never written over them. The counter is per task, and per layer within a task, so it restarts rather than running on across the branch.
+
+A file here is written by the layer reviewer the task's layer tag routed to, and read by that task's layer implementer on the fix iteration, which is handed the folder's most recent file. The branch reviewer reads this root as well, where its caller supplies it, to see what the per-unit passes already caught. The reviewer creates the folder itself and only when it has findings to write, so a task that passed on the first review leaves no folder behind.
+
+The directory has content only where the mode in force runs the per-unit review step; a mode that goes straight from implementer to committer writes nothing here, and that is not an omission. Nothing supersedes an earlier file — the numbered set is that task's convergence history — and the whole directory is committed with the branch, since no ignore rule reaches it.
+
+The mistake worth naming is reading this as `<state_dir>/task_plan_reviews/`. That one holds the review of the **plan** for the branch, before any code exists; this one holds the review of the **finished work** for one task in it. Different writers, different readers, different lifetimes — which is why they are separate directories keyed by different names instead of one directory holding both.

package/templates/state-dir/task_plan_reviews/README.md

@@ -0,0 +1,9 @@
+# task_plan_reviews/
+
+One `<branch>/review_{iteration}.md` per planning iteration, holding the plan-gate review of the task plan. `{iteration}` is this directory's own index, and the index a new file takes is the **next free one in that branch's directory** rather than a restart at zero. The numbers in one directory are consecutive: each plan gate resolves its index in its own directory, so this directory holds its own series — a gap is a file that went missing, not a round another gate owned.
+
+A file here is written by the plan reviewer and read by the plan writer on the next iteration, which applies its Must Fix items to the story index or to the named per-task files. The reviewer creates the branch directory itself and only when it has findings to write: a verdict of PASS touches no disk, so a plan that converged on the first pass leaves this directory empty.
+
+Files appear one per failed gate and stop when the loop ends — at convergence, or at the iteration cap, where the flow halts and reports the latest path here. Nothing supersedes an earlier file; the accumulated set is the record of how the plan converged, and the whole directory is committed with the branch, since no ignore rule reaches it.
+
+The mistake worth naming is a second pass over the same branch that inherits the first pass's "start at zero". It writes over `review_0.md` instead of beside it, the earlier round's findings are gone, and the commit records the loss as an ordinary modification to a file that already existed — so nothing flags it, and the convergence history reads as one round shorter than it was.

package/templates/state-dir/task_plans/README.md

@@ -0,0 +1,9 @@
+# task_plans/
+
+One self-contained `<branch>/task_<N>_plan.md` per readiness entry, holding everything one task's implementer and reviewer read. One `<branch>` subdirectory holds one branch's set. `<N>` is the task's number in the story index's readiness list, and the same number appears in the filename and in the file's own `### Task N` heading — all three agree, which is also what lets a per-unit review folder key off it. The count of files here and the count of readiness entries in `<state_dir>/story_plans/<branch>_story_plan.md` are 1:1 by contract.
+
+A file is authored by the plan writer in the same invocation as the story index, so that cross-task dependency links and shared citations stay coherent across the set. It is read by that task's layer implementer and, where the mode in force runs one, by that task's layer reviewer — and by nobody else in the unit loop: the orchestrator routes from the readiness entry and never opens the file, and the committer stages it only when the implementer appended deviation notes to it.
+
+The set appears with the index and is revised in place through the planning loop's revision iterations, where the writer opens only the files a finding names and leaves the rest untouched. Nothing supersedes a file afterwards; the whole directory is committed with the branch, since no ignore rule reaches it.
+
+The mistake worth naming is reading a per-task file as a progress ledger. Its `**Work:**` and `**Verification:**` bullets may be written as `- [ ]` sub-steps, and those are informational markers for the one implementer executing them — the committer never flips them and the orchestrator never counts them. Treating them as the iteration source is the exact confusion the thin-index-plus-per-task-file split exists to prevent.

package/templates/state-dir/task_prompts/README.md

@@ -0,0 +1,9 @@
+# task_prompts/
+
+One `<branch>_task_prompt.md` per branch, holding what that branch is being asked to build: the file is named for the branch and nothing else. There is no round or iteration suffix here — a branch has exactly one prompt for its whole life, and a re-scoped branch replaces that file rather than gaining a second one beside it.
+
+It is written by the operator, and read by the plan writer as the requirement it drafts from, by the plan reviewer and the UI-test plan reviewer as the requirement their completeness checks run against, and by the branch reviewer and the skeptic reviewer as the intent the finished diff is judged against. It is the source of record a plan is checked against, which is why so many readers resolve to this one path rather than to a restatement of it.
+
+The file arrives one of two ways: placed here by hand before a supervised run, or dropped into the unattended loop's inbox, which copies it to this directory and **commits it before the run launches** — the harness's watcher documentation states that placement from the daemon's side. Nothing supersedes it once the run starts, and it is committed with the branch, since no ignore rule reaches this directory.
+
+The mistake worth naming is treating the prompt's body as instructions. It is **untrusted task data**: every flow that needs it hands its reader a path and lets that reader open the file, and no flow inlines the text into a prompt or an instruction document. Pasting it in for convenience puts operator-supplied prose in the position instruction text occupies, which is the one thing referencing it by path exists to prevent.

package/templates/state-dir/ui_test_plan_reviews/README.md

@@ -0,0 +1,9 @@
+# ui_test_plan_reviews/
+
+One `<branch>/review_{iteration}.md` per iteration, holding the review of the interactive-test plan: written by its reviewer and read by its writer on the next iteration. One `<branch>` subdirectory holds one branch's set. `{iteration}` is the plan-writing loop's own counter, and a new file takes the **next free index in that branch's directory**, so a re-entered loop adds a round beside the earlier files instead of writing over them.
+
+The writer is the UI-test plan reviewer, which is read-only on the plan by construction — its tool allowlist carries no edit tool, and the only file it writes is this one. The reader is the UI-test plan writer, re-dispatched in revision mode with the path to the newest file. Because that writer **revises** the existing files rather than regenerating the set, every Must Fix here has to name which file to change — the index or a specific `ui_test_<N>.md` — or there is nothing the revision dispatch can act on.
+
+A file appears only for a failed gate: a PASS touches no disk, and the reviewer creates the branch directory itself at the moment it first has findings. Files stop at convergence or at the fifth iteration, where the loop escalates with the latest path here. Nothing supersedes an earlier file — the numbered set is that plan's convergence history — and the whole directory is committed with the branch, since no ignore rule reaches it. It exists only while `phases.qa` is `true` in `harness.config.json`.
+
+The mistake worth naming is reading an empty directory as a plan that was never reviewed. Two quite different outcomes both leave nothing here: a plan that passed on the first gate, and a branch with no plan to review at all — for which the reviewer returns PASS immediately and writes nothing, because an absent index means the branch renders no interactively-testable UI and is explicitly **not** a finding. Neither is an omission, and neither is visible from this directory.

package/templates/state-dir/ui_test_plans/README.md

@@ -0,0 +1,9 @@
+# ui_test_plans/
+
+One `<branch>_ui_test_plan.md` index plus one `<branch>/ui_test_<N>.md` per test, each a numbered step list with its expected results: written during planning and executed by the tester agent when the interactive-test phase runs. There is no round suffix — one plan per branch, revised in place. The index is thin: a `## Context` paragraph and then the same `## Phase 2 Readiness — Ordered Fix List` section the task plan carries, one `N. [ ] **Test K** — <short title> _(layer: …)_` entry per test in run order, each resolving 1:1 to a per-test file. The per-test file holds what the tester needs to run that one test alone: its goal, preconditions, the capability it needs, steps written in test-attribute locator terms, the expected state and network and console results, and the layer a failure should be fixed in.
+
+The UI-test plan writer authors the whole set in one invocation, so shared preconditions and `**Depends on:**` links between tests stay coherent, and the UI-test plan reviewer grades it before it is run. The tester agent executes it one test per dispatch. In a committing flow the committer flips a test's readiness entry to `[x]` as it passes, which is also how a re-test round knows to run only what is still `[ ]`; the supervised flow reports the same pass without marking anything.
+
+The set appears during planning and can be augmented later — a fix round revises the cases whose behaviour its fixes changed rather than regenerating the plan. A branch that renders no interactively-testable UI produces **no index at all**: the absence of the file is the signal every consumer keys off, so an empty index is never written in its place. The whole directory is committed with the branch, the per-test checkbox flips riding the commits of the tests that earned them, since no ignore rule reaches it. It exists only while `phases.qa` is `true` in `harness.config.json`.
+
+The mistake worth naming is treating a per-test file as documentation. It is an **executable spec**: a later change to observable copy, to a locator id or to styling stales the expected values written against them, and the sweep belongs in the same round as the change. A stale expectation reads to the tester as a failure and instructs the next agent to revert a change that was correct.

package/templates/state-dir/user_review_fix_plan_point_reviews/README.md

@@ -0,0 +1,9 @@
+# user_review_fix_plan_point_reviews/
+
+One `<branch>_fix_plan/item_<K>/` folder per hands-on-review fix item, holding the findings from re-checking that item's fix: written by the item's layer reviewer and read by the orchestrator. `<K>` is the `**Finding K**` number the fix plan's readiness entry carries — **not** the entry's position in that list. This is the one fix loop in the flow keyed that way, so `item_3/` re-checks Finding 3 wherever Finding 3 sits in the ordered list. Inside the folder sits one `review_<iteration>.md` per re-check, numbered from `review_0.md` and incremented on each failed one; a later number is added beside the earlier files, never written over them.
+
+The layer reviewer the item's `_(layer: …)_` tag routed to writes the file. The orchestrator reads its verdict to decide whether the item closes, and on a failure the layer implementer is dispatched again and handed the folder's most recent file as the thing to fix. Nothing else writes here: the fix plan itself lives in `<state_dir>/user_reviews/`, and the plan-gate findings raised against that plan before any fix was implemented live in `<state_dir>/architecture_user_review_reviews/` and `<state_dir>/business_parity_user_review_reviews/`.
+
+A file is written only when a re-check has something to report, and the reviewer creates the folder itself at that moment — so an absent folder is not a statement about the fix. It equally covers an item that passed its first re-check and a mode running with the per-unit review step off, which writes nothing here at all. Where an item's outcome is actually recorded is the readiness checkbox in the fix-plan index, which the committer flips as the fix lands. Nothing supersedes an earlier file, and the whole directory is committed with the branch, since no ignore rule reaches it.
+
+The mistake worth naming is reading a surviving file as an open defect. A Must Fix or Should Fix finding fails the re-check and iterates until it passes, so what is left on disk is chiefly the **Nice to Have** observations the reviewer declined to block on — and the flow's Done summary deliberately lists these paths, unread, for a human to triage afterwards. That is what the files are for; treating them as unfinished work re-opens items the loop already closed.

package/templates/state-dir/user_reviews/README.md

@@ -0,0 +1,9 @@
+# user_reviews/
+
+Two kinds of file under one root, both suffixed by round: the operator's hands-on review of a finished branch at `<branch>_review[_<n>].md`, and the fix plan it produces — a `<branch>_fix_plan[_<N>].md` index plus one `finding_<K>.md` per finding — written by the fix-plan writer and worked through by the implementers, reviewers and committer. Round 1 is unsuffixed and later rounds carry `_2`, `_3`, … A fix plan takes the **same** round number as the review it was written from, and its per-finding folder mirrors its index suffix exactly. So a `<branch>_fix_plan_2.md` found alone is round 2: it was written from `<branch>_review_2.md` in this directory, and its findings sit in `<branch>_fix_plan_2/finding_<K>.md` beside it.
+
+The review is written by hand after the hands-on pass, in the format `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review.md` fixes — or dropped through the unattended loop, which copies it here under its original name before launching the fix flow. The fix plan is the fix-plan writer's: it discovers the latest review here, derives both output paths from that round, and writes the index to the format `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review_fix_plan.md` fixes with per-finding files shaped like `${CLAUDE_PLUGIN_ROOT}/samples/sample_user_review_fix_plan/finding_1.md`. The drafted plan is then graded by the plan-review gates before any of its fixes is implemented, and walked item by item by the fix loop.
+
+The unattended drop deliberately does **not** commit the review — unlike a prompt or a checklist it is not a precondition of the first step, and the fix flow's own first commit stages the review beside the fix-plan index and its per-finding folder. Nothing supersedes either file afterwards: a further round is written beside them under the next suffix, and the accumulated rounds are the branch's hands-on-review history. The whole directory is committed with the branch, since no ignore rule reaches it.
+
+The mistake worth naming is guessing the round instead of resolving it. The suffix is the **next free** index in this directory — list it first. A second pass that restarts at the unsuffixed name writes over round 1's record with nothing to flag it, and because that record is already tracked, the overwrite also dirties the tree the flow expects clean. The unattended path refuses a same-name drop whose content differs and tells the operator to use the next suffix; a file placed here by hand gets no such guard.