task-pipeline-skill 0.17.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,166 @@
 # Changelog
 
+## 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