task-pipeline-skill 1.97.1 → 1.99.0

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

@@ -1,576 +1,21 @@
-# Retrospective — the run teaches the next run, and the list stays short
-
-The last act of stage 10, after the coverage table and before the run is called
-done. It exists because the pipeline's gates are good at *this* run and blind
-across runs: the same class of failure can be caught, fixed and forgotten five
-times, and nothing in the flow notices it is the same one.
-
-**The cap here is not a general rule about doctrine files.** It applies because these
-instructions are read *in full* every run. [`learned.md`](learned.md) →
-*What leaves this file, and why there is no cap* is the other case: a file entered by
-citation, where the index must be right rather than the length short, and where a rule
-retires on two triggers that are not counts. Proposing this cap for that file is a
-recurring idea, and it is answered there with the measurement rather than an opinion.
-
-**Two artifacts, and the split is the point.** A file that is read *in full* every
-run may not contain anything that grows without limit — otherwise the cap that
-justifies reading it protects one section while the file below it doubles.
-
-| Artifact | Parts | How it is read |
-|---|---|---|
-| `docs/evidence/retro.md` — **one per project** | **Standing instructions** (max **10**) · **Run stamps** (max **10**, oldest rotate out) | stage 0, **in full** — both are bounded by a **cap**, which *one line each* never was |
-| the same file's **Recent log** | narrative entries, **uncapped by design** — the heading said *entries from the last five run stamps* until 2026-08-20 while the section held 25 going back nine days, a bound in a heading that nothing enforced | stage 0, **queried** by the task's nouns. It said *in full* until 2026-08-10, when it measured **74%** of the file: an uncapped section inside a binding source is what makes the capped part get skimmed |
-| `docs/evidence/retro/YYYY-QN.md` — the archive | every entry and every retirement ever written, append-only | **queried** by the task's nouns; never read end to end |
-
-Seed the archive from [`../templates/retro-archive.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/retro-archive.md).
-
-Every run writes a **stamp** and runs the **prune**. Only a run that *diverged*
-writes an entry. A retro that is empty after a messy run is the exact failure this
-file exists to stop.
-
-## Contents
-
-- Write the entry only for a divergence — and name the layer that owned it
-- Every lesson carries its commit
-- Never amend a commit a record already names
-- A release stamp names the TAG, and the merge commit — never the branch's own SHA
-- The stamp table is capped at ten, and *one line per run* was never a cap
-- `publish:` is a line in the verdict, not a silence
-- Rotation — the archive is how pruning stops losing things
-- Three grades of fix — take the highest one that can work
-- Stamp first, then prune, then write
-- The prune — mandatory, and it runs after the stamp
-- When the prune cannot run, say so — it is not the same as nothing to prune
-- A fix to one call site closes a call site, not a class
-- The loop closes at stage 0
-- Where a lesson goes when it is not about this project
-- Recording to a shared lesson store, where the host has one
-- Publishing the insight — the skill learns from every project that runs it
-- The improvement iteration — what happens to a published insight next
-- What may leave the project — the redaction list
-- Rationalizations
-
-## Write the entry only for a divergence — and name the layer that owned it
-
-An entry is owed when the run did not go as planned: a gate reopened, a stage was
-re-entered, a fix broke something it wasn't touching, an estimate was wrong by a
-factor, the operator had to intervene where the brief said they wouldn't.
-
-Required fields, and none of them is optional:
-
-| Field | The rule |
-|---|---|
-| **Symptom** | what actually happened, in one line, with the evidence (a command, a `file:line`, the gate that reopened) |
-| **Surfaced at** | the stage where it became visible |
-| **Owned by** | the stage that *let it through* — usually an earlier one. A finding belongs to the layer that owns it; recording it against the stage that tripped over it is how the same defect returns |
-| **Root cause** | why the pipeline permitted it. "The agent was careless" is not a cause — it is the absence of one, and it produces no fix |
-| **Fix** | one of the three grades below |
-| **The check** | what would have caught this the first time. If the honest answer is "nothing yet", that is the fix, and it is grade 1 |
-| **Commit** | the short SHA of the change that fixed it |
-
-## Every lesson carries its commit
-
-A standing instruction carries **two** SHAs — `Commit` (the change that introduced
-it) and `Fired at` (the last run in which it fired) — and every log entry and every
-retirement carries one.
-
-**Why a SHA and not a `file:line`.** A line number rots at the next edit, and then
-the evidence points at something that has moved or gone; the reader is left with a
-claim and no way to check it. A commit is immutable and carries the diff, the
-message and the parent, so `git show <sha>` reconstructs the entire incident two
-months later — which is exactly when the same class comes back and somebody needs
-to know whether this was already understood.
-
-**Every SHA must resolve — and resolving is not enough.** This is
-[`learned.md`](learned.md) rule 14 — *a document may not send a reader to something
-absent* — applied to history, and it is mechanical: the documentation gate runs
-`git rev-parse --verify --quiet <sha>^{commit}` over every backticked SHA in the retro
-and its archive ([`gates.md`](gates.md)).
-
-**But a commit that was amended away still resolves on the machine that amended it**,
-and exists in no clone. The gate therefore also requires each SHA to be **reachable
-from `HEAD`** — `git merge-base --is-ancestor <sha> HEAD` — because that is the
-question a reader two months from now is actually asking, and the weaker one passes
-for as long as the object survives locally.
-
-## Never amend a commit a record already names
-
-Measured 2026-08-16, twice in one close-out and twenty minutes apart. The sequence is
-seductive because each step is right on its own: stamp the run with its commit → the
-stamp is part of the run, so fold it in with `--amend` → the amend mints a new SHA →
-the stamp now names a commit that will never reach the remote.
-
-The rule is one line and it is absolute: **once a file names a SHA, that commit is
-frozen.** A correction goes in a *follow-up commit*, never a second amend — amending to
-repair a stamp is the loop that produced the problem, and the second attempt lands in the
-same place as the first.
-
-Practically, that makes the order:
-
-1. commit the work;
-2. **then** stamp, in a commit of its own, naming the commit from step 1;
-3. prune and write the entry in that same second commit, or a third.
-
-The stamp costs one line and one commit. A run that folds it back into the work to keep
-the history tidy is trading a reader's ability to find the incident for the appearance of
-tidiness — and the reader is the entire reason the stamp exists.
-
-## A release stamp names the TAG, and the merge commit — never the branch's own SHA
-
-The sibling of the amend rule, one level up, and it recurred three times after the amend
-rule was written because each step is right on its own: stamp the run on the PR branch →
-the stamp cites that branch's HEAD → `main` is **rebase-merge-only** by ruleset → the
-rebase mints new SHAs → the object the stamp names dies with the branch.
-
-Measured across `v1.79.1` (twice) and `v1.80.0`, and again on 2026-09-05 in the umbrella
-repository, where it burned **two tags** in one afternoon. Each recurrence costs the same
-two refusals, both of them correct:
-
-1. the **unstamped-release guard** reads the tag's own commit range, finds no stamp that
-   resolves, and refuses the release;
-2. the **documentation gate** resolves every backticked commit reference against a *fresh
-   clone*, where the branch SHA has never existed, and refuses again.
-
-Then it costs one extra PR and one full CI round — measured at 57–97 minutes here.
-
-**The shape that survives a rebase-merge is the tag.** A SHA the author can know before
-the merge is precisely the SHA the merge is about to destroy, so the rule cannot be
-"write a better SHA". Two spellings are allowed and nothing else:
-
-- **cite the release tag** — `v1.84.1` is immutable, it is the thing being released, and
-  it resolves in any clone;
-- **or write the stamp AFTER the merge**, in a second PR, naming the **merge commit**.
-  This is the default, because it is what the amend rule already forces one level down:
-  once a file names a SHA, that commit is frozen, so the SHA has to exist first.
-
-The order for a release run is therefore:
-
-1. merge the work; the merge commit is now a real object on `main`;
-2. **then** stamp, in a second PR, naming that merge commit;
-3. cut the tag **locally**, run `npm run test:all` against the tag's own tree, and push
-   the tag only if that run is green — `git merge-base --is-ancestor <stamp-sha> HEAD`
-   is what the release gate will ask, so ask it first.
-
-Step 3 is not optional and it is not the same as a green branch build: the branch tree
-and the tag's tree differ by whatever the merge did, and **a tag cannot be repaired** —
-deleting or re-pointing one is refused by repository rule, correctly, because a tag is a
-promise about a tree. A tag pushed on a green branch build is a promise about a tree
-nobody ran.
-
-## The stamp table is capped at ten, and *one line per run* was never a cap
-
-Measured 2026-08-10: standing instructions **~1 234 tok** behind a cap of ten, run stamps
-**~2 099 tok over 27 rows** behind nothing. Both are read in full at stage 0 and both
-were described as *bounded by construction*. One line per run is a **slope**: at a
-hundred runs the stamp table alone is ~7 800 tokens of a floor the doctrine believes is
-bounded.
-
-This is the same shape the 2026-08-10 audit found in the narrative log and moved out of
-the floor — and it left the neighbour in the same file, with the same property, because
-the neighbour's growth is *tidy*. A tidy slope is still a slope.
-
-**The cap is ten and the trigger is why.** The cold rule reads *the last five run
-stamps*; ten is that with a margin, so a stamp rotating out can never be one the trigger
-needed. At the eleventh, the oldest row moves — whole, with its verdict and its retro
-column — into `docs/evidence/retro/YYYY-QN.md` under `## Run stamps`, append-only,
-like every other rotation. **The count is printed at the prune**, beside the standing
-instructions' own count, so a table that stops rotating is visible rather than merely
-large.
-
-## `publish:` is a line in the verdict, not a silence
-
-Reported from another project, and the report is about this file: an operator asked, after
-many runs, why nothing had ever been published.
-
-The floor is right and does not move — publishing is opt-in per project, off by default,
-because an outward act taken from a generic flag is an outward act nobody authorized. The
-gap is what happens next. A project with no configuration produces, run after run,
-retrospective entries carrying lessons about **the skill**, and the mechanism reports
-nothing, because it was never armed. **An unarmed mechanism and a mechanism with nothing
-to say are indistinguishable from the outside** — [`gates.md`](gates.md)'s false success,
-applied to this bundle's own learning path. In the reporting project several runs had
-produced skill-level lessons over months; the count of published insights was zero and no
-gate had ever mentioned it.
-
-Stage 10 prints ratchets and two disclosures — what the run declined to claim, and what a
-check never looked at. Publishing is neither, so its absence is not observable at the only
-moment anyone is reading.
-
-**So stage 10's block carries one line for publication:**
-
-```
-publish: <issue url>                       — opened this run
-publish: 0 (configured, nothing insight-grade)
-publish: not configured (N insight-grade entries stayed local)
-```
-
-It arms nothing and authorizes nothing; it makes the silence legible. A count of zero
-beside *configured* is a fine answer. A **blank** where configuration is absent is how an
-instruction went unread for eight releases.
-
-**The failure mode survived its own fix, in a quieter form.** This section once said
-*"open an issue upstream"* while naming no repository, no trigger and no authorization,
-and every reader took it as done. The mechanism that replaced it is correct — and until
-this line existed it still had no way to say it never ran.
-
-## Rotation — the archive is how pruning stops losing things
-
-At the prune, entries older than the last five run stamps **move** to
-`docs/evidence/retro/YYYY-QN.md`. Moving is not deleting.
-
-- The archive is **append-only**, and a retirement writes its line **there**, with
-  the trigger that retired it and the commit.
-- A retired rule that comes back as a real failure is a grade-1 fix — **with its
-  history attached**, which is the whole return on having archived it.
-- Nothing is ever removed from the archive to keep it tidy. It is not read in full,
-  so its size costs nothing; its completeness is what it is for.
-
-## Three grades of fix — take the highest one that can work
-
-**Grade 1 — mechanical.** A test, a lint rule, a gate criterion, a CI step, a hook.
-The check *is* the memory: nothing has to be read, remembered or pruned later. Log
-it as `landed` and move on — it never becomes a standing instruction and never
-costs a slot.
-
-**Grade 2 — a standing instruction.** A rule an agent must read, for the cases no
-check can decide (a judgement, a precedence, a "ask before X"). It costs one of the
-ten slots and it is **only accepted with its retirement trigger written at birth**
-(below).
-
-**Grade 3 — a note with an expiry.** For something still being understood. Maximum
-**two runs**. At the second stamp it is promoted to grade 1 or 2, or deleted. A note
-with no expiry is how a file becomes unreadable one honest line at a time.
-
-Prefer grade 1 whenever a check can decide it. This is the same law as
-[`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) → *A class that repeats twice becomes a gate, not a note*: a
-rule that could have been a check gets read twice and obeyed once.
-
-## Stamp first, then prune, then write
-
-`learned.md` rule 21. This order used to be *prune first*, and that was a **deadlock**, not a
-preference: the cold trigger below reads *the last five run stamps*, and the stamp was written after
-the prune. The trigger read a counter the same stage produced later, so on any list it had never run
-on real data — and it stays unreadable for exactly as long as nobody stamps.
-
-Measured on a real project: last entry five days old; stamps per day 33, 20, 26, **3, 0** — the zero
-on a day with 107 commits — and the list sitting at **10 of 10**. Every run arrived at a stage that
-opened with a full list, an unusable trigger and a mandatory deletion. It was not skipped out of
-laziness; its first step could not be performed, and the cheap step that would have made it
-performable was queued behind it.
-
-**The stamp is one line and costs nothing.** It is also the only thing that makes the prune
-computable, which is why it goes first:
-
-```bash
-printf '%s · %s\n' "$(date +%F)" "$(git rev-parse --short HEAD)" >> docs/evidence/retro.md
-```
-
-## The prune — mandatory, and it runs after the stamp
-
-A lesson that lands in a cluttered file is a lesson nobody will reach — so the prune still runs
-before the entry is written. It runs *after* the stamp, because it reads it.
-
-Every row carries its own trigger in a **`Retire when`** column AND a **class**,
-both written at birth — a rule whose retirement condition is decided later is a
-rule the prune can only argue about. Three classes, because coldness means
-three different things:
-
-- **permanent** — a safety invariant, a contract, a recovery procedure. The
-  absence of the rare event it guards is not absence of value: **coldness never
-  retires a permanent rule** — only *became a check* or *surface gone* do.
-- **situational** — fires when a named EXPOSURE occurs (a payment run, a
-  migration, a release). Its row names the exposure, and the prune counts
-  **exposure opportunities, not raw runs**: five runs that never touched
-  payments say nothing about a payment rule.
-- **temporary** — a workaround with a **TTL** and the replacing mechanism named
-  at birth. TTL only exists on this class.
-
-Check **every** standing instruction against three triggers:
-
-| Trigger | Test | Then |
-|---|---|---|
-| **It became a check** | the rule is now enforced by a test, lint, gate or hook | delete it — the check is the memory, and keeping both means it is read twice and obeyed once |
-| **Its surface is gone** | resolve every path, command, stage and tool it names; any that no longer exists | delete it — it now describes a system nobody is running |
-| **It went cold** | *situational only*: it fired in none of the last **five exposure opportunities** — or no exposure occurred in **sixty days** | mark **review-needed** and put the question to the operator with the exposure counts — cold is evidence worth reviewing, never an automatic deletion. *temporary*: TTL expired → archive it **once the replacing mechanism is verified present** (its check resolves and runs); an expired workaround whose replacement is absent is a live defect, not a retirement. *permanent*: not applicable |
-
-Every removal stays explainable: the archive line names the class, the trigger
-and the evidence (the exposure counts, or the replacing mechanism's check).
-
-**Each trigger is a command, not a judgement.** A retirement condition nobody can run is a
-condition nobody applies, which is how a list reaches ten and stops being read:
-
-```bash
-# became a check — the rule's own words appear in something that runs
-grep -rl "$RULE_KEYWORD" scripts/ test/ .github/workflows/ Makefile* 2>/dev/null
-
-# surface is gone — every path, command and tool it names, resolved
-grep -oE '`[^`]+`' <<<"$RULE_TEXT" | tr -d '`' | while read -r t; do
-  [ -e "$t" ] || command -v "$t" >/dev/null || echo "MISSING: $t"; done
-
-# went cold — fired in none of the last five stamps
-tail -n 200 docs/evidence/retro.md | grep -c "$RULE_ID"
-
-# ...OR in the last 60 days, whichever comes first — see below for why both
-git log -1 --format=%cd --date=short -S"$RULE_ID" -- docs/evidence/retro.md
-```
-
-Anything the first two print is a deletion. A zero from the third — counted against
-**exposure opportunities** for a situational rule (`grep -c "$EXPOSURE_MARK"` over the same
-stamps, so the denominator is runs that COULD have fired it) — marks **review-needed**, and the
-run states the counts rather than the conclusion (`learned.md` rule 19 — an empty result and an
-unrun command look identical). Only the operator's answer, or a temporary rule's verified
-replacement, turns review-needed into a removal.
-
-**Why the cold trigger needs two units, and it is not belt-and-braces.** A run stamp is written by
-a run *of this pipeline*. Where a project ships some of its work another way, the stamp counter
-stops while the work does not — so "the last five stamps" can span an arbitrary amount of change,
-and a rule sits unexamined for exactly as long as the pipeline goes unused. Measured on this
-repository: **ten consecutive releases, `v1.16.0` through `v1.23.0`, carry no stamp at all.** Over
-that stretch the trigger was not strict or lenient; it was **unreadable**, and a list capped at ten
-with an unreadable retirement condition fills up and stops being pruned.
-
-The wall-clock alternative fires on elapsed time, which nothing can stall. Keep both: the stamp
-count is the better signal when the pipeline is in use, and the date is the one that still works
-when it is not.
-
-**The stamp gap is itself a number worth printing.** A retro whose newest stamp is far behind the
-repository's newest release is telling you the retro is describing a smaller world than the one
-that shipped — the same failure `learned.md` rule 16 records for a work-list. State it beside the
-retro counts:
-
-```bash
-git tag --sort=-v:refname | head -1                    # newest release
-grep -m1 -oE '`[0-9a-f]{7,}`' docs/evidence/retro.md # newest stamped commit
-```
-
-Then the cap: **ten standing instructions, hard.** At eleven you do not get to keep
-them all — the oldest never-fired one goes. "But all of them matter" is precisely
-the state in which the list stopped being read, and the ninth stale rule is what
-discredits the two that are load-bearing.
-
-**Every deletion writes one line in the archive** — id, date, which trigger fired,
-and the commit. Silent deletion is forbidden: the record is what survives, the
-instruction is what leaves.
-
-**Print the counts beside the gate verdict**, the same way the carry-over ledger
-does ([`audit.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/audit.md) → *What can't be fixed now becomes a ratchet, never a TODO*):
-
-```
-GATE 10 acceptance: PASS — 14/14 REQ verified
-  carry-over: 0 unresolved · retro: 7 standing (was 9) · retired 3 · added 1
-  abstained: 2 · unlooked: 3
-  holds: 10 — none — enumerated 8/8 classes
-```
-
-A pruned list that nobody prints is a list that quietly grows back.
-
-## When the prune cannot run, say so — it is not the same as nothing to prune
-
-The prune retires a standing instruction against its triggers, and the cold trigger counts
-run stamps. Meeting a list whose rows carry **no id and no retirement condition**, the
-honest behaviour was undefined — so a careful run printed counts and stopped while a
-careless one could delete nine rules, and both looked like *the prune ran*.
-
-- **Backfill first, once.** On meeting rows with no id, the prune's first act is to mint
-  ids and propose a retirement condition per row **from the row's own text**, printed for
-  the operator to accept. One pass, and the trigger works forever after.
-- **`blocked` is a named outcome**, printed like any other: what could not be evaluated
-  and why. An undefined case is where the spread between two runs lives.
-- **A hard cap plus an unrunnable retirement condition is a deadlock.** Either the cap
-  yields until the backfill is done, or the backfill is a precondition of enforcing it —
-  but not both, and the file says which.
-
-## A fix to one call site closes a call site, not a class
-
-- **A fix other call sites will need is exported before it is used.** The test is
-  mechanical: if the same defect could exist in a second file, the fix does not stay
-  private to the first.
-- **Closing a defect includes a census of its siblings, by BEHAVIOUR rather than by a list
-  of names** — *every script that spawns a browser*, found by searching for the spawn, not
-  by remembering the five. A list of names is how the previous pass missed four of them.
-- **The entry states how many call sites the class had and how many were fixed.** *Fixed*
-  and *fixed in one of five* currently read identically, and only one of them closes a row.
-
-## The loop closes at stage 0
-
-The standing instructions are an **instruction source**, not background reading:
-[`knowledge-sources.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md) reads them in full at the harvest —
-they are short by construction — and records the file as a ledger row. Every
-instruction that actually *fires* during the run gets its **last-fired date and
-commit stamped** as it fires. That stamp is the only thing that makes the cold-rule
-honest; without it "five runs without firing" is a guess, and the prune becomes a
-mood.
-
-**The archive is queried at the same moment**, by the task's own nouns. It is the
-one source that answers *"have we been bitten by this class before?"* — and that
-question is worth asking precisely when the in-force list says nothing, because a
-rule that was retired for going cold is exactly the rule about to be re-learned.
-
-## Where a lesson goes when it is not about this project
-
-A lesson that would be true in any repository does not belong in one project's
-retro — it belongs in the pipeline's own doctrine
-([`learned.md`](learned.md), which is exactly that list, earned the same way). A local
-file that accumulates universal rules is a fork of the skill that nobody named.
-
-**This said *"open an issue upstream"* for eight releases and named no repository, no
-trigger and no authorization** — an instruction on rung 1 that everybody read as done.
-The rest of this section is the mechanism.
-
-## Recording to a shared lesson store, where the host has one
-
-**One job: let the next agent on another project read this lesson at its stage 0.** An
-entry whose class would be true in another project carries a `**Lesson:**` line — the class
-key, the class in one sentence, when it applies, 3–8 search nouns. That line makes it a
-*lesson* ([`lesson.schema.json`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/lesson.schema.json), lesson/1): with task-pipeline installed, its `scripts/lessons.py add` puts it in the
-local index every install has, and where the session lists a shared lesson store (an
-Observatory) it is also recorded there, as a proposal. An entry without the line stays
-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
-`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
-product's name, a title that states the class. `retro.publish` strips the whole origin.
-The read side is source 7b of [`knowledge-sources.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md). Where no store exists the run
-says `shared lessons: absent` rather than nothing.
-Mechanics and the read and write recipes: [`iteration.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/iteration.md) → *The learning loop*.
-
-## Publishing the insight — the skill learns from every project that runs it
-
-**One job: stop a lesson dying in the repository that learned it.**
-
-A retro entry is written per project and read by that project's next stage 0. The
-pipeline itself never sees it. So a defect in the **skill** — a gate that loops, a
-doctrine promising what nothing enforces, a rule firing on the wrong shape — is
-rediscovered independently in every project and fixed in none of them.
-
-**Opt-in, per project, off by default** — `pipeline.json` → `retro.publish`:
-
-```json
-"retro": {
-  "publish": {
-    "repo": "ssheleg/task-pipeline",
-    "label": "retro-insight",
-    "redact": "strict"
-  }
-}
-```
-
-Absent, nothing is published, and nothing is asked. **Silence arms nothing** — the same
-floor deploy authorization uses, and for the same reason: this is an **outward act**,
-and an outward act taken from a generic flag is an outward act nobody authorized
-([`continuity.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/continuity.md) → *The limit, before the capability*).
-
-**The body is printed in full before the issue is opened, every time.** Not a summary
-of it, not its title — the string that will be sent. The operator standing at stage
-10's manual gate is already reading; showing them what leaves the machine costs one
-block and is the only moment anyone can stop it.
-
-```
-── would open issue ──────────────────────────────────────────
-repo:  ssheleg/task-pipeline
-label: retro-insight
-title: [retro] a queue is not a diagnosis
-<the whole body, verbatim>
-──────────────────────────────────────────────────────────────
-opening…  → #24
-```
-
-**No `gh`, no network, no permission?** Print the body, say the issue was **not**
-opened, and carry the exact text in the carry-over ledger. That is the honest
-degradation; a second transport is not.
-
-## The improvement iteration — what happens to a published insight next
-
-Publishing is half a loop. An issue that is opened and never triaged is a lesson
-that cost a run and bought nothing, and a tracker full of those teaches everyone
-that publishing is where findings go to be filed.
-
-**The loop, and every arrow in it is somebody's obligation:**
-
-```
-a run diverges → a retro entry → retro.publish → an issue on the skill
-                                                        ↓
-   a board row ← measured against the tree ← triaged in a later cycle
-        ↓
-   doctrine + the guard that proves it → a release → the next run reads it
-```
-
-**Resolve what you worked, let the rest accumulate — visibly.** At the close of a
-cycle that consumed published issues:
-
-- **An issue closes when the behaviour changed**, not when the lesson was
-  understood (that is R-006, and it applies to issues exactly as it applies to
-  findings). The closing comment names **where** it landed — a file and a line —
-  and the guard that now holds it. A close with no address is a close nobody can
-  audit.
-- **An issue nobody worked stays open.** It is not triaged into silence, not
-  relabelled, not closed as stale. The pile is the queue, and its depth is the
-  honest measure of how far behind the doctrine is.
-- **Nothing is deleted.** A closed issue keeps its number, and the number is what
-  the CHANGELOG and the retro entry point at. Deleting one severs both, and the
-  cost lands on whoever next asks *why is this rule here*.
-
-**Where the queue comes from at the start of a cycle**, in this order: open issues
-published by any project running this skill, then the board's open rows by computed
-priority, then the open-questions register. A run that finishes its brief early
-takes the top of that list rather than inventing work — and a run that *cannot*
-take it says so, which is a fuller queue rather than a quiet one.
-
-**The measurement that keeps this honest.** Print, at the close: issues consumed,
-issues resolved with an address, issues left open. Three numbers, no floor, no
-target, and the third one rising is information rather than a failure — it means
-the projects running this skill are finding more than one cycle can absorb, which
-is what you want them to do.
-
-## What may leave the project — the redaction list
-
-An issue is a **public artefact in someone else's repository**. What travels is the
-*class*; what stays is everything that identifies where it happened. This list binds
-whatever leaves the estate, and every lesson too; *Recording to a shared lesson store*
-above names the one relaxation a lesson kept on this machine or estate gets.
-
-| Goes | Stays |
-|---|---|
-| the class of failure, stated in the abstract | the file, the function, the line it happened in |
-| which stage owned it and which stage surfaced it | the repository, organisation, branch or commit |
-| the doctrine or guard that missed it, by its name **in this skill** | any host path, absolute or relative |
-| the fix by grade, and the check that would catch it | the code, the config values, the data |
-| whether an existing standing instruction fired | any person, company, customer or product name |
-
-Five rules, numbered so a reader can point at one:
-
-1. **No host paths.** Only paths inside task-pipeline itself — `references/…`,
-   `templates/…`, `test/validate.py`. An absolute path names a machine.
-2. **No host identifiers**: repository, organisation, branch, commit, tag, issue or PR
-   number belonging to the project the run happened in.
-3. **No code, no configuration values, no data** — not a snippet, not a redacted
-   snippet. A shape can be described in a sentence.
-4. **No names**: person, company, customer, employer, product.
-5. **The title states the class, not the incident** — *"a queue is not a diagnosis"*,
-   never *"our export job looped"*.
-
-**The printed text and the sent text are one string.** Redacting after the print, or
-printing a cleaned-up version of what is actually sent, is the false-success shape this
-bundle names outright ([`gates.md`](gates.md) → *False success*): a mechanism reporting
-on itself rather than on what it did.
-
-**When in doubt the rule is subtraction, not judgement.** An insight that survives
-losing a detail is still an insight; a detail that leaks cannot be recalled from an
-index. If removing it makes the entry incomprehensible, the entry was about the project
-and not about the skill — keep it local.
-
-## Rationalizations
-
-| Excuse | Reality |
-|---|---|
-| "Nothing really went wrong this run" | Then the stamp says so in one line and you are done in ten seconds. The runs that "went fine" are where a repeated class hides — it never cost enough to remember. |
-| "I'll write the retro later, with a clear head" | Later is when you remember the outcome and not the seam. The cause is legible for about an hour after the run. |
-| "Don't delete it, it might still be useful" | That sentence is the entire failure mode. Every rule kept "just in case" spends attention that the load-bearing ones needed, and the file stops being read at all. |
-| "Pruning loses knowledge" | The Log keeps the incident forever; only the *instruction* leaves. If it recurs you get a grade-1 fix with its own history attached. |
-| "The list is at eleven but they're all important" | Then one of them is doctrine and belongs in `CLAUDE.md`, one has become a check, and one has not fired in a year. Ten is the budget precisely because ranking is uncomfortable. |
-| "I'll note it as a reminder for next time" | A note is grade 3 and expires in two runs. If it is worth remembering it is worth a check or a slot; if it is worth neither, it was never going to be read. |
+# Retrospective: pointer
+
+The retrospective doctrine has one home:
+[task-pipeline's `references/retrospective.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/retrospective.md).
+With the task-pipeline plugin installed, the same file sits beside this skill at
+`skills/task-pipeline/references/retrospective.md`. Until 1.98.0 this file was a
+34.7 KB copy of it with no delta of its own; a copy is a second thing to keep true.
+
+What evidence-docs relies on from it, in short:
+
+- **One file per project**, `docs/evidence/retro.md`, written as stage 10's last act:
+  stamp the run first, then prune, then write an entry only if the run diverged.
+- **The floor stage 0 reads in full** (standing instructions, max ten rows; run stamps,
+  max ten lines) stays under a 12 000-byte budget: a standing row at most 600
+  characters, a stamp at most 300. `scripts/retro_budget.py check` measures it.
+- **Every lesson carries its commit**, and every SHA must resolve from `HEAD`.
+- **Each entry names its Class and its Cost**; recurrence is counted by class.
+- **A universal rule is cited by its [`learned.md`](learned.md) number**, never
+  restated; a lesson standing in two projects goes upstream in the same run.
+
+evidence-docs-specific delta: none.

package/plugins/task-pipeline/skills/project-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-audit
-description: "Use when someone asks what is actually true of a whole project right now — what is finished, what is half-built, what is broken, and what nobody has looked at. Walks a cold start: discover what the project is, run a registry of probes chosen from that, read production evidence (published artefact against source, CI history, telemetry present or absent), then leave a JSON sidecar so the next audit can say what moved, and a self-contained HTML report on request. Read-only: it proposes board rows and commits nothing. Triggers - 'project audit', 'audit the project', 'codebase audit', 'state of the project', 'what is unfinished', 'project health check', 'аудит проекта', 'проаудируй проект', 'состояние проекта', 'что не доделано', 'аудит кодовой базы'. Not for: auditing one deliverable inside a run (that is the pipeline's own ladder), reviewing a diff, or checking a skill's construction — say 'без диагностики' to opt out."
+description: "Use when someone asks what is true of a whole project: finished, half-built, broken, unexplored ('project audit', 'аудит проекта'). Discovers the project, runs probes, reads production evidence, leaves a JSON sidecar, an HTML report on request. Read-only: proposes board rows, commits nothing. Not for: one deliverable inside a run, a diff review, a skill's construction; 'без диагностики' opts out."
 license: MIT
 compatibility: "The collector (scripts/audit.py) needs python3 and reads committed state, so it needs git. Probes needing gh, npm, network or a browser declare it and report blind when it is absent — degraded, never silent."
 ---
@@ -318,3 +318,10 @@ requested, not a fixed page-and-browser:
 | "Findings should just be fixed while I'm in there" | An audit that edits while it reads cannot re-run to check itself, and the next run cannot tell a fix from a rewording. |
 | "It's the same nine checks every time, so I can skip discovery" | Then the instrument returns the same answer for every input, which is a fact about the instrument and not about the project. |
 | "No findings — clean bill" | Only against the probes that ran. Read the blind list before saying that sentence out loud. |
+
+## Triggers
+
+The description is the short form. The full trigger list it carried until 1.98.0,
+moved here verbatim, still routes to this skill:
+
+"Use when someone asks what is actually true of a whole project right now — what is finished, what is half-built, what is broken, and what nobody has looked at. Walks a cold start: discover what the project is, run a registry of probes chosen from that, read production evidence (published artefact against source, CI history, telemetry present or absent), then leave a JSON sidecar so the next audit can say what moved, and a self-contained HTML report on request. Read-only: it proposes board rows and commits nothing. Triggers - 'project audit', 'audit the project', 'codebase audit', 'state of the project', 'what is unfinished', 'project health check', 'аудит проекта', 'проаудируй проект', 'состояние проекта', 'что не доделано', 'аудит кодовой базы'. Not for: auditing one deliverable inside a run (that is the pipeline's own ladder), reviewing a diff, or checking a skill's construction — say 'без диагностики' to opt out."