task-pipeline-skill 1.98.0 → 1.99.1

package/CHANGELOG.md

@@ -1,3 +1,262 @@
+## v1.99.1 (2026-10-21)
+
+Guards: 530 → **530**; property checks 15 → **15**. No negative was added: the new cases
+are regression tests in `test/audit_regressions/diet_retro_budget.py`.
+
+**`retro_budget.py` reads an older retro's floor and migrates it** (B-149, from sshlg-skills
+B-244). That retro writes its standing instructions as a numbered list and its run stamps as
+`- **date: title** ...` narrative items beside a table. `check` printed `standing 0/10 rows`
+for ten instructions, and `migrate` answered `nothing to move` on a 103,737-byte floor with 89
+stamps, so stage 10's byte budget could never pass there.
+
+- `check` counts numbered-list standing instructions and list stamps, measures each item
+  whole and names it (`standing row #6`, `stamp 2026-09-06 (list)`).
+- `migrate` rotates the oldest stamps past the cap of ten, ordered by their date and never by
+  position, verbatim into the quarter's archive (a table row travels under its table's
+  header); keeps a long list item's bold rule and its `*(Retire ...)*` trigger and moves the
+  rest; keeps a long list stamp's bold title; and, only over budget, moves the Run stamps
+  section's loose prune paragraphs. Every move leaves a `sha256:` pointer that `verify` proves.
+- Edge rules from two review rounds: a lead of several bold spans stays whole and a date-only
+  lead refuses by name; a same-day tie follows its own block's direction; a paragraph holding
+  a heading stays in the floor; the script's own pointer notes never move again, so a floor
+  still over budget is left alone by the next run; a table's header leaves only with the rows
+  this run rotated; a list marker, a quote, a rule or a `*(` note ends an item; a rule still
+  over 600 characters after its story moved is reported, never moved again.
+- On a copy of the sshlg-skills retro: 103,737 bytes to 6,446, every pointer proved, no
+  non-blank line lost, the text outside the floor unchanged.
+- Tests: `test/audit_regressions/diet_retro_budget.py` gains seventeen cases. Each failed on the
+  1.99.0 script (it crashed with no archive to read) or on a reviewed intermediate version.
+
+## v1.99.0 (2026-10-21)
+
+Guards: 448 → **530**; property checks 15 → **15**. There are 82 new negatives in
+`lessons.py`. Each one plants a revert, and the suite must catch it:
+
+- the whole-scan refusal put back;
+- the carry-forward removed;
+- status computed without carried origins;
+- prune on every run;
+- git worktrees no longer discovered;
+- memory ids keyed by retro anchor;
+- one memory id left on two class keys;
+- problems attributed by path prefix;
+- `emit`/`record` ignoring the origin that holds the memory id;
+- memory ids compared together with their `@revision`;
+- a stranger at the same path not recognised;
+- `record` putting one memory id on two class keys;
+- an origin removed on its own;
+- a memory id moved to another project's origin;
+- an origin carried as `checkout holds another project` counted;
+- a project key taken from the checked-out branch;
+- a stranger called on a key alone, though the origin's commit resolves;
+- `record` taking another project's id;
+- `record` writing an id the loader refuses;
+- a title carrying a Unicode line separator;
+- the index split on Unicode line breaks;
+- a rebuild printing absolute paths;
+- `--prune-carried-reason` accepted alone, or taking any string, or offering a reason that
+  never occurs;
+- merged duplicate lines dropping an id silently;
+- `add` counting a phantom project after a re-init;
+- a shallow check trusted when it times out;
+- an index line accepted with `mem:x@0` or with an unknown `carried` reason;
+- an origin v1.95.0 wrote kept as a second project, by `rebuild` or by `add`;
+- that re-key made for an origin with provenance, between two candidate repositories, or
+  merging two memory ids (in `rebuild` and in `add`);
+- `record` re-attaching an id from another checkout;
+- one memory id left on two live projects, or kept by the later holder;
+- a project key skipping the main worktree's HEAD or `init.defaultBranch`;
+- redaction replacing a relative name, or inside a longer name;
+- a session note, a newer-format notice or a refusal printing an absolute path;
+- a stage id carrying a line break or a path;
+- a same-revision duplicate decided by the order of lines;
+- a re-key taking a commit from a merged history, ignoring the key v1.95.0 would compute, or
+  moving a project read this run;
+- `add` leaving one id on two live projects; the id kept by the smaller key instead of the
+  earlier holder;
+- a rebuild asking git the same question again;
+- `query`, an `add` refusal or the repository top printing an absolute path;
+- an index set aside for a stage id v1.95.0 accepted, or one normalised past 32 characters;
+- the schema admitting a blank stage id;
+- a partial rebuild or an `add` moving an origin of a project the index already knows;
+- an origin carried as `checkout holds another project` counted as a live holder of its id;
+- a re-key that does not record where the id came from, in `rebuild` or `add`, or loses that
+  source on a repeated `add` or a rebuild;
+- `rebuild`, `add` or `record` never giving a re-keyed id back to its source project, or
+  giving it back while leaving it on the other project too, or over that project's own id;
+- an index line accepted with an impossible `rekeyedFrom`;
+- an id dropped by the one-project or the one-class rule keeping its `rekeyedFrom`, a re-key
+  source given to every project holding that id, a reclaim to a project never read, the main
+  worktree's HEAD keying the repository before `init.defaultBranch`, and `save` writing a line
+  the loader refuses;
+- `record --replace` keeping the replaced id's `rekeyedFrom`, and an `add` or rebuild re-key
+  giving a twin's own id a source it never had.
+
+These are the fixes from verification rounds 6 to 18 of release iteration 1.
+
+- **A replaced id takes its source with it** (round 18). `record --replace` gave the origin a
+  new id but kept the `rekeyedFrom` of the re-keyed id it replaced, so the next read of that
+  source project took X's own record, and X's later record of it was refused. An origin given
+  another id now drops the source. A re-key whose legacy origin held no id no longer tags the
+  twin's own id with the legacy project as its source.
+
+- **No write leaves a line the loader refuses; only a read project reclaims** (round 17).
+  When the one-project or the one-class rule took a memory id off an origin, `rekeyedFrom`
+  stayed behind; the loader refuses a source beside no id, so the next command set the whole
+  index aside as `.corrupt-<date>` and every lesson in it left the live index. The source now
+  leaves with the id, and it follows the (id, project) it was recorded for: another project
+  holding the same id is never given one. `save` reads every line back as the loader does and
+  refuses to write one it would refuse, the previous index intact. A re-keyed id goes back
+  only to a project actually read (an origin with provenance, not carried), never to a
+  v1.95.0 origin that could not be re-keyed in the same run. `init.defaultBranch` now keys
+  the repository before the main worktree's HEAD, so a main worktree on an orphan branch does
+  not move the key. Known, not fixed here, each with a backlog row: a `git replace --graft`
+  moves the key (B-141); a v1.95.0 origin with no twin still counts as a second project
+  (B-142); the known-project set is index-wide (B-143); a case-insensitive path read twice
+  (B-144).
+
+- **Ownership is recoverable, not predicted** (round 16). A re-key can only judge the projects
+  it has already seen, so an `add` in X, or a rebuild of X's root alone, could take an id
+  from a repository Y that had never been read. A re-key now records its source key on the
+  origin (`rekeyedFrom`). The first time Y is read with an origin of that class key, by
+  `add` or `rebuild`, or Y records the id, the id moves back to Y, is dropped from X, and a
+  `reclaimed:` line names it. Whichever verb runs first, the final owner is the project
+  whose key the legacy store used. When Y already holds its own id for that class, nothing
+  moves, and that is said. Each lesson plant now requires its own expected failure line, not
+  any non-zero exit. Known, not fixed here: the known-project set is index-wide, not per
+  class key.
+
+- **Ownership no longer depends on verb order** (round 15). The live-project rule now covers
+  every project the previous index records with provenance, not only the projects this run
+  read: an `add` in a repository, or a rebuild over its root alone, never re-keys another
+  known project's origin, and a later full rebuild agrees. That rule subsumes the separate
+  "no re-key with provenance" check (an origin with provenance names a known project), so the
+  check and its plant (492) are retired; the F1c test stays. Known limit, not fixed here: on a
+  case-insensitive file system one checkout reached by two spellings of its path is read
+  twice (real paths do not fold case), which can count a phantom second project; no memory
+  id ends on two projects.
+
+- **The re-key and the one-project rule, closed** (round 14).
+  - A provenance-less origin is re-keyed only when, in the checkout that re-derived its anchor,
+    its commit descends from the root the new key names (so it resolves there) and v1.95.0
+    would have computed its key there. Round 13's separate "commit resolves" plant (490) is
+    retired: the roots check subsumes it, so reverting it alone changes nothing. So is its
+    "own key re-derived" plant (493): an origin whose own key is re-derived belongs to a project
+    read this run, which the next rule already keeps. A monorepo that merged another repository's history keeps
+    its hands off that repository's origin and memory id.
+  - An origin whose project key any checkout read this run holds is never re-keyed, whatever
+    its anchor.
+  - `add` keeps one memory id on one live project, against the index as it read it.
+  - The M/M2 fixtures put the earlier holder's key above the later one, so "the smaller key"
+    fails every run.
+  - One `cat-file` per (checkout, commit) in a run.
+  - Every verb's messages name files, the index home-relative; `path` alone prints a path.
+  - A stage id v1.95.0 accepted that lesson/1 now refuses is normalised on read and said, so no
+    line and no memory id goes to the corrupt file. The schema's string stage ids are not blank.
+  - The pre-tag admission packet cites the v1.94.0 commit, not the tag object, which a clone
+    without tags does not hold.
+
+- **Upgrade and ownership in `lessons.py`** (round 13).
+  - An index written by v1.95.0 (keyed on the smallest root of HEAD, no provenance) no longer
+    turns a repository that merged an unrelated history into two projects. An origin with no
+    provenance whose `retro#anchor` this run re-derives under exactly one other key, and whose
+    commit resolves in that checkout, is re-keyed: its memory id follows, and `emit` and
+    `record` keep using it. `add` does the same for its own checkout. Never with provenance,
+    never when its own key is re-derived, never between two candidates, never merging two ids.
+  - `record` re-attaches an id held by an origin carried as `checkout holds another project`
+    only from a checkout in that origin's provenance (a re-init at the same path).
+  - A rebuild never leaves one memory id on two live projects: the earlier holder keeps it,
+    and the other origin is named and keeps its place without it.
+  - Without `origin/HEAD`, `main` or `master`, the project key is the main worktree's HEAD,
+    then `init.defaultBranch`, so a linked worktree on an orphan branch is the same project.
+  - Redaction replaces only absolute paths, as whole path components (`--roots .` deleted every
+    dot), and stderr (the session's notes, the newer-format notice, a refusal) is redacted
+    like stdout (in `rebuild`; every verb since round 14).
+  - A stage id given as a string gets the text checks: one line, at most 32 characters, no
+    path or credential shape.
+  - Two copies of one origin at the same revision keep the lexically smaller id, whatever the
+    order of the lines.
+
+- **Identity and safety in `lessons.py`** (round 12).
+  - The project key is the repository's: the first-parent root of its default branch, once
+    per git common dir. A worktree on a branch that merged an unrelated history, or a checkout
+    on an orphan `gh-pages`, is still its project.
+  - `checkout holds another project` applies only when the origin's own commit does not
+    resolve in that checkout. `add` applies the same rule to its checkout's old-key origin, so
+    a re-init never counts a phantom project, even before the next rebuild.
+  - `record` refuses an id another project's origin holds, naming the project (exit 1), and an
+    id the loader would refuse (exit 2).
+  - lesson/1 text (a string stage id too, since round 13) refuses every line separator,
+    including U+2028, U+2029 and U+0085. The index
+    is split on `\n` only, so a value can never make it read as corrupt.
+  - Rebuild messages name checkouts and files, never an absolute path.
+  - `--prune-carried-reason` needs `--prune-carried` and offers only the reasons a rebuild
+    produces; otherwise it is a usage error, exit 2.
+  - Merged duplicate lines name the id they drop and keep the higher revision.
+  - A shallow check that does not answer is refused: no source, and a problem named.
+
+- **`lessons.py rebuild` never removes or moves anything on its own** (round 11, narrowed
+  under the loop guard).
+  - Every previous origin the run does not re-derive is carried with everything recorded on
+    it, its memory id included, and marked `carried: <reason>`.
+  - `--prune-carried`, optionally narrowed by `--prune-carried-reason <reason>`, is the only way
+    an origin leaves the index.
+  - Nothing supersedes and nothing moves: a memory id stays on the origin that holds it, and is
+    re-attached only to the same `(project, classKey)`.
+  - The reasons are `checkout not read`, `retro file not read`, `no checkout read holds it`
+    (the checkout read the file and the entry is gone), `commit does not resolve`,
+    `retro cites a commit that does not resolve`, `lesson refused`, `no provenance` and
+    `checkout holds another project`. The last one is kept but not counted in `seen`,
+    `projects` and `status`; the others count as temporary unavailabilities. So no phantom
+    project appears, and an unreadable root never demotes a lesson.
+  - A shallow clone is never a source: a problem owned by its checkout, with nothing derived
+    under its unstable key. `add`, `emit-observatory` and `record` refuse there, exit 1, and say
+    to deepen it.
+  - Known limit: a project whose root commit changes (re-init, unshallow) starts new store
+    records. The operator re-attaches by `record`-ing the old id on the new origin of the same
+    class key.
+  - `record` over a different id the origin already holds needs `--replace`. It also refuses an
+    id another class key holds and a revision older than the one held.
+  - Each origin records its provenance, `checkouts`, the real paths it was derived from. It
+    decides only the carried reason; it stays in the local index, is never emitted, and `show`
+    omits it. A path is not an identity.
+  - Git worktrees of every checkout found are discovered, including those under
+    `.worktrees/` and `.claude/worktrees/`. Problems carry a structural owner and are printed by
+    name, never by absolute path or prefix match.
+  - Retro files are stamped when read and again under the lock. A file that changed in
+    between, such as an `add` landing mid-run, leaves its checkout not read for that run.
+  - Memory ids follow `(project, classKey)`, compare on the part before `@`, start at revision
+    1, and keep the highest revision everywhere. One id is never on two class keys, and the run
+    refuses to write if an id would vanish other than by `--prune-carried`.
+  - Index lines are re-derived from their origins on every read: `seen`, `projects`, `status`
+    and the rest are never trusted from disk, and duplicate origins and duplicate lines merge.
+    A line with wrong types, an origin lesson that fails lesson/1, a `carried` outside the
+    enum, or `mem:…@0` is a corrupt line. It is salvaged around and never causes a traceback.
+    A memory id that only a bad line held is named in the output.
+  - Exit 1 means nothing could be read: every root was missing or unreadable. A readable empty
+    root, or one holding only a shallow clone, exits 0.
+
+- **`lessons.py rebuild` never loses what it cannot re-derive.** Round 6's narrowed refusal
+  dropped an origin and its memory id while a project's root was unreadable. It also still
+  refused the routine case: an indexed lesson whose commit was pruned after a squash merge.
+  Rebuild now derives every lesson it can read. Every previous origin whose source it could
+  not re-derive is carried forward with everything recorded on it, marked `carried`, and
+  named. That covers a root not read or outside the scan, a commit that no longer resolves,
+  and a refused entry. Carried origins count toward `seen`, `projects` and `status`. They are
+  re-derived and un-marked when the source reads again, and are removed only by the new
+  `--prune-carried`. Rebuild exits 0 whenever anything was read, and exits 1, touching
+  nothing, only when nothing could be read. The loss guard and `--force` are gone.
+  `templates/lesson.schema.json` declares the `carried` field.
+- The merge notice no longer says "read both" when the family index was corrupt and set aside.
+- Docs: `continuity.md` names `graph.py next` exit `6` beside `4`, pinned by
+  `continuity_doc_test.py`, and `waves.md` lists `6` for `next --wave N`. The `graph.py`
+  docstring says exit `3` counts parked nodes as finished. In `stages.md` and `README.md`,
+  `checks` mode puts the release run on a watcher. The release-authority rule has one home,
+  `deploy-targets.md`, and `pipeline.schema.json` points to it.
+- Lessons of this run, now doctrine: `iteration.md` checks for parallel work on the same
+  nodes before each cycle, across every tool's branch prefixes. `build.md` adds a
+  command-hygiene block that every background dispatch carries.
+
 ## v1.98.0 (2026-10-20)
 
 Guards: 448 → **448**; property checks 15 → **15**.

package/README.md

@@ -201,7 +201,7 @@ and the inline fallback satisfy the same [provider contract](plugins/task-pipeli
 | 3 + 4 · every spec and plan | the self-review reads its rules back — is every named check real, does anything contradict a locked decision or a rejected option, and what does this cost now versus at design time. Answers land as a committed `## Self-review` of computed numbers |
 | 6–10 + any check you write | [`gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) — the three axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors |
 | any agent-time enforcement | [`hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) — the `PreToolUse` contract, the fail-open hazard, the Claude-Code-only limit |
-| 7 · the tag | [`deploy-targets.md`](plugins/task-pipeline/skills/task-pipeline/references/deploy-targets.md) → *When the release waits for an approval* — `pipeline.json` → `release.approval`: `checks` (tag, watch the run selected by the tag, report) or `reviewers` (the direct link to the run that is `waiting`) |
+| 7 · the tag | [`deploy-targets.md`](plugins/task-pipeline/skills/task-pipeline/references/deploy-targets.md) → *When the release waits for an approval* — `pipeline.json` → `release.approval`: `checks` (push the tag, put the run selected by the tag on a watcher, take independent work until it reports) or `reviewers` (the direct link to the run that is `waiting`) |
 | between stages | [`continuity.md`](plugins/task-pipeline/skills/task-pipeline/references/continuity.md) Part 3 — workflow memory through Observatory, a planned handoff (`stage_checkpoint.py handoff` / `accept`), and `hooks/memory-nudge.sh`, which reminds once when a gate returned with no memory line after it — unless the run recorded memory unavailable with `--for-run` |
 
 **Ported, not depended on.** Stage 0 is adapted from

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.98.0 |
+| **Version** | 1.99.1 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. The engine is WebKit (Safari) first; `chrome-devtools` is Chrome-only, a stated exception. Every stage's doctrine ships in-repo; user-facing stage 3 requires a valid scenario artifact; super-ux is preferred, with equivalent-provider and inline-fallback paths under the provider contract |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.98.0",
+  "version": "1.99.1",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "task-pipeline",
   "displayName": "Task Pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/judgment/manual gates, a frozen requirement spine that closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a proportional short path for small changes, a loop guard whose ceilings stop and record a blocker, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs); a third, `waves`, takes the whole board and closes it in waves that each finish in one pass. Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.98.0",
+  "version": "1.99.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json

@@ -236,7 +236,7 @@
           "minLength": 1,
           "pattern": "\\S",
           "not": {"pattern": "[\\r\\n]"},
-          "description": "Optional single-line source locator (for example docs/DECISIONS.md:42) for the specific standing authorization covering the tag and its publication. The locator is not authorization: read the source and verify its authority, currentness and scope at stage 7. Absent: inspect existing recorded authority before asking; do not infer a grant from checks approval, loop mode or this field's mere presence (references/deploy-targets.md)."
+          "description": "Optional single-line source locator (for example docs/DECISIONS.md:42) for the standing authorization covering the tag and its publication. A locator, not a grant: how it is read and verified lives in references/deploy-targets.md, When the release waits for an approval."
         },
         "approval": {
           "enum": [

package/plugins/task-pipeline/skills/task-pipeline/references/build.md

@@ -233,6 +233,21 @@ Record the implementer's agent identity: fix rounds 1–3 resume it.
 > commit range, a one-line test summary, and your concerns. Ask before starting
 > if anything in the brief is ambiguous — questions are cheaper than rework.
 
+**Command hygiene** — put this in every background dispatch, whether it goes to an
+implementer, a reviewer or a verifier:
+
+> Avoid commands that the harness holds for permission. Do not write `cd X;` compounds: use
+> absolute paths or `git -C`. Do not write `rm -rf $VAR`: use a literal path or `"${VAR:?}"`.
+> Do not edit repository files with inline heredocs: use the editor tool or a script file.
+> If a command has not returned in about 5 minutes and no process is running, rephrase it.
+
+*A lesson of release iteration 1 (2026-10-13): background agents stopped silently. Each was
+waiting on a command the harness held for a permission no one could see. The triggers were a
+`cd X; python3 - <<EOF` compound and `rm -rf $HOME` with HOME overridden. Source: the
+iteration's run record, which is private, and
+[task-pipeline#125](https://github.com/ssheleg/task-pipeline/pull/125), which carries the
+rule.*
+
 ### 4.1a Decisions settled inside a task — and who may write them down
 
 The report above already asks for *"decisions you made"*, and stage 5 settles more

package/plugins/task-pipeline/skills/task-pipeline/references/continuity.md

@@ -108,9 +108,12 @@ questions are marked `needs-operator` and made answerable without context
 ([`prioritisation.md`](prioritisation.md) → *5. Where the human goes*); external waits
 get watchers, and project-owned questions go to the owning Project under
 [`iteration.md`](iteration.md)'s board rule. The run continues on every node it does
-not block. When the whole frontier is blocked — `graph.py next` exits `4` — classify the
-recorded reasons: external waits go on watchers, human decisions go into the question
-batch. Exit 4 does not prove a human gate or completion. A watcher keeps the recorded
+not block. When the whole frontier is blocked, `graph.py next` says which kind of block it
+is. Exit `6` means every remaining dependency leaf is a recorded watched wait: keep those
+watchers armed and take independent work ([`work-graph.md`](work-graph.md) → *Watched
+external waits*). Exit `4` means a mixed, unclassified, running or parked barrier remains:
+classify the recorded reasons, put external waits on watchers and human decisions into the
+question batch ([`waves.md`](waves.md)). Neither code proves a human gate or completion. A watcher keeps the recorded
 next action alive while no independent node is runnable. **When the board is empty, say so once**, and do not invent work to fill it.
 
 **Stop is not idle.** A finish line reached closes that iteration — stages 9–10, the

package/plugins/task-pipeline/skills/task-pipeline/references/iteration.md

@@ -75,6 +75,22 @@ act. **Step 11 runs stage 8's verification trio** on what was released. Steps 12
 with stage 10. No gate in [`stages.md`](stages.md) is skipped. The cycle changes when each
 stage runs, and over what.
 
+**Before each cycle, check for parallel work on the same nodes.** In every target repository,
+list the open PRs and the recently merged ones by branch prefix. Include other CLIs' prefixes,
+such as `codex/`, `fix/` and `release/`, and do not stop at your own tool's live sessions:
+
+```bash
+gh pr list -R <owner>/<repo> --state open   --json number,headRefName,title
+gh pr list -R <owner>/<repo> --state merged -L 20 --json number,headRefName,mergedAt
+```
+
+Each node has one owner. When work has to be split, record the split on the PR you would
+otherwise collide with. *A lesson of release iteration 1 (2026-10-13): fix PRs from other
+tools' branches landed on nodes a fix cycle was rebuilding, and a later cycle was briefed on
+a PR that had already merged. Source: the iteration's run record, which is private, and
+[task-pipeline#125](https://github.com/ssheleg/task-pipeline/pull/125), which carries the
+rule.*
+
 ## Module dossiers
 
 **One dossier per cluster.** The inventory is grouped by the part of the system each item
@@ -259,13 +275,152 @@ private to its project and never leaves it.
 **Layer 1 — every install, no service.** The project retro and [`learned.md`](learned.md),
 as before, plus a **local index** of every project's lessons on this machine:
 `scripts/lessons.py`, one JSON line per class, a pure function of the retros
-(`lessons.py rebuild --roots <dir>` re-derives it). Rebuild replaces the projection for
-its explicitly selected roots and depth: choose the whole intended scope. A readable empty
-scope can produce an empty index; a missing or unreadable root, discovery error, malformed
-artifact configuration, missing explicitly configured artifact directory, dangling source
-link, nonregular retro input, or invalid/unresolved lesson refuses before changing the index
-or its migration state. An absent default artifact directory in a new repository remains
-a valid empty source. Repair the named source and retry; unknown is never measured zero.
+(`lessons.py rebuild --roots <dir>` re-derives it). **A rebuild never removes or moves
+anything on its own.** It derives every lesson from the retros it can read under the roots and
+depth given, and from every git worktree of each checkout it finds. Worktrees under
+`.worktrees/` or `.claude/worktrees/` are included, even though the walk skips
+dot-directories.
+
+An origin is one project's copy of a lesson, `(project, retro)`. It records its
+**provenance**: the checkouts it was derived from, by real path. That record stays in the
+local index; it is never emitted, and `show` omits it. Provenance decides only the reason an
+origin is carried, never a removal.
+
+**Every previous origin the run does not re-derive is carried.** Nothing is removed and nothing
+is moved: no origin is dropped because a checkout read its retro and no longer found the entry,
+and no memory id moves to another project's origin. **`rebuild --prune-carried` is the only way
+an origin leaves the index**. `--prune-carried-reason <reason>` narrows it to one reason. It
+needs `--prune-carried`, and it offers only the reasons listed below; anything else is a usage
+error, exit 2. A
+carried origin keeps everything recorded on it, including its memory id, and is marked
+`carried: <reason>`, named in the summary. It is re-derived and un-marked as soon as a checkout
+holding it reads again. One thing is re-keyed rather than carried, on positive evidence only:
+an origin written before provenance existed (v1.95.0 keyed a project on the smallest root
+commit of HEAD) whose `retro#anchor`, under the same class key, this run re-derives under
+exactly one other key, and in the checkout that re-derived it: its own commit resolves there,
+v1.95.0 would have computed exactly its key there, and the commit descends from the root the new
+key names (its own history, not a history the repository merged). It is the same repository, so
+it takes the new key and its memory id follows; `add` does the same for its own checkout. It is
+never re-keyed when it has provenance, when its project key is held by any checkout read this
+run or by any origin of the previous index that has provenance (so the verb and the roots
+given never decide who owns an id), when two keys could claim it, or when the copy under the new key holds a different memory
+id (then it stays carried, and that is named). A monorepo that merged another repository's
+history therefore never takes that repository's origin.
+
+A re-key can only judge the projects already seen, so ownership is made recoverable: the
+re-keyed origin records its source key as `rekeyedFrom`. The first time that project is read
+with an origin of the same class key (by `add` or `rebuild`), or records the id itself, it
+takes the id back; the other origin keeps its place without it, and a `reclaimed:` line says
+so. Read means an origin with provenance that is not carried: a v1.95.0 origin under that key
+that could not be re-keyed is not a read, so the run that re-keys never hands the id back to
+it. Whichever verb runs first, the final owner is the project whose key the legacy store used,
+once that project is read. If that project already holds its own id for the class, nothing
+moves, and that is named. An origin that loses its id to the one-project or the one-class rule
+loses `rekeyedFrom` with it, so does an origin `record --replace` gives another id, and a
+re-key records a source only for an id it moved from the legacy origin; and no verb writes an index line the loader would refuse: `save`
+refuses instead, the previous index intact. The reasons are:
+
+- `checkout not read`: the checkout was not discovered, or a problem is owned by it. That
+  problem may be an unreadable retro, a refused `git worktree list`, a shallow clone, a broken
+  configuration, or a retro that changed while the rebuild ran (an `add` landing mid-run).
+- `retro file not read`: the checkout read completely, but that file was not read, for
+  example because it lies outside the artifact root or was moved.
+- `no checkout read holds it`: the checkout read the file, holds the same project, and the
+  entry is no longer there.
+- `commit does not resolve`, `retro cites a commit that does not resolve` or
+  `lesson refused`: the entry is there but could not be derived. A dangling commit is routine
+  after a squash merge and a deleted branch.
+- `no provenance`: the origin was written before provenance existed, and no re-derived origin
+  proves it is the same repository's.
+- `checkout holds another project`: every checkout in its provenance now holds a different
+  project key, and the origin's own commit does not resolve there. A path is not an identity.
+  The same repository under another key still holds the commit, so it is not a stranger;
+  `add` applies the same rule to its own checkout's old-key origin.
+
+The project key is the repository's own: the first-parent root of its default branch
+(`origin/HEAD`, then `main`, then `master`, then the branch `init.defaultBranch` names).
+Without any of them it is the main worktree's HEAD, read in the common directory, so every
+worktree gets one answer; then this checkout's HEAD. It is computed once per git common directory. A worktree on a branch that merged an unrelated history, or a
+checkout sitting on an orphan `gh-pages` branch, is still its project.
+
+**Counting.** `seen`, `projects` and `status` count re-derived origins and every carried origin
+except `checkout holds another project`. Those are kept, with their memory ids, but not counted.
+So a temporarily unreadable root never demotes a lesson two projects hold, and a stranger at a
+path, or one checkout under a new root commit, never makes a phantom second project. Derived
+fields are recomputed from the origins whenever the index is read; they are never trusted from
+disk.
+
+**Shallow clones.** A shallow checkout is never a source. It is a problem owned by that
+checkout, nothing is derived from it under its unstable key, and its origins are carried as
+`checkout not read`. A shallow check that does not answer is refused the same way, and since
+it taught nothing, it does not count as something read. `add`, `emit-observatory` and
+`record` refuse in a shallow clone, exit 1 and write nothing, and say to deepen it with
+`git fetch --unshallow`.
+
+**Known limit.** A project whose root commit changes, through a re-init or an unshallow, starts
+new store records: its old origins are carried as `checkout holds another project` with their
+memory ids, and the new origins start without one. The operator re-attaches by running
+`record` with the old id on the new origin, from the same checkout. That is allowed, because
+the new origin is of the same class key and the origin holding the id is carried as `checkout
+holds another project` with this checkout in its provenance. From any other checkout it is
+refused.
+
+Another checkout of the same project, even one reading the same retro path, decides nothing
+for an origin it never held. Problems carry their owner, a checkout or none, and are never
+matched by path prefix.
+
+**Memory ids.** A memory id belongs to `(project, classKey)`, the store's own identity, and
+never to a retro anchor:
+
+- A rotated or retitled entry keeps its id on the re-derived origin. The old anchor is carried.
+- A class key changed inside one entry does not inherit another key's id.
+- One id is one `(project, classKey)`. `record` refuses each of the following, exits 1 and
+  writes nothing:
+  - an id that another class key holds;
+  - an id that another project's origin holds (the refusal names that project), unless that
+    origin is carried as `checkout holds another project` and this checkout is in its
+    provenance (the re-attach above);
+  - a revision older than the one held;
+  - without `--replace`, a different id over the one the origin already holds.
+
+  It also refuses an id the index cannot hold, such as `mem:`, a quote, a backslash or a
+  space: that exits 2.
+- One id is one project's store record. Two projects may hold it only while one of them is
+  carried as `checkout holds another project`. When a rebuild would leave it on two live
+  projects (that checkout came back), the id stays on the earlier holder: the project the
+  previous index carried as `checkout holds another project` with it, else the smaller project
+  key. The other origin keeps its place without the id, and the run names it. `add` applies the
+  same rule against the index as it read it, so an add from an old clone never leaves the id on
+  both projects either.
+- Merged duplicate lines name every id they drop. Of two copies of one origin the higher
+  revision wins; on equal revisions, the lexically smaller id.
+- Ids compare on the part before `@`, revisions start at 1, and the highest revision wins.
+
+`emit-observatory` and `record` both use the origin of the project that holds the id. The run
+refuses to write if a memory id would vanish other than through `--prune-carried`.
+
+Unreadable sources are named under `not read`, by name rather than by absolute path. Every
+root, checkout, repository top, file given and directory is shown by its name — the index files
+home-relative, such as `~/.sshlg-skills/lessons/index.jsonl` — in every verb's messages, on stdout
+and stderr alike (the session's notes and a refusal too). `path` alone prints the path: that is
+its answer. A git question about one commit in one checkout is asked once per run. Only absolute paths are replaced, and only as whole
+path components, so a root given as `.` changes no other text. The index is split on `\n` only, and
+lesson/1 text refuses every line separator, including U+2028, U+2029 and U+0085. So no value
+can make a good index read as corrupt. The run
+exits 0 whenever anything was read: a retro, a checkout discovered in full, or a shallow
+checkout found. A readable root that holds no checkout also exits 0: the index is written,
+and every origin is carried. The run exits 1 only when nothing could be read because every
+root was missing or unreadable; then no index, lock directory or migration is touched. A held
+lock or an unreadable index is its own refusal. On the default path the one-time merge of a
+standalone index runs first, as for every verb.
+
+So does setting a corrupt index aside:
+- The file is kept whole as `.corrupt-<date>`.
+- Every line that still parses is salvaged into the live index.
+- Two lines for one class key are merged.
+- A memory id that only a bad line held is named in the output.
+
+Unknown is never measured zero, and never measured gone.
 Two projects holding one class key make
 one lesson seen twice, status `candidate`. The index path is a parameter — `--index`, then
 `$TASK_PIPELINE_LESSONS`, then `~/.sshlg-skills/lessons/index.jsonl` **when
@@ -290,7 +445,8 @@ rule 2 (no host identifiers) for exactly two fields, and nothing else:
   repository's SHA names nothing to someone without the clone; **a public repository's SHA
   is searchable** and leads to the repository, so it stays in this field and never in text;
 - **`origin.project`, the pseudonymous project key** — `p-` and 12 hex digits of the
-  repository's root commit — stable across clones and never the repository's name, because
+  repository's root commit (the first-parent root of its default branch, so every worktree
+  and branch of one repository shares it) — stable across clones and never the repository's name, because
   lessons are read into *other* projects' briefs and a repository name can be a customer's
   or a product's. The shared store receives the same key, never a `project:<slug>` id.
 
@@ -298,7 +454,10 @@ Rules 1, 3, 4 and 5 still bind every text field, on the estate as off it: no pat
 no code or value, no person's, company's, customer's or product's name, and a title that
 states the class rather than the incident. Never, in either layer, a transcript or a URL.
 `lessons.py` refuses what a pattern can see (paths, URLs, addresses, credential shapes, long
-hex or base64 runs) and any field lesson/1 does not name; a name it cannot see stays the
+hex or base64 runs, line breaks) in every text field and in a stage id given as a string (at
+most 32 characters, never blank), and any field lesson/1 does not name. A stage id an older
+index holds that fails those checks is normalised when the index is read (one line, cut to 32
+characters, or `stage`), and said, so the line and its memory id are never set aside; a name it cannot see stays the
 writer's duty. Off the estate (`retro.publish`) the relaxation ends: the whole origin is
 stripped.
 

package/plugins/task-pipeline/skills/task-pipeline/references/retrospective.md

@@ -205,6 +205,10 @@ narrative are how a capped list grows anyway.
   `Because`) **verbatim** into the quarter's archive, each block carrying the sha256 of
   its text, and leaves a pointer; `retro_budget.py verify` proves every pointer. An
   instruction still over 600 characters after its story moved is rewritten by hand.
+  An older retro whose standing instructions are a numbered list and whose stamps are
+  `- **date: title**` items is read the same way: the item keeps its bold rule and its
+  `*(Retire ...)*` trigger, a stamp keeps its title, stamps past the cap rotate out by date,
+  and, over budget, the Run stamps section's loose prune paragraphs move.
 - **A prune that retires nothing writes its count into the stamp row**, as
   `prune: 0 retired`, and no paragraph. Repeated "nothing to prune" notes were a
   measured share of the floor.
@@ -476,7 +480,8 @@ private to this project.
 **A lesson is not a publication, but the redaction list below binds it too — with one
 relaxation.** On this machine or estate (the local index, a shared store), rule 2 is relaxed
 for exactly two fields: the evidence commit and the pseudonymous project key (`p-` and 12 hex
-of the root commit, the same key in the store, never the repository's name or a
+of the root commit — the first-parent root of the default branch — the same key in the store,
+never the repository's name or a
 `project:<slug>` id). A private repository's SHA names nothing; a public repository's SHA is
 searchable, so it stays in its field and never in text. Rules 1, 3, 4 and 5 still bind every
 text field: no path at all, no code or value, no person's, company's, customer's or

package/plugins/task-pipeline/skills/task-pipeline/references/stages.md

@@ -315,14 +315,11 @@ never that the work was skipped quietly.
   close before it ships. **The
   carry-over count is printed beside this verdict.** Deploy is outward → explicit
   operator go, or a specific standing authorization naming that act, cited with its source
-  and scope. Authorization to release does not silently authorize a separate deploy. If
-  `release.authorized_by` is present, read that source and verify its authority,
-  currentness and scope for the tag and publication; the locator is not authorization.
-  If absent, inspect existing recorded authority before asking for a missing grant.
-  **Before the tag, read
-  the release's approval mode** (`pipeline.json` → `release.approval`; then
-  [`deploy-targets.md`](deploy-targets.md) → *When the release waits for an approval*):
-  `checks` — push the tag, watch the run selected by the tag, report; `reviewers` — the
+  and scope. How a release's authority is established, `release.authorized_by` included,
+  has one home: [`deploy-targets.md`](deploy-targets.md) → *When the release waits for an
+  approval*. **Before the tag, read the release's approval mode** (`pipeline.json` →
+  `release.approval`; the same section): `checks` — push the tag, put the run selected by
+  the tag on a watcher and take independent work until it reports; `reviewers` — the
   direct link to the run that is actually `waiting`, never a request without it. Respect deploy-from-main rules if the project mandates them. **Before
   tagging, the CI verdict for what was just pushed is READ, not assumed**
   ([`conventions.md`](conventions.md) → *The CI verdict*) — a tag on a commit whose

package/plugins/task-pipeline/skills/task-pipeline/references/waves.md

@@ -263,7 +263,8 @@ The work graph ([`work-graph.md`](work-graph.md)) carries `wave` on a node, an i
 - `graph.py validate` refuses an edge from a later wave's node into an earlier wave's
   node: an earlier wave that waits on a later one cannot close in its own pass.
 - `graph.py next --wave N` prints wave N's frontier only. Exit `3` says the wave is done,
-  `4` that nothing in it is runnable, `1` that no node is in wave N.
+  `4` that nothing in it is runnable behind a mixed or unclassified barrier, `6` that only
+  recorded watched waits hold it, `1` that no node is in wave N.
 - `graph.py wave N-007 --to 3 --why "<reason>"` moves a node and writes the revision.
   It refuses a move that would break the order above.