stack-dev/stack-close skill split; publish stack-machinery note; model-selection fix (#47 Block 2)
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:
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user