stack: TOC-Scope auf types/ und docs/, Sprachregeln nach AGENTS.md zentralisiert, alle Templates auf Control-Plane-Sprache, --breaking akkumuliert (schliesst #99)
Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
This commit is contained in:
@@ -40,7 +40,24 @@ touched; a row that does not apply needs no action.
|
||||
| The reasoning behind a gate, boundary, or design decision | The `docs/` page that carries it, if one exists (AGENTS.md § File naming lists all four) |
|
||||
| A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/` |
|
||||
|
||||
3. **Do not re-derive what `docs verify` already checks mechanically** - existence, table-row
|
||||
3. **A heading you changed means a table of contents to regenerate - by the tool, never by
|
||||
hand.** Every reference file over 100 lines carries one (`AGENTS.md`, the stage contracts,
|
||||
`kb/CONVENTIONS.md`, each `COLLECTION.md`, the flat `instructions/**.md` form, the
|
||||
type-specs, the `docs/` pages - a `SKILL.md` is the one exception). Adding, renaming,
|
||||
reordering or deleting a `##`/`###` heading in one of them makes its region stale, and
|
||||
`docs verify` fails on stale exactly as it fails on missing:
|
||||
|
||||
```bash
|
||||
tools/wikitool docs toc # dry run: which files would change
|
||||
tools/wikitool docs toc --apply # write them
|
||||
```
|
||||
|
||||
The region is generated, so AGENTS.md invariant 1 applies to it like any other: editing the
|
||||
list by hand is the failure, not the fix - and a hand-written entry survives until the next
|
||||
`--apply` silently disagrees with it. It is cheap to over-run: `--apply` is idempotent and a
|
||||
file whose headings did not move is left untouched.
|
||||
|
||||
4. **Do not re-derive what `docs verify` already checks mechanically** - existence, table-row
|
||||
membership, ignore-canary state. That enumeration lives once, in
|
||||
[tools/CONTRACT.md](../../tools/CONTRACT.md)'s own `docs verify` row; copying it here would be a
|
||||
second copy that drifts, the exact failure this instruction exists to describe (Gitea #90).
|
||||
|
||||
@@ -48,10 +48,12 @@ and a fresh subagent starts without the session's context).
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Offer the model switch back up, once, and keep working either way.**
|
||||
1. **Offer the model switch back up, once, and keep working either way.** A model of the
|
||||
message, not a script to quote: say it in the instance's KB language, per `AGENTS.md`
|
||||
§ File naming.
|
||||
|
||||
> 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.
|
||||
> From here on no mechanical check applies - nothing verifies the issue body, `docs/`
|
||||
> staleness, or the changelog prose. If you want to switch back to Opus, now is the 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.
|
||||
@@ -86,6 +88,11 @@ and a fresh subagent starts without the session's context).
|
||||
behaviour one of these documents describes, update it now; if none did, say so rather than
|
||||
leaving the question unasked.
|
||||
|
||||
**If that update moved a `##`/`###` heading, the file's table of contents is now stale** -
|
||||
regenerate it with `tools/wikitool docs toc --apply`, never by editing the list. The region
|
||||
is generated (AGENTS.md invariant 1), `docs verify` fails on stale exactly as on missing, and
|
||||
a pull-through in this phase is a common way to move a heading without noticing.
|
||||
|
||||
**A pull-through of its own needs its own bump.** This phase runs *after* `stack-dev` step 4
|
||||
has already bumped the version, and the documents it touches are frequently the ones CI's
|
||||
version gate watches - `types/`, `instructions/`, `tools/`, `AGENTS.md`, any
|
||||
|
||||
@@ -76,12 +76,13 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
|
||||
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 that names what the mechanical stretch does **not**
|
||||
cover:
|
||||
cover. The message below is a model of what to say, not a script to quote: say it in the
|
||||
instance's KB language, per `AGENTS.md` § File naming.
|
||||
|
||||
> 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`.
|
||||
> The plan is settled. From here the work is mostly mechanical and covered by tests/CI -
|
||||
> except the changelog prose (step 4), any `docs/` page you touch, new human-facing
|
||||
> documentation, and the prose half of an instruction. If you are on Opus, now is the moment
|
||||
> for `/model sonnet` at 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
|
||||
@@ -146,7 +147,13 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
|
||||
5. **Pull through every document that makes a claim about the surface you touched - `docs verify`
|
||||
checks a cell's presence, never its prose.** `instructions/dev/doc-pull-through.md` has
|
||||
the table of which document that is, per surface.
|
||||
the table of which document that is, per surface, and its step 3 for the one part of the
|
||||
pull-through that is *not* prose: a reference file whose headings moved needs
|
||||
`tools/wikitool docs toc --apply`, never a hand-written list.
|
||||
|
||||
Prose you write here is English, whatever language the session is being held in -
|
||||
`AGENTS.md` § File naming has both language rules and the line between prose and quoted
|
||||
vocabulary.
|
||||
|
||||
6. **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
|
||||
|
||||
@@ -66,7 +66,12 @@ a new one, and only `version release` turns it into something the release workfl
|
||||
|
||||
1. **Heading, author, breaking/migration lines** - written by `version bump`, anchored right
|
||||
above the bump list so the line an operator most needs to act on never sits beneath a list
|
||||
that can run long.
|
||||
that can run long. The breaking line **accumulates** across a candidate's crossings - one
|
||||
reason on the marker line, bullets under a bare marker from the second onward - because a
|
||||
long-running candidate can break compatibility more than once and each break is its own
|
||||
thing to act on. The migration line does not: it answers one yes/no about the candidate as
|
||||
a whole, and `--migration-required` is its retraction path. Nothing retracts a breaking
|
||||
reason; a wrong one is rare enough, and the candidate is dev-local until release.
|
||||
2. **The bump list**, grouped `**High/Medium/Low impact**` (empty groups omitted) - rendered by
|
||||
`version bump`'s `--impact` (default `medium`), corrected after the fact by `version regrade`.
|
||||
Flat and ungrouped, exactly as before this layering existed, when every bump is `medium` - the
|
||||
|
||||
Reference in New Issue
Block a user