task-pipeline-skill 0.17.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,249 @@
 # Changelog
 
+## v1.1.0 — 2026-07-29
+
+**The pipeline could find a requirement that was named and lost. It could not find
+one that was never named.** Every gate compares two things — and a contradiction has
+two sides while **an absence has one**. Nothing in a diff between spec and plan
+reveals the error path nobody specified, the entity nobody gave an owner, the
+failure mode nobody thought of. This release adds the pass that can.
+
+### Added
+- **`references/audit.md` — the audit ladder, cross-cutting.** Eight rungs of one
+  deliverable (requirement → decision → spec section → contract **and its failure
+  behavior** → plan task → change → **executed** test → surface/docs) and, more
+  importantly, the **seam between each pair**, each with its own question: did the
+  decision reach the spec; does the section say what happens when the contract
+  fails; does every contract have a task (stage 4's set-equality covers REQ→task and
+  nothing covers contract→task); did the DoD land in the diff; would this test still
+  pass with the production code deleted; can a user reach it and does a doc say so;
+  and finally — does what shipped satisfy the requirement's own *statement* rather
+  than the task's instructions.
+- **Stage 10 now opens with the ladder walk, before the coverage table.** An absence
+  found there becomes a **new REQ row with its check**, and *then* the table is
+  written. Appending after the table is exactly how acceptance goes green over a
+  gap. Findings that belong to a lower layer go back to that layer (spec → stage 3,
+  plan → stage 4) instead of being patched in place at the last stage.
+- **Findings are ordered by seam, never by file.** A file-ordered list reads as
+  noise; a seam-ordered one names *which layer of your own process is leaking*,
+  which is the part worth knowing.
+- **Bottom-up, and that is not taste.** A missing artefact low on the ladder makes
+  everything above it meaningless — top-down you spend the pass polishing a surface
+  for a contract that does not exist. Bottom-up, the absence is finding #1 and the
+  six findings above it collapse into it.
+
+### Added — three rules that stop the audit becoming another loop
+- **Every pass changes the axis, not the effort.** A searching loop does not
+  oscillate the way an editing loop does — it **converges**, because each pass edits
+  the corpus the next pass reads, so the newest edits are always the
+  least-reviewed text present and are what the next pass finds. Measured over seven
+  passes on a production repository: by pass six, ten of thirteen findings were
+  caused by pass five's own fixes, while the raw count still looked healthy. So the
+  doctrine requires **two counts per pass** — new findings, and self-inflicted ones —
+  and names the crossover as the signal to **rotate the axis**: seams down one
+  deliverable, then invariants across deliverables, then one class swept end to end.
+- **A class that repeats twice becomes a gate, not a note.** Once is an incident;
+  twice is a category, and a category belongs in the host's lint or CI where nobody
+  has to remember it. Writing the third instance into the ledger is how a
+  mechanical defect class becomes permanent. Wired into the stage-5 fix loop too.
+- **What can't be fixed now becomes a ratchet, never a TODO.** The carry-over ledger
+  is now defined as a *named, counted set that may only shrink, printed beside every
+  gate verdict* — `carry-over: 4 open (was 6) · unresolved: 0`. A TODO is invisible
+  until somebody opens the file; a ratchet sits next to the word `PASS` on every
+  run, so **"green" never reads as "verified"** — it reads as *"green, and here is
+  exactly what was not looked at"*. A ratchet that grew needs one sentence saying
+  why.
+
+### Added — the exit criterion that is usually skipped
+- **A green result from an unproven check is worth nothing.** A deliverable is not
+  audited when somebody has read it; it is audited when every rung has its artefact
+  **and every check being relied on has fired at least once against a planted
+  defect.** This is `tdd.md`'s iron law — *if you didn't watch it fail, you don't
+  know it tests the right thing* — raised from one test to every gate, linter and
+  script in the run, and it is now part of the stage-10 gate. Checks written under
+  pressure lie in ways that read as success: a predicate that inspects the wrong
+  shape, a probe that reads its own over-deletion as a pass, a regex that misses the
+  word it searches for. All three pass loudly.
+
+### Changed
+- `loop-guard.md` and `audit.md` now state their seam explicitly in both files: the
+  loop guard governs loops that **change** things and trips on oscillation; the
+  audit governs loops that **look** for things and trips on convergence. Different
+  failure, different exit, and an agent reading either one now learns when the other
+  applies.
+- `tdd.md` names the generalisation of its own iron law; `build.md`'s fix loop gains
+  the repeats-twice rule; `templates/carryover.md` documents the ratchet contract.
+
+### Validator
+- `references/audit.md` joins the built-in-doctrine set (must exist, must not be a
+  stub, must be reachable from `SKILL.md`).
+- The shipped acceptance gate must require the ladder walk **and** say that an
+  absence becomes a new REQ row — a config where stage 10 only compares the REQ list
+  now fails.
+- Both guards ship with CI negative self-tests, and both were proven the way this
+  release demands: defect planted, check watched failing, defect removed.
+
+## v1.0.0 — 2026-07-28
+
+**1.0.** Eighteen releases in ten days added a stage, a requirement spine, a
+decomposition pass and a loop guard; this one adds nothing and instead makes the
+whole thing coherent enough to depend on. Every file was read against every other
+file, the contradictions between them are fixed, and the repo now carries the
+surface a stranger needs before they trust it.
+
+What 1.0 promises: the stage flow (0 intake + 1→10), `pipeline.schema.json`, the
+artifact layout in `references/artifacts.md`, and the two install paths are stable.
+Breaking any of them means a 2.0.
+
+### Fixed — contradictions between doctrine files
+- **Two names for one idea.** `brainstorm.md` told the agent to split an oversized
+  task into "sub-projects", each with its own spec→plan→build cycle;
+  `decomposition.md` — the file that actually owns the procedure — calls them
+  **modules**, cuts them at the end of stage 2, and runs stages 3→10 per module
+  against a committed module map. An agent that read the first file ran a
+  decomposition the second file's gate could not check. Brainstorm now hands off to
+  `decomposition.md` by name.
+- **The same split, invented twice.** `planning.md` independently told stage 4 to
+  "split the spec into one plan per subsystem" — a second, unrecorded decomposition
+  two stages after the one with the gate and the map. A plan now covers exactly one
+  spec; a multi-subsystem spec arriving at stage 4 is a missed stage-2
+  decomposition and goes back there.
+- **A hardcoded `main`.** `build.md` and `review.md` both built the final
+  whole-branch review package with `git merge-base main HEAD`, in a pipeline whose
+  stage-0 brief records the base branch precisely because it is not always `main`.
+  On any repo with a `master`, a `develop` or a stacked base, the final review saw
+  the wrong diff. Both now read the brief's base.
+- **A five-status set that claimed to have four.** `acceptance.md` listed four
+  statuses, declared "there is no fifth status", then named `unknown` in the next
+  clause. Reworded so the mechanism is legible: four ways to close, and anything
+  that fits none of them is `unknown`, which fails the gate.
+- **A version pin on someone else's contract.** The README and `stages.md` both
+  pinned super-ux's scenario format at "ux-contract v4" — the exact cross-repo
+  version skew this project ported its own doctrine in-house to avoid. Both now
+  point at the contract super-ux itself ships, with no version named here.
+- **A blockquote where a sentence should be.** In `knowledge-sources.md` the
+  precedence chain `code > host docs and ADRs > the wiki > memory` wrapped so the
+  second line *began* with `>`, which Markdown renders as a block quote —
+  the rule about which source wins was visually broken in the file that defines it.
+- **`skills[]` entries that resolve to nothing.** `pipeline.example.json` names
+  `task-pipeline:grill` and `host:lint` beside real skills, with no key anywhere for
+  the two prefixes. A host copying the example had no way to tell a notional label
+  from an installable skill. The convention is now stated in the config and in
+  `SKILL.md`: `task-pipeline:<name>` is this skill's own `references/<name>.md`,
+  `host:<name>` is the host project's command per `conventions.md`, everything else
+  is a real skill. Stage 3 also gained the `/ux` entry point and `/ux-lint`, which
+  the doctrine mandates and the config had omitted.
+- **A repo tree that had drifted.** `references/artifacts.md`'s map of this
+  repository listed `templates/` outside the tree and missed several files.
+- A broken ordered list in the Cursor rule (`3a.` is not a list marker) and a
+  `references/` index in `SKILL.md` that never mentioned `templates/`.
+
+### Added — the open-source surface
+- `CONTRIBUTING.md` — dev setup, the repository layout, and **the nine invariants**
+  written out with the failure each one prevents: four-way version sync, the stage
+  list living on three machine-checked surfaces, every human-facing description
+  having to name the flow's final stage last, no hardcoded vendor model ids, no
+  unreachable reference file, no external provider in the default flow, stage 0 and
+  stage 10 staying manual, the frontmatter budget, and resolving links.
+- `SECURITY.md` — what the executable surface actually is (two installers, a
+  validator, two workflows), private reporting with a 72-hour acknowledgement, and
+  an explicit scope: doctrine that would lead an agent to exfiltrate secrets, push
+  to an unnamed repo or deploy without a go **is** a security bug here.
+- `CODE_OF_CONDUCT.md`, GitHub issue forms (bug / doctrine change, with routing to
+  super-ux and obsidian-wiki), and a pull-request template whose checklist is the
+  list of surfaces that drift.
+- `CLAUDE.md` — house rules for any agent working in this repo, which is also what
+  this pipeline's own stage-0 harvest reads first: the commands, the branch and
+  commit policy, the invariants, and the docs that must be updated in the same
+  change. The project now dogfoods the convention it asks of every host.
+- **Two validator guards, each with a CI negative self-test:** the open-source root
+  files must exist, and `npm test` must actually run the validator. A documented
+  check nobody can run is a check nobody runs.
+
+### Changed
+- **README rewritten.** Same substance, ordered so it can be read: a one-paragraph
+  statement of the problem, a Mermaid diagram of the flow with gate types coloured,
+  the gate table, *what you get*, then a quickstart — before the deep sections.
+  Configuration, install/update and a documentation map now live in their own
+  places instead of interleaved with doctrine.
+- Package, marketplace and plugin descriptions rewritten — shorter, and all three
+  now say the same thing about the same ten stages.
+- npm metadata: a `test` script (`npm test`), a `bugs` URL, `homepage` at the README.
+- `.worktrees/` is git-ignored — stage 5 creates them.
+
+> The open-source surface above shipped in v0.18.1, hours earlier the same day;
+> it is restated here because it is part of what 1.0 means.
+
+## v0.18.1 — 2026-07-28
+
+Open-source hygiene pass — the repo is public, so the files a first-time
+contributor looks for now exist, and the validator keeps them there.
+
+### Added
+- `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue forms and a
+  pull-request template.
+- `CLAUDE.md` — house rules for any agent working in this repo: the commands, the
+  branch and commit policy, and the invariants that drift most often.
+- The validator now requires the open-source root files, with a CI negative
+  self-test that deletes `CONTRIBUTING.md` and proves the check fails.
+
+### Changed
+- npm metadata: a `test` script, a `bugs` URL, and `homepage` pointing at the
+  README. Package, marketplace and plugin descriptions rewritten so all three say
+  the same thing about the ten stages.
+- `.worktrees/` is ignored — the pipeline creates them during stage 5.
+
+## v0.18.0 — 2026-07-28
+
+The grill stops opening cold. Stage 0 now reads what the project already knows
+about the task **before** the first question, checks every answer against it, and
+stage 9 updates the same list at the end — the loop the pipeline was missing.
+
+### Added
+- **Stage 0 phase 1: the knowledge harvest** (`references/knowledge-sources.md`).
+  Before question one, query what the project already knows about *this* task —
+  the code, `CLAUDE.md`/`AGENTS.md`, `CONTEXT.md` + `docs/adr/`, `docs/` and
+  `docs/ux/`, previous pipeline briefs and their carry-over ledgers, **the
+  knowledge wiki when one is installed**, and **any other repository or hosted doc
+  system the project names as its docs**. It is retrieval scoped by the task's own
+  nouns, not a read of everything: query, follow one hop, stop when the terms
+  return nothing new. Nothing is ever fetched on a guess — a doc repo is in scope
+  because the project names it.
+- **The source ledger** — a required `## Knowledge sources` section in the brief
+  (source, what it says about this task, freshness, authority, "stale after this
+  run?"). `none found` is a valid, useful row: it tells the next run the search
+  happened and came back empty. Silence doesn't.
+- **Answers are validated against the harvest** (`grill.md` → *Domain awareness*).
+  The cheap win is not re-asking what an ADR already answers. The one that matters:
+  **an answer nobody can check is a recollection** — people answer from memory
+  about systems they wrote a year ago, and a false premise adopted at stage 0 makes
+  every later gate pass honestly on it. So the grill quotes the source instead:
+  *"the March ADR says X, you just described Y — has it changed?"* The operator
+  **outranks every document, but only out loud** — an override quoted against its
+  source is a recorded decision, an unquoted one is an undetected divergence.
+  Precedence when sources disagree: **code > host docs/ADRs > wiki > memory.**
+- **obsidian-wiki is the recommended knowledge base**
+  (https://github.com/ar9av/obsidian-wiki — Karpathy's LLM-wiki pattern), detected
+  via `~/.obsidian-wiki/config` or a resolving `wiki-query`/`wiki-update`.
+  Installed → queried in the harvest, synced with `wiki-update` at stage 9. Absent
+  → the preflight prints `pip install obsidian-wiki` / `obsidian-wiki setup --vault
+  <path>` **once** and the run continues. A recommendation, never a gate; a project
+  whose `CLAUDE.md` names a different knowledge base wins.
+- **Stage 9 closes the loop:** the stage-0 ledger *is* its work list. Every source
+  the harvest read gets updated if this run changed or disproved it — including the
+  docs the grill already proved stale, which is why those conflicts are logged in
+  phase 2 instead of only being settled out loud. Docs living in **another
+  repository** are outward: propose the edit and get an explicit go, or carry it
+  over with the exact change written down. Never a direct push to a repo the task
+  didn't name.
+- **Autonomy-sweep row** for doc sources beyond this repo, and whether stage 9 may
+  write to them — decided at intake, like every other outward action.
+- **Three validator guards, each with a CI negative self-test:** the brief template
+  must keep its `## Knowledge sources` section; the stage-0 gate must require the
+  harvest *and* its ledger before the interview; the stage-9 gate must name that
+  ledger as its work list. A harvest with nowhere to land degrades silently back
+  into asking from memory, which is precisely the failure it exists to stop.
+
 ## v0.17.1 — 2026-07-28
 
 A full-repo consistency audit. v0.16.0 added a third review verdict and a tenth