geneseed 3.3.0 → 3.5.0

package/src/skills/develop.md

@@ -2,28 +2,46 @@
 
 > {{DESC_DEVELOP}}
 
-**Trigger:** implementing a feature, fixing a bug, or changing code behaviour in a repo that has (or should have) a test suite.
+**Trigger:** implementing a feature, fixing a bug, or changing code behaviour in a
+repo that has (or should have) a test suite — before writing implementation code.
+Covers both the test-first cycle (red → green → refactor) and the cover-alongside
+case where the seam is only known once the change is made.
 
 ## Procedure
-1. Orient on the project's own documentation for what you are about to touch ({{DOCTRINE}} process 4).
-2. Make the smallest change that advances the task ({{DOCTRINE}} craft 6).
-3. Cover the behaviour — test-first via the [tdd {{SKILL}}](tdd.md) where the target is known up front; otherwise write the covering test alongside the change ({{DOCTRINE}} rigor 3).
-4. Run the *affected* tests and read the output ({{LAW}} III); on failure, fix the cause, do not mask it ({{LAW}} VIII).
-5. Tidy the green code via the [refactor {{SKILL}}](refactor.md) — the tests are your safety net.
-6. Commit the green slice via the [commit {{SKILL}}](commit.md) ({{DOCTRINE}} process 5). Loop one slice at a time; dispatch the [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for heavier or unfamiliar coverage.
+1. Orient on the project's own documentation for what you are about to touch
+   ({{DOCTRINE}} process 4), and confirm the actual starting state — the suite runs,
+   the baseline is green ({{LAW}} III). A red baseline is a [debug {{SKILL}}](debug.md)
+   task first, not something to build on.
+2. Agree the seams: name the public interfaces the tests will target and confirm
+   them with the user when they are not obvious — no test is written at an
+   unconfirmed seam. Testing effort belongs on critical paths and complex logic,
+   not every edge.
+3. Pick the next **smallest slice** that advances the task ({{DOCTRINE}} craft 6), then
+   cover it:
+   - *Seam known up front* — test-first. Write ONE failing test that pins the slice,
+     specific about the expected output (for a bug, the test reproduces it). Run it
+     and watch it fail **for the right reason** — a test that passes immediately, or
+     fails on a typo, proves nothing.
+   - *Seam only clear once the change exists* — write the covering test alongside the
+     change ({{DOCTRINE}} rigor 3), then break the implementation on purpose once to
+     see the test go red before trusting it.
+4. Write the minimum code that makes it pass; add nothing the test doesn't demand.
+5. Run the *affected* tests and read the output ({{LAW}} III); on failure fix the
+   cause, never mask it ({{LAW}} VIII). Dispatch the
+   [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for heavier or unfamiliar coverage,
+   or when the blast radius is unclear.
+6. With the slice green, tidy through the [refactor {{SKILL}}](refactor.md) — the tests
+   are the safety net — then commit the slice through the [commit {{SKILL}}](commit.md)
+   ({{DOCTRINE}} process 5). Loop from step 3, one slice at a time.
+7. **Exit.** When the last slice is in: run the whole affected suite once more, state
+   what was run and its result, and hand over — to the [ship {{SKILL}}](ship.md) when
+   the change is ready for a PR, or to the [handoff {{SKILL}}](handoff.md) if the
+   session ends mid-task. Leave no slice uncommitted and no test you could not make
+   fail.
 
 ## Done when
-- The behaviour changed is covered by tests written this session, the affected suite is green with its output shown, and each slice was committed.
+- Every behaviour changed is covered by a test written this session that was seen
+  to fail before it passed, the affected suite is green with its output shown, each
+  slice was committed on its own, and the work has been handed to ship or handoff.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/document-project.md

@@ -65,15 +65,4 @@ into line with the implementation.
   them all; the single-file `overview.html` opens offline and shows both the digest and the
   complex-core deep-dives; and any surface left undocumented is named explicitly.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/domain-modeling.md

@@ -24,15 +24,4 @@ decision, or a design conversation keeps stumbling over ambiguous terms.
 - The glossary and ADRs reflect every term and decision that crystallised this
   session, and no two names compete for one concept.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/forge-mcp.md

@@ -35,15 +35,4 @@ depends on it.
 - The server builds, every tool passes the Inspector, and the evaluation
   questions are answered correctly through the tools — not by guesswork.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/fresh-eyes.md

@@ -15,15 +15,4 @@
 ## Done when
 - A fresh context that never saw the solving session derived the acceptance criteria from the original task alone, froze them before seeing the artifact, ruled each PASS/FAIL/UNVERIFIABLE with evidence by checking the live artifact, and returned an overall gate (SATISFIES / SATISFIES-WITH-GAPS / DOES-NOT-SATISFY) for the user to weigh — or, where no true isolation was possible, the verdict is stamped soft-isolation so it is discounted.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/frontend-design.md

@@ -44,15 +44,4 @@ preview tool) — the second-pass critique in step 6 cannot run without one.
   templated tells, holds the accessibility floor, and a screenshot critique finds
   nothing that reads as a generic default.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/geneseed-code-review.md

@@ -14,20 +14,13 @@
 5. Pass 3 — spec fidelity: compare the diff against the task or issue from
    step 1; flag anything asked for but missing, and anything present that was
    never asked for. No spec available → say so and skip the pass.
-6. Write each finding as `file:line — problem — fix`, correctness first.
+6. Write each finding as a Conventional Comment, `label (decoration): file:line — problem — fix`,
+   correctness first. Labels: issue, suggestion, question, todo, nitpick, thought, note,
+   praise. Decorations: blocking, non-blocking, if-minor. The line pastes straight into a
+   merge-request comment, and a reader can filter on the label without reading the prose.
 
 ## Done when
-- Findings are reported with a clear verdict: ship / fix-then-ship / block.
+- Findings are reported with a verdict that follows from the decorations: any `blocking`
+  finding → block; any `if-minor` and nothing blocking → fix-then-ship; otherwise ship.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/geneseed.md

@@ -15,15 +15,4 @@
 ## Done when
 - The user's question about the deployed harness is answered from the live install — file paths or CLI output — not from recall.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/git-archaeology.md

@@ -33,15 +33,4 @@ or rewrite, use git-rescue.md; to write a new commit, use commit.md).
 - The question is answered with a specific commit (or commits) and the diff/output that
   proves it, the bisect state is reset, and the working tree is unchanged.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/git-rescue.md

@@ -54,15 +54,4 @@ finding *when/why* something changed without altering history, use git-archaeolo
 - The repository is in the intended state, verified against actual git output, and the
   pre-rescue state is still recoverable from the backup branch or the reflog.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/handoff.md

@@ -15,15 +15,4 @@
 ## Done when
 - A fresh agent can resume from the worklog alone — goal, progress, next step, and blockers are all written down.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/herdr.md

@@ -151,15 +151,4 @@ herdr pane read 1-1 --source recent --lines 100
 
 The task that motivated the side pane is finished, its output has been read (or its result captured), and any pane / tab / workspace you opened just for the task has been closed — unless the user asked you to keep it.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/ingest.md

@@ -36,15 +36,4 @@ must be converted first.
 - The document's content is available as markdown and the slice the task needs has
   been read — without reading the binary or committing a stray conversion.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/migrate.md

@@ -31,15 +31,4 @@ change into the same deploy as the code that depends on it (universal {{LAW}} II
   changelog / lockfile reflect the new state with its docs updated
   ({{DOCTRINE}} craft 3).
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/opencode-theme.md

@@ -39,15 +39,4 @@ them at `--theme` / the setup wizard, not this {{SKILL}}.
 - Both `<name>.json` (and/or `<name>-transparent.json`) exist in the active themes dir,
   the CLI reported the path, and the user knows the `/theme <name>` command to select it.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/parallel-agents.md

@@ -5,24 +5,13 @@
 **Trigger:** two or more independent subtasks with no shared state or ordering between them — and a tool that can run subagents.
 
 ## Procedure
-1. Confirm independence: the subtasks must not depend on each other's output or write the same files. If they're sequential or share state, use [plan](plan.md) instead.
+1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE}} process 8). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
 2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return.
-3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its output contract, and the inherited constraints (no commit/push — {{DOCTRINE}} process 5 stays with you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW}} VII). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE}} process 3). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
+3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE}} process 5 stays with you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW}} VII). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE}} process 3). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
 4. Keep the main context lean: collect each subagent's distilled result, not its working transcript.
-5. Converge: reconcile the results, resolve conflicts yourself, and verify the combined outcome.
+5. Converge: compare each unit's changed files against its write set and against its siblings' — an edit outside the set or a file two units touched is a conflict you resolve before anything else — apply the shared-file rows yourself, then verify the combined outcome.
 
 ## Done when
 - Independent units ran concurrently, each returned a distilled result, and the reconciled outcome is verified.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/pipeline.md

@@ -16,37 +16,26 @@ The minimum roster per task type. The parent may add specialists on top — secu
 |---|---|
 | Development | [explorer](../{{DIR_AGENTS}}/explorer.md) (analyst) → [developer](../{{DIR_AGENTS}}/developer.md) → [tester](../{{DIR_AGENTS}}/tester.md) + lint gate |
 | Documentation | [explorer](../{{DIR_AGENTS}}/explorer.md) (analyst) → [docs](../{{DIR_AGENTS}}/docs.md) |
-| Research / investigation | [explorer](../{{DIR_AGENTS}}/explorer.md) (analyst) alone |
+| Research / investigation | [explorer](../{{DIR_AGENTS}}/explorer.md) (analyst) alone; add [researcher](../{{DIR_AGENTS}}/researcher.md) when the question leaves the repository |
 | Review / audit | [reviewer](../{{DIR_AGENTS}}/reviewer.md) + [skeptic](../{{DIR_AGENTS}}/skeptic.md) |
 
 ## Procedure
 
 1. Confirm the task is genuinely substantial — a trivial one-file tweak or a question does not warrant a crew; do it directly instead.
 2. Compose the crew from the floor above, adding specialists only where the task demands them.
-3. Isolate the crew's work in its own git worktree/branch (the SETUP.md worktree add-on). Where worktrees are unavailable, fall back to a single tree, one pipeline at a time, and say so.
+3. Isolate the crew's work in its own git worktree/branch (the SETUP.md worktree add-on). Where worktrees are unavailable, fall back to a single tree, one pipeline at a time, and say so. Give the crew a **write set** and check it against every other pipeline in flight ({{DOCTRINE}} process 8): two crews whose sets overlap do not run at once, and shared append files (registries, index tables, lockfiles, generated bundles) are the parent's to apply, never a crew's.
 4. **The dev↔tester loop:** the developer implements, the tester validates — runs the tests and lint, produces raw logs. On failure, the findings go back to the developer. Cap at **5** iterations; on exhaustion, stop, do not merge, and report the failure with the branch left in place for inspection.
 5. **Two execution shapes**, chosen by host capability (same pattern as the [workflow {{SKILL}}](workflow.md)):
    - *Deterministic:* where the host exposes a `workflow` tool, run a saved script encoding analyst → developer → (tester ⇄ developer)×≤5 → proof.
    - *Model-driven fallback:* everywhere else, run the same stages via the [parallel-agents {{SKILL}}](parallel-agents.md) or sequential personas, with the same handoff envelopes and the same delivery contract.
-6. On success, attach the mechanical proof to the branch (test + lint output, exit codes) and hand the result back to the parent for the merge decision — the pipeline never commits, pushes, or merges on its own ({{DOCTRINE}} process 5).
+6. On success, hand the worktree back to the parent uncommitted, with the mechanical proof (test + lint output, exit codes) and the list of files it changed in the result envelope, rebased on the current base so a conflict with a sibling resolves on the crew's branch. The pipeline never commits, pushes, or merges ({{DOCTRINE}} process 5): the parent re-runs the proof commands itself, shows the user the diff and the output, and commits and merges once the user accepts.
 
 ## Delivery contract
 
-A branch/worktree containing the work **plus** the mechanical proof: test and lint output with exit codes, either committed alongside the run's notes or handed back in the result envelope. Anything without green proof is surfaced, never merged — merging on proof (not re-verification) is only sound because every {{AGENT}} in the crew inherits all {{LAWS}} through the handoff envelope.
+A worktree containing the work, uncommitted, **plus** the mechanical proof in the result envelope: test and lint output with exit codes. Anything without green proof is surfaced, never merged. The crew's proof is what the parent re-runs, not what it trusts: a log is an account of the state, and the gate that decides the merge runs against the state itself.
 
 ## Done when
 
-- Green proof: the crew delivered a branch with passing tests and lint, and the parent merged it — or the loop cap was exhausted and the failure was reported with the branch left in place.
+- Green proof: the crew delivered a worktree whose tests and lint the parent re-ran green, and the user accepted the commit and merge — or the loop cap was exhausted and the failure was reported with the branch left in place.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/plan.md

@@ -31,15 +31,4 @@
 > place after the window fills, and lets the user correct course early. Consider
 > git-ignoring `WORKLOG.md` if it should stay local to each developer.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/ponytail.md

@@ -15,15 +15,4 @@
 ## Done when
 - The shipped solution sits on the highest ladder rung that works, deliberate shortcuts carry a `ponytail:` comment with their upgrade path, non-trivial logic has one runnable check, and nothing on the never-simplify list was cut.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/profile.md

@@ -44,15 +44,4 @@ as creation, and never discard a section the user wrote by hand.
   `user-rules.md` or {{MEMORY}} instead — or the user declined, and the file is
   untouched.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/prose.md

@@ -28,15 +28,4 @@ person wrote it, not a model.
 - The text says what it means in the fewest honest words, carries no AI tells,
   and would pass as written by a careful human.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/prototype.md

@@ -30,15 +30,4 @@ real implementation.
 - The question has a recorded verdict, the decision lives in the real code,
   and no prototype code remains on the main branch.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/quiz.md

@@ -0,0 +1,43 @@
+# {{SKILL}}: quiz
+
+> {{DESC_QUIZ}}
+
+<!-- invocation: user -->
+
+**Trigger:** the user wants what they know *tested*, not explained — "drill me on X",
+"quiz me until it sticks", "let me explain X to you and catch me", "I think I already
+know X, prove me wrong", "find the holes in what I know". Three shapes, picked from the
+ask: a **drill** (practise until reflex), a **feynman** (explain it back, get caught on
+the stumbles), or a **gap check** (a mastery claim stress-tested). To be taught instead,
+use the [teach {{SKILL}}](teach.md).
+
+## Procedure
+1. Pin the concept and set the contract plainly: you will test, not lecture, and you
+   will not go easy. Do not explain the concept up front.
+2. Pick the shape and run it:
+   - **Drill** — drop the user straight into a realistic situation where they would
+     have to use the concept and would probably slip. On a mistake, withhold the
+     answer; ask the one question that forces them to find where their own reasoning
+     broke. Reveal only after two honest attempts. New situation each cycle, until they
+     get it right without hesitation.
+   - **Feynman** — have them explain the topic as if teaching a ten-year-old.
+     Interrupt the moment they (a) use jargon they cannot themselves unpack, (b) skip
+     a step in the reasoning, or (c) simplify so far the explanation becomes wrong —
+     name which of the three it was each time, and keep them going to the end.
+   - **Gap check** — ask five questions that look simple but separate someone who
+     has gone deep from someone who skimmed: edge cases, the *why*, the assumption
+     under the rule, the case where the standard answer breaks. After each answer say
+     plainly what it reveals is still missing; a shallow answer is named as shallow,
+     with what depth would have looked like.
+3. Close with the honest readout, no flattery: what the stumbles or misses reveal is
+   not yet solid, what to restudy, and — for a drill — the variation most likely to
+   catch them out next. Offer the [teach {{SKILL}}](teach.md) for the gaps that need
+   teaching rather than more testing.
+
+## Done when
+- The user worked the situation correctly without being handed the answer (drill),
+  explained the topic through with every stumble caught and labelled (feynman), or
+  answered all five questions and holds a concrete verdict on the remaining gaps (gap
+  check) — and the run ended with a direct readout, never empty praise.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/react-view-transitions/VENDOR.md

@@ -8,9 +8,15 @@ listed in the generator's `VENDORED_SKILL_DIRS`.
 - **Upstream:** https://github.com/vercel-labs/agent-skills/tree/main/skills/react-view-transitions
 - **Commit:** f8a72b9603728bb92a217a879b7e62e43ad76c81
 - **Author:** Vercel Engineering
-- **License:** MIT (https://github.com/vercel-labs/agent-skills — `## License` → MIT)
+- **License:** MIT (https://github.com/vercel-labs/agent-skills — `## License` → MIT).
+  Upstream ships no LICENSE file (neither at the pinned commit nor on `main`), so there
+  is no license text to carry here; the README's declaration is the whole grant.
 
 The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md` +
 `references/`). Its internal links point at the upstream project's own files; do not
 "fix" them to Geneseed paths — that is why the folder is gate-exempt. To update,
 re-copy the upstream folder and bump the commit above.
+
+**Deliberately not copied:** upstream's `README.md` (the repo-facing readme: install
+command and folder tree, nothing an agent reads). `AGENTS.md`, upstream's compiled
+all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it.

package/src/skills/refactor.md

@@ -18,15 +18,4 @@
 ## Done when
 - Structure is improved, observable behaviour is unchanged, tests are green, and the refactor is committed by itself.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/release.md

@@ -29,15 +29,4 @@
 - Version, changelog, and tag all name the same number, and the release is pushed
   (or staged for the pipeline) with no unrelated changes bundled in.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/repo-map.md

@@ -22,15 +22,4 @@
 - `ARCHITECTURE.md` reflects the current structure, and a fresh agent could orient
   from it in a single read.
 
-## Self-improvement
-
-Close each run with one beat of reflection on the {{SKILL}} itself:
-- A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW}} II).
-- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
-  clears {{DOCTRINE}} process 1's bar: it would change how a future session behaves, and a
-  fresh read of the repo would not re-derive it. Update an existing memory over
-  adding one; when in doubt, leave it out.
-- No friction, nothing learned — move on; this loop earns no ceremony. Most
-  runs end here.
+<!-- INCLUDE: skills/_self-improvement.md -->