feat: stack development in three phases - stack-dev (design), stack-build, stack-close, handed over through tracker states (#168)
CI / verify (push) Successful in 5m15s
CI / pwsh (push) Successful in 2m2s
Release / release (push) Successful in 34s

stack-build and stack-close carry disable-model-invocation, so each phase change is
the operator's slash command; no skill offers a mid-session /model or /effort switch.
Mode rules and the phase table move to instructions/dev/stack-mode.md, publish and CI
waiting to instructions/dev/publish-and-ci.md, the ready definition to issue-tracking.md.

Files changed:
- AGENTS.md
- CHANGES.md
- DEVELOPMENT.md
- README.md
- VERSION
- docs/model-and-effort-selection.md
- instructions/CONTRACT.md
- instructions/dev/commonplace-kb.md
- instructions/dev/dev-setup.md
- instructions/dev/doc-pull-through.md
- instructions/dev/issue-tracking.md
- instructions/dev/publish-and-ci.md
- instructions/dev/stack-build/SKILL.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- instructions/dev/stack-mode.md
- instructions/dev/testing-conventions.md
- instructions/dev/version-parts.md
- tools/chemenu/commands/git_publish.py
- tools/chemenu/tests/test_git_publish.py
- tools/chemenu/tests/test_instructions_cmd.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
torbenandClaude Opus 5.5 committed 2026-10-02 20:33:07 +02:00
1 parent 80488bee38
commit d8224ee2ab
21 files changed
+631 -331

No files matched your search

+28 -1
View File
@@ -26,6 +26,7 @@ issues at that URL, which is exactly why `dist export` excludes
- [When to run](#when-to-run)
- [Steps](#steps)
- [Incoming stubs](#incoming-stubs)
- [Ready to build](#ready-to-build)
- [Renames and other decay in the tracker](#renames-and-other-decay-in-the-tracker)
- [Citing an issue in the repo](#citing-an-issue-in-the-repo)
- [What no tool checks](#what-no-tool-checks)
@@ -45,6 +46,8 @@ issues at that URL, which is exactly why `dist export` excludes
(§ Incoming stubs).
- **While working on one:** the body is updated as the state moves, not at the
end (step 2). A session that is interrupted leaves the body as its handover.
- Ending a design session, or starting a build from a body: check that it is
ready (§ Ready to build).
- Prioritising: deciding what to pick up next, or re-labelling after the ground
moved.
- Closing one: the body is rewritten to its final state first, and only then
@@ -310,6 +313,30 @@ no publish - it is tracker work, and several stubs can be worked out in one pass
What comes *after* it is an ordinary work package, picked up on its merits like
any other.
## Ready to build
A body is **ready** when a session that has never seen the design conversation can build from
it alone. That is the handover from design to build ([stack-mode.md](stack-mode.md) § The
three phases): `stack-dev` ends by checking it, and `stack-build` checks it again as its first
step. All four hold:
- **The body says what will be built**, and its acceptance criteria are checkable properties
(step 1), not activities.
- **No open question is left in it.** It carries `kind/build`, and neither `status/incoming`
nor `status/unconfirmed`. A question that is genuinely not blocking may stay, marked as such
and with the answer's consequence stated either way - "check X while building; if it does
not hold, do Y" is a decision, "X is unclear" is not.
- **The version part is named** ([version-parts.md](version-parts.md)). Whether a change is a
drop-in replacement is a judgment with no mechanical guard, so it is made while designing, not
discovered at the bump.
- **The files or surfaces involved are named**, so the build starts from the tree rather than
from a search for where the change belongs.
A body that fails one of these goes back to design. It is not built around: the gap a build
session fills on its own is the same gap a `status/incoming` stub leaves (§ Incoming stubs),
only better disguised. The useful side effect of the cut between the two phases is that it
tests this definition - if a cold session cannot build from the body, it was not ready.
## Renames and other decay in the tracker
A rename is not finished when the tree is green. Renaming a package, a path,
@@ -356,7 +383,7 @@ it in a `<!-- dist:strip-start/end -->` block ([instructions/CONTRACT.md](../CON
`tools/**/*.py` is deliberately outside all of this. A code comment addresses whoever edits that
line, and that only ever happens in the origin repo, because `dist export` prunes the
`stack-dev` skill together with this directory; a distributed `tools/` tree is runtime
`stack-` skills together with this directory; a distributed `tools/` tree is runtime
machinery, not reading material. The same holds for `.gitignore` and `tools/.coveragerc` -
config, not documentation.