torben/chemenu
1
1
Fork 0
Code Issues 26 Pull Requests Actions Packages Releases 32 Activity

stack-dev/stack-close skill split; publish stack-machinery note; model-selection fix (#47 Block 2)
CI / verify (push) Successful in 58s
Details
Release / release (push) Successful in 38s
Details

Browse Source 
Files changed:
- CHANGES.md
- VERSION
- instructions/claude-code-model-selection.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- tools/CONTRACT.md
- tools/chemenu/commands/git_publish.py
- tools/chemenu/tests/test_git_publish.py
This commit is contained in:
Torben Nehmer
2026-09-04 15:30:09 +02:00
parent 87a47cc237
commit d34924d640
8 changed files with 293 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
instructions/claude-code-model-selection.md
+6 -2
View File
@@ -74,8 +74,12 @@ to *make*, not a setting to apply.
switch at the moment the phase changes - once, without arguing about it, and never as a reason
to stop work that is already underway.
<!-- dist:strip-start -->
In this repo those moments are named: the `stack-dev` skill breaks for them at its steps 3
(design settled, work turns mechanical) and 6 (publish done, the unchecked tail begins).
In this repo those moments are named, one per skill rather than both in one: `stack-dev`'s own
step 3 breaks for the first (design settled, work turns mechanical), and `stack-dev` itself
ends at the publish rather than asking the same session to break out of its own momentum a
second time. The second switch lives at the opening of `stack-close`, the skill `stack-dev`
hands off to once the publish succeeds (the unchecked tail begins) - a session has to invoke
it to reach that step at all, which is the point: nothing left to skip past mid-flow.
<!-- dist:strip-end -->
2. **Pick a spawned subagent's model by what it does**, via the `Agent` tool's `model:`
instructions/dev/stack-close/SKILL.md
+102
View File
@@ -0,0 +1,102 @@
---
name: stack-close
description: Close out a stack-dev work package after its publish has landed - rewrite the issue body to its final state, check for docs/ staleness, and name which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed.
---
# Stack Close
**Purpose:** Carry out the unchecked closing phase of a stack-development work package, as its
own skill rather than a break `stack-dev` has to remember to ask for mid-flow.
**Trigger:** A `stack-dev` session's `tools/wikitool publish` just succeeded - `stack-dev` ends
there and hands off here rather than continuing into this phase in the same breath. Also: `publish`
printed its stack-machinery note ("this publish touched stack machinery...") and nothing has
closed the work package it belongs to yet; or a package was published in an earlier session and
never went through this skill (the gap this split exists to make impossible to skip past
silently - see [issue-tracking.md](../issue-tracking.md)'s note that a closed body is the version
everyone reads afterwards and nobody revisits).
**This directory is dev-only.** Same boundary as `stack-dev`
([its own note](../stack-dev/SKILL.md) has the full reasoning) - `dist export` prunes
`instructions/dev/` wholesale, so this skill never reaches a distributed instance.
## Why this is a separate skill, not `stack-dev`'s step 6
The two phases around the mechanical middle of a stack-dev session have no mechanical guard at
all - `pytest`, `docs verify` and `instructions verify` cover the code and tests in between, and
nothing covers a changelog entry's accuracy, a `docs/` page's staleness, or an issue body's final
state (see [claude-code-model-selection.md](../../claude-code-model-selection.md)). Asking the
same session to notice it has crossed into that second unchecked stretch - as a prose break inside
`stack-dev`'s own step 6 - failed twice in a row on this stack (Gitea #42, then #30): both times
the session knew the rule and skipped past it anyway, because nothing in the moment forced the
question. Splitting the phase into its own skill does not add a check either - `wikitool` still
does not know this tracker exists and must not learn (see
[issue-tracking.md](../issue-tracking.md) § What no tool checks) - but it removes the thing that
was actually failing: there is no longer a "next step" to skip past, only a skill nobody has
invoked yet. See Gitea #47 for the full incident history and the rejected alternative (a
model-switched subagent - not buildable in Claude Code, where a fork inherits the parent's model
and a fresh subagent starts without the session's context).
## Steps
1. **Offer the model switch back up, once, and keep working either way.**
> Ab hier greift kein maschineller Check mehr - Issue-Body, `docs/`-Veralterung und
> Changelog-Prosa prüft nichts. Wenn du zurück auf Opus willst, ist jetzt der Moment.
**Never block on the answer.** The change is already published; a session that stops here
leaves exactly the state this skill exists to prevent.
2. **Rewrite the issue body to its final state, then close.** The test is what a reader who
opens the closed issue tomorrow would conclude:
- every acceptance criterion ticked, or struck with the reason it was dropped
- proposals that were decided read as decided; a "to decide" section has become the decision
and its reasoning
- nothing left in the present tense about a defect that no longer exists
- what was verified is named - which checks ran, which CI run - not a commit hash alone
Then one short comment naming what changed against the previous state, and nothing else -
[issue-tracking.md](../issue-tracking.md) steps 2-3 and 7 have the full shape; this is that
procedure, run at the point this skill exists to guarantee it actually gets run.
**A closing report in a comment does not satisfy this**, however thorough: it reads as
complete to whoever writes it and leaves a body still phrased as open work. Nothing mechanical
catches it, which is why this is a step - and now a whole skill - rather than a habit. #44 and
#45 both closed exactly this way on the old, single-skill shape, the second an hour after the
rule was first written down.
3. **Check whether a `docs/` page or new human doc went stale.** A `docs/` page carries no
normative sentence, so nothing verifies it by construction (AGENTS.md § File naming) - the
same is true of `README.md`/`INSTALL.md`/`DEVELOPMENT.md` prose and a new instruction's own
wording, which `instructions verify` checks structurally but never for what it claims. If the
change this package shipped moved the reasoning one of these pages documents, update it now;
if none did, say so rather than leaving the question unasked.
4. **Name which model ran which phase - not only this one.** This is the handover in full, not
a note about the tail alone: state the model for the design/version-part/boundary-judgment
phase (`stack-dev` step 3), for the mechanical middle (code, tests, the version bump), and for
this closing phase - all three, even when they are all the same model. A handover that only
flags a cheap-model *closing* phase stays silent exactly when the earlier, equally unchecked
design phase also ran cheap and nobody offered the switch back then either; naming all three
every time is what keeps that omission from being the quiet default.
## Decision points
- **The work package spans several sessions?** Run this skill once, at the point the package is
actually finished and its last publish has landed - not after every individual publish. A
package still open across sessions keeps its body current per
[issue-tracking.md](../issue-tracking.md) step 2 in the meantime; that is maintenance, not
closing.
- **Resuming a package whose publish landed in an earlier, already-ended session?** Run this
skill now, on whatever model the current session is - do not reopen the earlier session to run
it "correctly." The handover in step 4 names the earlier phases from the historical record
(the issue's comments, `CHANGES.md`) rather than from memory.
- **Nothing to close - the session's own exploration, no publish happened?** This skill does not
apply; there is no package to rewrite a body for.
## Scope
Follows a `stack-dev` session's publish. Not for wiki content work - use
`wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/`wiki-status` for that, whose own closing
conventions (`kb/log.md`, page provenance) are unrelated to this tracker-body procedure.
instructions/dev/stack-dev/SKILL.md
+39 -48
View File
@@ -46,9 +46,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
package, labelled `area/`, `kind/`, `prio/` and `size/`. There is no `TODO.md`. **The body
of the issue you are working on is this session's plan file:** keep it current as the state
moves, so an interrupted session leaves a body the next one can resume from, *and* rewrite it
to its final state before closing. Both halves bind; the second is step 6 below. Read it
before filing something for later, before editing or closing an issue, or before deciding
what to pick up next.
to its final state before closing. Both halves bind; the second is what
[`stack-close`](../stack-close/SKILL.md) carries out once this skill's own work is published -
see step 5 below. Read it before filing something for later, before editing or closing an
issue, or before deciding what to pick up next.
[testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
empty machine; what the autouse fixture already neutralizes, and what a test still has to
establish itself. Read it before adding or changing a test.
@@ -63,14 +64,18 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
list grows without needing this skill file to change shape.
3. **Settle the design before building - and break there for the model switch.** These are two
different kinds of work, and the split is not stylistic: design, the version part and any
boundary judgment have **no** mechanical guard, while the code and tests that follow have
`pytest`, `docs verify`, `instructions verify` and CI behind them.
boundary judgment have **no** mechanical guard, while the code and tests that follow are mostly
covered - `pytest`, `docs verify`, `instructions verify` and CI catch a mistake **in what they
cover**.
So when the design is settled - the issue body says what will be built, the open questions are
answered - stop and say so, in one sentence:
answered - stop and say so, in one sentence that names what the mechanical stretch does **not**
cover:
> Der Plan steht, ab hier ist die Arbeit mechanisch und durch Tests/CI abgedeckt. Wenn du auf
> Opus bist, ist jetzt der Moment für `/model sonnet` bei Effort `high`.
> Der Plan steht, ab hier ist die Arbeit größtenteils mechanisch und durch Tests/CI abgedeckt -
> mit Ausnahme der Changelog-Prosa (Schritt 4), einer berührten `docs/`-Seite, neuer
> Menschendoku oder des Prosa-Anteils einer Instruction. Wenn du auf Opus bist, ist jetzt der
> Moment für `/model sonnet` bei Effort `high`.
**You cannot make this switch yourself** - the session's model is the user's `/model`, not a
setting an agent applies. Offer it once and keep working either way; a session that argues
@@ -78,6 +83,15 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
be settled after all - a boundary crossing surfaces, an assumption breaks - that is a reason to
offer the switch back up, not to decide it alone.
**"Covered by tests" means covered by the tests that exist, not by the tests that should
exist.** Whether the right test was written is itself a judgment call with no mechanical
guard: two data-destroying bugs in `upstream merge` (Gitea #30) shipped past a green
`pytest`/`docs verify`/`instructions verify`/CI because no test exercised the case, not
because a weaker model wrote worse code for the case that *was* tested. This is not a third
break - it is a caveat on this one: the middle phase stays the cheaper phase to run on, but its
test suite is only as complete as the judgment that wrote it, and that judgment is unchecked
the same way the design phase is.
Effort is the cheaper lever than the model, and `high` is the floor for anything touching more
than one file or a contract. Full table and reasoning:
[claude-code-model-selection.md](../../claude-code-model-selection.md).
@@ -119,47 +133,23 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
Prose-only changes (`README.md`, `INSTALL.md`, `EVALS.md`) and the workflows under `.gitea/`
do not need a bump - CI's version gate is scoped to what changes behaviour.
5. **Verify before publishing.** `tools/wikitool docs verify`, `tools/wikitool instructions
verify`, and the relevant `pytest` run in `tools/` - the same checks any stack change must
pass, run explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a
full `setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves
`VERSION` additionally triggers a tagged release. **CI does the tagging** - a session never
creates a tag, which is what keeps AGENTS.md invariant 5 intact.
5. **Verify, then publish.** `tools/wikitool docs verify`, `tools/wikitool instructions verify`,
and the relevant `pytest` run in `tools/` - the same checks any stack change must pass, run
explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a full
`setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves `VERSION`
additionally triggers a tagged release. **CI does the tagging** - a session never creates a
tag, which is what keeps AGENTS.md invariant 5 intact.
6. **Close the issue with a body rewrite, not a comment.** The last act of a session that
finished a work package, and the one most easily skipped: by here the change is published and
the issue feels done. It is not. The body is the version everyone reads afterwards and nobody
revisits, so it is the one place the debt comes due at the worst moment.
Publish with `tools/wikitool publish`. When the changeset touches `tools/`, `types/`,
`instructions/`, `AGENTS.md` or a `<stage>/CONTRACT.md`, `publish` itself prints a one-line
reminder that the phase past this point is not covered by any of the checks above - that line
is the cue that this skill's own job just ended.
**Break here too, in the other direction.** Everything left in the session - this rewrite,
whether a `docs/` page's reasoning went stale, the changelog prose - is the unchecked kind of
work again, the mirror of step 3. If the session dropped to Sonnet there, say so now:
> Ab hier greift kein maschineller Check mehr - Issue-Body, `docs/`-Veralterung und
> Changelog-Prosa prüft nichts. Wenn du zurück auf Opus willst, ist jetzt der Moment.
Then **do the work regardless of the answer.** Never block a close on a model switch: the
change is already published, and a session that stops here leaves exactly the state this step
exists to prevent. If it ran on the cheaper model, name that in the handover rather than
leaving it silent.
Rewrite it to its final state *first*, then close. The test is what a reader who opens the
closed issue tomorrow would conclude:
- every acceptance criterion ticked, or struck with the reason it was dropped
- proposals that were decided read as decided; a "to decide" section has become the decision
and its reasoning
- nothing left in the present tense about a defect that no longer exists
- what was verified is named - which checks ran, which CI run - not a commit hash alone
Then one short comment naming what changed against the previous state, and nothing else.
**A closing report in a comment does not satisfy this**, however thorough: it reads as
complete to whoever writes it and leaves a body still phrased as open work. Nothing
mechanical catches it - `wikitool` does not know this tracker exists and must not learn it,
since it ships to instances that have no board - so this step is the only enforcement there
is. #44 and #45 both closed exactly this way, the second an hour after the rule was written.
[issue-tracking.md](../issue-tracking.md) step 7 has the full shape.
**This skill stops here.** The closing phase - rewriting the issue body to its final state,
checking for `docs/` staleness, and naming which model ran which phase of the session - lives
in [`stack-close`](../stack-close/SKILL.md), not in a further step of this one. Invoke it now;
do not fold its work into this session under this skill's rules, and do not treat "the change
is published" as this work package being done.
## Decision points
@@ -180,4 +170,5 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
Not for wiki content work - use `wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/
`wiki-status` for that. Not for setting up a new instance (`instructions/setup-instance.md`) or
a fresh clone of this repo (`instructions/bootstrap.md`).
a fresh clone of this repo (`instructions/bootstrap.md`). Not for closing a work package after
its publish has landed - that is [`stack-close`](../stack-close/SKILL.md).