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

stack: SKILL.md-Links auf repo-root-relative Pfade umgestellt, docs verify/instructions verify pruefen Linkziele
CI / verify (push) Successful in 52s
Details
Release / release (push) Successful in 36s
Details

Browse Source 
Files changed:
- CHANGES.md
- VERSION
- instructions/CONTRACT.md
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-close/SKILL.md
- instructions/dev/stack-dev/SKILL.md
- instructions/wiki-ingest/SKILL.md
- instructions/wiki-lint/SKILL.md
- instructions/wiki-manage/SKILL.md
- instructions/wiki-query/SKILL.md
- instructions/wiki-status/SKILL.md
- tools/CONTRACT.md
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/instructions_cmd.py
- tools/chemenu/tests/test_docs_verify.py
- tools/chemenu/tests/test_instructions_cmd.py
This commit is contained in:
Torben Nehmer
2026-09-12 23:21:45 +02:00
parent dc688e5726
commit 0fb8fd6122
16 changed files with 442 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
instructions/CONTRACT.md
+35 -3
View File
@@ -18,6 +18,7 @@ alongside [AGENTS.md](../AGENTS.md).
- [Publishing](#publishing)
- [Writing an instruction](#writing-an-instruction)
- [A skill's H1 is a name, not an imperative](#a-skills-h1-is-a-name-not-an-imperative)
- [A skill's outbound reference is a plain path, not a link](#a-skills-outbound-reference-is-a-plain-path-not-a-link)
- [Reference depth: bundled files, not repo-wide contracts](#reference-depth-bundled-files-not-repo-wide-contracts)
- [When a skill carries a copy-in checklist](#when-a-skill-carries-a-copy-in-checklist)
- [How much reasoning a step may carry](#how-much-reasoning-a-step-may-carry)
@@ -190,6 +191,35 @@ exception in the same breath - "for promoted skills, the skill name is the title
That is the whole exception. Everything else in this section binds a `SKILL.md` exactly as it
binds an instruction.
### A skill's outbound reference is a plain path, not a link
`tools/wikitool instructions sync` copies each `SKILL.md` byte for byte into
`.agents/skills/<name>/` and `.claude/skills/<name>/` (§ Publishing, above) - a different depth
than the source, and without the sibling files a relative link might expect. A markdown link
correct at `instructions/<name>/SKILL.md` (`../session-setup.md`, `../../kb/CONTRACT.md`)
resolves to a different, usually nonexistent, file once copied: the number of `../` segments
that reaches a target from `instructions/` does not reach the same target from
`.claude/skills/`. Fifty-two of the fifty-eight relative links across this repo's seven skills
broke exactly this way before this rule existed, silently - nothing rendered the copy to notice,
and no check read a link target.
So a `SKILL.md` never writes an outbound reference as a relative markdown link, correct depth or
not. It names the target as a repo-root-relative **plain path** instead - `` `instructions/session-setup.md` ``, not `[session-setup.md](../session-setup.md)`; `` `kb/CONTRACT.md` `` for a
whole file, `` `kb/CONVENTIONS.md` § Tone `` for a section rather than an anchored link. The path
survives the copy unchanged because it does not depend on where the reading file sits: an
agent's working directory is the instance root regardless of which published copy it opened, so
the same plain path resolves in the source and in both published copies alike. The cost is that
the reference is no longer clickable from the source file - accepted deliberately, because the
source is not where an agent reads it from; the harness reads the published copy.
`tools/wikitool instructions verify` enforces the ban mechanically
(`check_skill_reference_paths`).
This binds only `SKILL.md`. The flat `instructions/<name>.md` form - this file included - is
never copied anywhere, so its relative links stay exactly as correct as their `../` count says,
and stay ordinary links; `tools/wikitool docs verify` (`check_reference_targets`) resolves those
against the working tree instead of banning the syntax, over the same reference-file scope
`tools/wikitool docs toc` uses.
### Reference depth: bundled files, not repo-wide contracts
Anthropic's skill-authoring guidance asks that reference files stay **one level deep from
@@ -201,9 +231,11 @@ That rule governs **skill-bundled** material: files sitting in `instructions/<na
`OOXML.md`), and it says nothing about files outside the skill directory. No skill in this repo
has a bundled file today, so as written the rule currently binds nothing here.
A link from a skill to a repo-wide contract - [kb/CONTRACT.md](../kb/CONTRACT.md),
[tools/CONTRACT.md](../tools/CONTRACT.md), [gates.md](gates.md) - is a different category, and
the two halves of the question have different answers:
A skill's reference to a repo-wide contract - `kb/CONTRACT.md`, `tools/CONTRACT.md`,
`instructions/gates.md` (written as a plain path per § "A skill's outbound reference is a plain
path, not a link" above; this file is a flat instruction rather than a `SKILL.md`, so its own
references to the same three files, a few sections up and below, stay ordinary links) - is a
different category, and the two halves of the question have different answers:
- **The mechanic is real and directory-independent.** A contract reached at the second hop can
be read partially exactly as a bundled file would be. Nothing about the path makes it safe.
instructions/dev/doc-pull-through.md
+2 -2
View File
@@ -33,7 +33,7 @@ touched; a row that does not apply needs no action.
| 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 `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 |
@@ -42,7 +42,7 @@ touched; a row that does not apply needs no action.
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
[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.
instructions/dev/stack-close/SKILL.md
+7 -7
View File
@@ -13,11 +13,11 @@ there and hands off here rather than continuing into this phase in the same brea
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
silently - see `instructions/dev/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
(its own `instructions/dev/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
@@ -25,13 +25,13 @@ everyone reads afterwards and nobody revisits).
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 [docs/model-and-effort-selection.md](../../../docs/model-and-effort-selection.md)). Asking the
state (see `docs/model-and-effort-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
`instructions/dev/issue-tracking.md` § What no tool checks) - but it removes the thing that
was actually failing: the closing *procedure* is no longer sitting in the session's context as a
next step to run past - it exists only inside a skill someone has to invoke.
@@ -66,7 +66,7 @@ and a fresh subagent starts without the session's context).
- 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
`instructions/dev/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
@@ -80,7 +80,7 @@ and a fresh subagent starts without the session's context).
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`
(`instructions/dev/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
@@ -110,7 +110,7 @@ and a fresh subagent starts without the session's context).
- **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
`instructions/dev/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
instructions/dev/stack-dev/SKILL.md
+15 -15
View File
@@ -39,30 +39,30 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
1. **Confirm the mode.** If the task is ambiguous between "extend the tool" and "operate the
wiki", ask rather than guess - the two have different rules for the same directories.
2. **Consult `instructions/dev/` for the concrete procedure.** Currently:
[commonplace-kb.md](../commonplace-kb.md) - vendored knowledge base on agent context
`instructions/dev/commonplace-kb.md` - vendored knowledge base on agent context
engineering, memory and deploy-time learning; consult before a design decision in those
areas.
[issue-tracking.md](../issue-tracking.md) - open work lives in Gitea issues, one per work
`instructions/dev/issue-tracking.md` - open work lives in Gitea issues, one per work
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 what
[`stack-close`](../stack-close/SKILL.md) carries out once this skill's own work is published -
`stack-close` (`instructions/dev/stack-close/SKILL.md`) carries out once this skill's own work is published -
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.
[testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
`instructions/dev/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.
[version-parts.md](../version-parts.md) - which part a change bumps: the drop-in test, the
`instructions/dev/version-parts.md` - which part a change bumps: the drop-in test, the
catalogue of breaks that cross the compatibility boundary with `kb/` untouched, and what to
put in front of the user before a breaking bump. Read it before step 4.
[corpus-policy.md](../corpus-policy.md) - what "curated enough" means for the shared
`instructions/dev/corpus-policy.md` - what "curated enough" means for the shared
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
`instructions/dev/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.
@@ -100,7 +100,7 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
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:
[docs/model-and-effort-selection.md](../../../docs/model-and-effort-selection.md).
`docs/model-and-effort-selection.md`.
4. **Raise the version, if the change ships.** A change under `tools/`, `types/`,
`instructions/`, `AGENTS.md` or a `CONTRACT.md` reaches every future instance, so it needs a
@@ -113,7 +113,7 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
`--impact high|medium|low` (default `medium`) grades this bump in the changelog entry's own
list - `tools/wikitool version regrade` corrects it later if the candidate's overall shape
changes the read on an earlier one; see
[instructions/dev/version-parts.md](../version-parts.md) § The candidate model.
`instructions/dev/version-parts.md` § The candidate model.
Never edit `VERSION` or the entry's heading by hand - `bump` writes both, and `docs verify`
fails a tree where they disagree. Pick the part by whether the new version is a **drop-in
@@ -128,12 +128,12 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
Content migration is one way to land in the last row, not the definition of it: a rename of
the update path, the artefact, an import name, a flag or an envvar breaks a swap with `kb/`
entirely untouched. The full test, the catalogue of such breaks, and what to put in front of
the user first are in [version-parts.md](../version-parts.md) - **read it before choosing
the user first are in `instructions/dev/version-parts.md` - **read it before choosing
`--major`.**
A `--major` bump therefore needs two things recorded. `--breaking "<what stops working>"`
is required on every boundary-crossing bump; on top of it, a migration document for the new
version - written per [migrate-corpus.md](../../migrate-corpus.md) - or
version - written per `instructions/migrate-corpus.md` - or
`--no-migration "<reason>"` when no content actually has to change. `bump` refuses without
either, and so does `docs verify`: an instance learning that it must migrate, with nothing
telling it how, is a dead end.
@@ -145,7 +145,7 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
do not need a bump - CI's version gate is scoped to what changes behaviour.
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
checks a cell's presence, never its prose.** `instructions/dev/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`,
@@ -162,7 +162,7 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
**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;
in `stack-close` (`instructions/dev/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.
@@ -176,7 +176,7 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
user decides whether it is worth that: show them what breaks, what an instance has to do about
it, and the alternatives (avoid the break with a shim, defer and batch it with the next one,
or split it behind a deprecation window), then recommend one and wait for a go-ahead.
[version-parts.md](../version-parts.md) step 4 has the full shape. A surfacing boundary crossing
`instructions/dev/version-parts.md` step 4 has the full shape. A surfacing boundary crossing
is also a reason to offer the model switch back up (step 3): the judgment it needs has no
mechanical guard, and `docs verify` only checks that a crossing documents itself, never that the
part was chosen correctly.
@@ -186,4 +186,4 @@ 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`). Not for closing a work package after
its publish has landed - that is [`stack-close`](../stack-close/SKILL.md).
its publish has landed - that is `stack-close` (`instructions/dev/stack-close/SKILL.md`).
instructions/wiki-ingest/SKILL.md
+16 -16
View File
@@ -10,7 +10,7 @@ description: Process a new source file into the LLM wiki - extract entities and
**Trigger:** User drops a file into `incoming/` (the normal path - see step 1) or directly into
`raw/`, or explicitly requests ingestion.
**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).
**Before the first `wikitool` call:** `instructions/session-setup.md`.
Contracts are read **when the step needs them**, not upfront: a source that produces no concept
pages should never have cost the concept contract. Field-level requirements always come from
@@ -40,7 +40,7 @@ validator complains - and the ticked list is the only record that they happened.
## Steps
1. **Promote from `incoming/` if that is where the file sits.** Read
[raw/CONTRACT.md](../../raw/CONTRACT.md) "Getting a file in" and "Capture fields" if you have
`raw/CONTRACT.md` "Getting a file in" and "Capture fields" if you have
not this session - the directory and any bundling are computed, never chosen by hand, but the
two capture flags are not: `raw accept` refuses without them.
@@ -63,7 +63,7 @@ validator complains - and the ticked list is the only record that they happened.
**A file that arrived through the MCP `submit` tool is not yet in `incoming/`** - it sits in
`mcp-upload/<id>/`, a quarantine no command in this step reads. A reviewer promotes it first
with `wikitool upload accept <id> --confirm <token>`, per
[instructions/ingest-queue.md](../ingest-queue.md); once accepted it is an ordinary file in
`instructions/ingest-queue.md`; once accepted it is an ordinary file in
`incoming/` and this step applies to it exactly as to anything dropped there by hand.
**If this refuses because the name is already claimed** (a file stem or a bundle directory
@@ -79,7 +79,7 @@ validator complains - and the ticked list is the only record that they happened.
**Check the size first, on both axes.** *Volume* - how many raw files this ingest covers -
and *breadth* - how many entities and concepts this one source would produce or update.
Either one past the thresholds in [ingest-large-tree.md](../ingest-large-tree.md) § When to
Either one past the thresholds in `instructions/ingest-large-tree.md` § When to
run is that procedure, not this one: stop and follow it. There, volume is cut into units;
breadth cannot be cut at all (`raw/` keeps a file whole, and one raw file has one owning
source page) and buys an extract pass instead, before any page is written. Skipping either
@@ -107,7 +107,7 @@ validator complains - and the ticked list is the only record that they happened.
which entities/concepts to create or update, any specific emphasis.
6. **Create the source page.** Read
[kb/sources/COLLECTION.md](../../kb/sources/COLLECTION.md) first - it holds what this
`kb/sources/COLLECTION.md` first - it holds what this
instance expects of a source page's sections and how it names one.
```bash
@@ -140,18 +140,18 @@ validator complains - and the ticked list is the only record that they happened.
article also pass `--set source_url=<upstream URL>`; `raw_files:` must still point at the
local copy. Then write the Summary / Key Takeaways / Action Items prose from step 5 - in the
KB language, whatever the source's own language is, quoting verbatim passages in the
original. Which language that is: [kb/CONVENTIONS.md](../../kb/CONVENTIONS.md#language).
original. Which language that is: `kb/CONVENTIONS.md` § Language.
What is exempt from it, in any language:
[kb/CONTRACT.md](../../kb/CONTRACT.md#language-and-identifiers).
`kb/CONTRACT.md` § Language and identifiers.
Fill `## Not Extracted` in the same pass: what you read and deliberately did not promote,
with the reason. Nothing in the repository can re-derive that judgment, and without it the
same source gets re-litigated on the next pass.
7. **Create or update entity pages.** Read
[kb/entities/COLLECTION.md](../../kb/entities/COLLECTION.md) and
[kb/CONTRACT.md](../../kb/CONTRACT.md) plus
[kb/CONVENTIONS.md](../../kb/CONVENTIONS.md) first - the second is where provenance and
`kb/entities/COLLECTION.md` and
`kb/CONTRACT.md` plus
`kb/CONVENTIONS.md` first - the second is where provenance and
citation are defined, the third where this instance's tone and naming forms are.
**A subject earns a page when the source carries material for one.** A name the source
@@ -186,7 +186,7 @@ validator complains - and the ticked list is the only record that they happened.
8. **Create or update concept pages** - only if the source produced any. Same pattern, including
step 7's rule about which subjects earn a page at all, reading
[kb/concepts/COLLECTION.md](../../kb/concepts/COLLECTION.md) first:
`kb/concepts/COLLECTION.md` first:
```bash
tools/wikitool new concept --name "<Name>" \
@@ -211,7 +211,7 @@ validator complains - and the ticked list is the only record that they happened.
The new raw file(s) must no longer be listed as uncovered, and no `raw_files:` entry may be
broken.
11. **Close out.** Follow [publish-cycle.md](../publish-cycle.md) with `--op ingest` and a
11. **Close out.** Follow `instructions/publish-cycle.md` with `--op ingest` and a
message of the form `ingest: <raw path>`.
12. **Check the lint cadence.**
@@ -230,16 +230,16 @@ validator complains - and the ticked list is the only record that they happened.
Two pages on one subject is the failure this step exists to prevent.
- **One source names far more subjects than usual?** That is breadth, not volume. It is not
split into several sources - it cannot be - and it does not get a page per name either:
[ingest-large-tree.md](../ingest-large-tree.md) § A broad source is not cut.
`instructions/ingest-large-tree.md` § A broad source is not cut.
- **No raw file backs a claim you want to write?** Leave it out, or mark the page
`provenance: mixed` and put it under `## General Guidance (unsourced)`.
- **`publish` exited 42?** A single ingest is normally well under the Mass-Update Gate
threshold. If it trips - a source touching many entities - show the user the output and stop;
see [gates.md](../gates.md).
- **A gate or the loop-breaker refuses anything?** Stop and follow [gates.md](../gates.md).
see `instructions/gates.md`.
- **A gate or the loop-breaker refuses anything?** Stop and follow `instructions/gates.md`.
A multi-tool ingest should land in roughly 20-35 `wikitool` calls; needing far more is a sign
the source should be split into several ingests - which is
[ingest-large-tree.md](../ingest-large-tree.md), not a bigger budget.
`instructions/ingest-large-tree.md`, not a bigger budget.
## wikitool commands used
instructions/wiki-lint/SKILL.md
+5 -5
View File
@@ -11,7 +11,7 @@ description: Health-check the LLM wiki - broken links, orphan pages, uncovered r
threshold reached - `wiki-ingest`'s last step checks it after every publish, so the count is
never something an agent has to remember.
**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).
**Before the first `wikitool` call:** `instructions/session-setup.md`.
## Run checklist
@@ -51,7 +51,7 @@ mechanical half looks exactly like a complete one.
The *Redundant see-also* section is the one that looks mechanical and is not - do **not**
clear it under step 7. It names a `see-also` edge standing beside a specific label on the
reverse direction, and the obvious repair destroys the thing worth keeping: `xref remove`
clears the reference in *both* directions (see [tools/CONTRACT.md](../../tools/CONTRACT.md)),
clears the reference in *both* directions (see `tools/CONTRACT.md`),
so removing the weak edge takes the labelled one with it and the pair ends up saying nothing
at all. Either relabel the weak edge to something true with `xref add`, which only ever
touches the source page, or leave it and report it at step 9. Clearing a batch of these is a
@@ -90,7 +90,7 @@ mechanical half looks exactly like a complete one.
7. **Repair what is mechanical.** A dangling frontmatter reference is either a page that should
exist (`tools/wikitool new ...`) or a reference that should not
(`tools/wikitool xref remove --a "<Page>" --b "<Missing>"`). A title that changed is
`tools/wikitool rename` - see [page-lifecycle.md](../page-lifecycle.md). Never hand-edit a
`tools/wikitool rename` - see `instructions/page-lifecycle.md`. Never hand-edit a
frontmatter array to clear one.
8. **Verify the stack.**
@@ -129,7 +129,7 @@ mechanical half looks exactly like a complete one.
- **Publish?** Lint does not auto-publish. Run `tools/wikitool publish` only if asked.
- **Bulk fixes touched 10+ files?** Expected for a lint pass: `publish` exits 42. Show the
user its output and stop; see [gates.md](../gates.md). Consider `--path` batches instead.
user its output and stop; see `instructions/gates.md`. Consider `--path` batches instead.
- **The gate or loop-breaker keeps tripping?** That is a signal to stop and re-plan with the
user, not to pass `--override-budget`. A full pass should land in roughly 20-35 calls.
@@ -140,7 +140,7 @@ mechanical half looks exactly like a complete one.
`publish` (only if asked)
**Deliberately absent:** `rm` - a lint pass never deletes a page, and
[page-lifecycle.md](../page-lifecycle.md) is where a deletion belongs. `log status` - it decides
`instructions/page-lifecycle.md` is where a deletion belongs. `log status` - it decides
this skill's *trigger*, but `wiki-ingest`'s last step is what runs it.
## Output
instructions/wiki-manage/SKILL.md
+9 -9
View File
@@ -11,11 +11,11 @@ catalog and the audit log in sync.
**Trigger:** User requests a new entity/concept/comparison page, or new information needs
integrating into an existing one.
**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).
**Before the first `wikitool` call:** `instructions/session-setup.md`.
**Read before drafting:** [kb/CONTRACT.md](../../kb/CONTRACT.md) - linking and provenance,
**Read before drafting:** `kb/CONTRACT.md` - linking and provenance,
both of which the tool enforces - and
[kb/CONVENTIONS.md](../../kb/CONVENTIONS.md), which is where this instance's language, naming
`kb/CONVENTIONS.md`, which is where this instance's language, naming
forms, tone and relationship labels are, together with the target collection's own
`COLLECTION.md`, which carries its quality goal and what is local to that subtree. Field-level
requirements come from `tools/wikitool types describe <type>`.
@@ -48,7 +48,7 @@ requirements come from `tools/wikitool types describe <type>`.
subjects - so the prose connects to existing pages instead of restating them.
5. **Draft.** Fill in the generated skeleton's TODO sections, following the tone rules in
[kb/CONVENTIONS.md](../../kb/CONVENTIONS.md#tone). If `provenance:` is `sourced` or `mixed`, cite
`kb/CONVENTIONS.md` § Tone. If `provenance:` is `sourced` or `mixed`, cite
hard facts as you write them with `tools/wikitool cite add --page "<Title>" --source
"Source - X"`, which also adds `X` to `sources:` - paste the `[^cite-id]` marker it prints.
@@ -60,7 +60,7 @@ requirements come from `tools/wikitool types describe <type>`.
One per relationship. Never hand-edit `related:`.
7. **Close out.** [publish-cycle.md](../publish-cycle.md), `--op create`.
7. **Close out.** `instructions/publish-cycle.md`, `--op create`.
## Updating a page
@@ -84,11 +84,11 @@ requirements come from `tools/wikitool types describe <type>`.
Never hand-edit `modified:`, `summary:` or `provenance:`.
7. **Close out.** [publish-cycle.md](../publish-cycle.md), `--op update`.
7. **Close out.** `instructions/publish-cycle.md`, `--op update`.
## Renaming, deleting, or unlinking
That is [page-lifecycle.md](../page-lifecycle.md). A title is the wiki's only identifier for a
That is `instructions/page-lifecycle.md`. A title is the wiki's only identifier for a
page, so none of it is a file operation.
## Decision points
@@ -98,7 +98,7 @@ page, so none of it is a file operation.
- **Entity or concept?** A thing you can point at is an entity; a *why* or *how* is a concept.
The collection contracts draw the line.
- **`publish` refused?** A single page is normally well under the threshold. If it trips,
[gates.md](../gates.md).
`instructions/gates.md`.
## wikitool commands used
@@ -106,7 +106,7 @@ page, so none of it is a file operation.
`sources rebuild-index`, `index rebuild`, `log append`, `publish`
`xref remove` belongs to the unlinking case, which this skill delegates whole to
[page-lifecycle.md](../page-lifecycle.md) rather than describing in a step of its own.
`instructions/page-lifecycle.md` rather than describing in a step of its own.
## Output
instructions/wiki-query/SKILL.md
+4 -4
View File
@@ -9,7 +9,7 @@ description: Answer a question using the LLM wiki's compiled knowledge - read-on
**Trigger:** User asks a question.
**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).
**Before the first `wikitool` call:** `instructions/session-setup.md`.
**Hard rule:** read-only with respect to wiki *content*. Never modify, hand-edit, or scaffold a
page while answering. Two exceptions, both mechanical: step 6 (filing a valuable answer through
@@ -46,7 +46,7 @@ invariant - rather than synthesizing a plausible-sounding answer from general kn
4. **Answer and cite.** Name the wiki pages the answer came from, and the sources behind them.
Hedge to what those sources carry, not to a number - see
[kb/CONVENTIONS.md § Hedging](../../kb/CONVENTIONS.md#hedging).
`kb/CONVENTIONS.md` § Hedging.
5. **Decide what earns a page - before the first `new`.** Name every page you are considering,
then hold each one on its own against all three criteria: the answer required synthesis
@@ -75,9 +75,9 @@ invariant - rather than synthesizing a plausible-sounding answer from general kn
exist under different words. Then say the wiki has no confident source, and offer to ingest
one.
- **Filed a page?** Query does **not** auto-publish. Run `tools/wikitool publish` only if asked;
the sequence is in [publish-cycle.md](../publish-cycle.md).
the sequence is in `instructions/publish-cycle.md`.
- **Several answers filed at once?** That can trip the Mass-Update Gate - see
[gates.md](../gates.md). The gate is a brake, not the check: it counts files and knows nothing
`instructions/gates.md`. The gate is a brake, not the check: it counts files and knows nothing
about whether any of them earned a page. Step 5 is what decides that, and a batch small enough
to pass the gate has not been cleared by it.
instructions/wiki-status/SKILL.md
+2 -2
View File
@@ -10,14 +10,14 @@ semantic review a lint pass does.
**Trigger:** User asks for wiki statistics, "what's new", or a quick health snapshot.
**Before the first `wikitool` call:** [session-setup.md](../session-setup.md) - step 2's `lint` is
**Before the first `wikitool` call:** `instructions/session-setup.md` - step 2's `lint` is
not on the budget's exemption allowlist and is counted like any other call, gitignored report or
not (§ Scope there).
**Hard rule:** read-only with respect to wiki *content*. Never create, modify, or scaffold a
page, never repair a finding, never publish. One file does get written: the report `lint`
produces in step 2. That is not an exception being stretched - `reports/` is gitignored and holds
no wiki page ([reports/CONTRACT.md](../../reports/CONTRACT.md)), so the write leaves nothing
no wiki page (`reports/CONTRACT.md`), so the write leaves nothing
behind that the wiki ships. If something looks wrong, point the user at `wiki-lint` or
`wiki-manage` instead of fixing it here.