fix(docs): AGENTS.md-Contract-Prosa als Sitzungsarbeit klargestellt, doc-pull-through-Instruction (schliesst #90)
Files changed: - AGENTS.md - CHANGES.md - VERSION - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - tools/chemenu/commands/docs_verify.py
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: doc-pull-through
|
||||
description: Which document makes a claim about a surface you are about to change - a wikitool command's behaviour, a stage's rules, an AGENTS.md rule/gate/invariant, a README-shaped human doc, a docs/ page's reasoning - and so needs updating in the same session, since tools/wikitool docs verify never reads a cell's prose.
|
||||
---
|
||||
# Update every document that makes a claim about the surface you changed
|
||||
|
||||
`tools/wikitool docs verify` is a hard oracle over presence, not content: it checks that a
|
||||
command is *listed*, that a contract *exists*, that an ignore canary is (or isn't) caught - never
|
||||
what a table cell, a contract section, or a README paragraph actually *says*. A command's flag
|
||||
can change, a gate's threshold can move, a contract's wording can go false, and every one of
|
||||
those checks stays green (Gitea #90; Gitea #91 narrows what the command-table check matches, but
|
||||
adds no reading of cell content). Content quality of every document below is therefore session
|
||||
work, the same duty AGENTS.md's Changelog section states for `README.md`/`EVALS.md`/
|
||||
`tools/README.md` - this instruction exists because that duty used to stop at those three files
|
||||
while the contracts rotted next to a green check (ten stale error-contract rows accumulated this
|
||||
way; see Gitea #89 for one).
|
||||
|
||||
## When to run
|
||||
|
||||
Before `tools/wikitool docs verify`/`publish` in a `stack-dev` session that changed behaviour -
|
||||
`stack-dev` step 5 sends you here. Read the table below and update every row whose surface you
|
||||
touched; a row that does not apply needs no action.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Name the surface(s) you changed.** A `wikitool` command's flags or behaviour, a stage's
|
||||
rule, an `AGENTS.md`-level rule/gate/invariant, a workflow a human runs by hand, or the
|
||||
reasoning behind a design decision - one change can touch more than one row.
|
||||
|
||||
2. **For each surface, update every document the table names - not only the one you were already
|
||||
editing:**
|
||||
|
||||
| Touched surface | Document(s) that make a claim about it |
|
||||
|---|---|
|
||||
| A `wikitool` command's behaviour, flags, or interface | Both tables in [tools/CONTRACT.md](../tools/CONTRACT.md): the command reference row, and its per-command error contract (exit codes, atomicity, retry-safety) |
|
||||
| A stage's authoring rules (`raw/`, `kb/`, `types/`, `reports/`, `work/`, `tools/`, `instructions/`) | The touched `<stage>/CONTRACT.md` |
|
||||
| A rule, gate, or invariant `AGENTS.md` itself states | The relevant `AGENTS.md` section (Invariants, Gates, File naming, Routing, ...) |
|
||||
| A workflow, stage, or command a human operates by hand | Whichever of `README.md`, `EVALS.md`, `tools/README.md`, `INSTALL.md`, `DEVELOPMENT.md` names it - AGENTS.md § File naming says which document is for which reader |
|
||||
| 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
|
||||
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).
|
||||
This instruction is only about the prose no check reads.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **The change touched no document in the table?** Nothing to do - not every stack change moves
|
||||
a claim. A pure bugfix with an unchanged interface is the common case.
|
||||
- **Unsure whether a `docs/` page's reasoning moved?** Read it. A `docs/` page carries no
|
||||
normative sentence and nothing verifies it by construction (AGENTS.md § File naming), so an
|
||||
unsure guess defaults to reading the page rather than skipping the question -
|
||||
[`stack-close`](stack-close/SKILL.md) step 3 asks it again at the end of the session as a
|
||||
backstop, not as the only time it is asked.
|
||||
- **The surface is a whole new stage, collection, or gate?** The table's rows are the steady
|
||||
state; a new row-worthy category is itself a change to this instruction - add the row here
|
||||
rather than leaving the next session to rediscover the gap.
|
||||
|
||||
## Scope
|
||||
|
||||
Applies to `stack-dev` sessions only - wiki content changes have their own provenance and
|
||||
cross-reference rules (`kb/CONTRACT.md`, `wiki-manage`), which already pull the relevant pages
|
||||
through as part of the normal skill. Not a replacement for `stack-close` step 3, which re-asks
|
||||
the `docs/`-staleness question after publish as the second, session-final check.
|
||||
@@ -75,12 +75,16 @@ and a fresh subagent starts without the session's context).
|
||||
#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.
|
||||
3. **Check whether a `docs/` page, a contract, or a 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 `tools/CONTRACT.md`'s two tables and any touched
|
||||
`<stage>/CONTRACT.md`, whose prose `docs verify` checks only for presence and table-row
|
||||
membership, never for what a cell or a section actually says
|
||||
([doc-pull-through.md](../doc-pull-through.md)); of `README.md`/`INSTALL.md`/`DEVELOPMENT.md`
|
||||
prose; and of 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 or the
|
||||
behaviour one of these documents describes, 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
|
||||
|
||||
@@ -48,7 +48,7 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
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 what
|
||||
[`stack-close`](../stack-close/SKILL.md) carries out once this skill's own work is published -
|
||||
see step 5 below. An issue labelled `status/incoming` is the exception to all of that: it is a
|
||||
see step 6 below. An issue labelled `status/incoming` is the exception to all of that: it is a
|
||||
human's stub, not a spec, and it is **never implemented as it stands** - it gets worked out and
|
||||
triaged first. Read this file before filing something for later, before editing or closing an
|
||||
issue, before picking up an incoming stub, or before deciding what to pick up next.
|
||||
@@ -62,6 +62,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
demo/testbed `kb/`, the measurable floors that define it, and what a reactive fix may and may
|
||||
not do to corpus content. Read it before judging whether the corpus can exercise a change, or
|
||||
before any fix that would touch `kb/` content.
|
||||
[doc-pull-through.md](../doc-pull-through.md) - which document makes a claim about a touched
|
||||
surface (a `wikitool` command, a stage's rules, an `AGENTS.md` rule/gate/invariant, a
|
||||
README-shaped human doc, a `docs/` page's reasoning) and therefore needs updating alongside
|
||||
the code, since `docs verify` never reads a cell's prose. Read it before step 6.
|
||||
More instructions are added here incrementally as stack-development needs come up - this
|
||||
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
|
||||
@@ -135,7 +139,11 @@ 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, then publish.** `tools/wikitool docs verify`, `tools/wikitool instructions verify`,
|
||||
5. **Pull through every document that makes a claim about the surface you touched - `docs verify`
|
||||
checks a cell's presence, never its prose.** [doc-pull-through.md](../doc-pull-through.md) has
|
||||
the table of which document that is, per surface.
|
||||
|
||||
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
|
||||
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`
|
||||
|
||||
@@ -177,6 +177,6 @@ Whenever you add or change a test under `tools/chemenu/tests/`.
|
||||
## Scope
|
||||
|
||||
Applies to `tools/chemenu/tests/` only. It says nothing about what to test - the test/review
|
||||
expectations for a stack change are the `stack-dev` skill's step 4 (`docs verify`,
|
||||
expectations for a stack change are the `stack-dev` skill's step 6 (`docs verify`,
|
||||
`instructions verify`, pytest). CI runs the suite once, unhardened, because the fixture makes a
|
||||
second hardened run redundant; see the note on the Tests step in `.gitea/workflows/ci.yml`.
|
||||
|
||||
@@ -65,7 +65,7 @@ a new one, and only `version release` turns it into something the release workfl
|
||||
|
||||
## When to run
|
||||
|
||||
Before every `tools/wikitool version bump` - the `stack-dev` skill's step 3 sends you here.
|
||||
Before every `tools/wikitool version bump` - the `stack-dev` skill's step 4 sends you here.
|
||||
Read it in full the first time a change looks like it might be boundary-crossing; afterwards
|
||||
the three-line test below is usually enough.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user