From 0afc8cc5f81cf09b903e07e4d53a1b8ba659eb8f Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 13:25:21 +0200 Subject: [PATCH] Name the commit the knowledge base's records now come from, and link research with touches and decisions with rests-on (review of #312) --- .claude/skills/hq-graduate/SKILL.md | 2 +- .claude/skills/hq-new-research/SKILL.md | 2 +- .claude/skills/hq-status/SKILL.md | 2 +- .claude/skills/hq-sync-constitution/SKILL.md | 5 +++-- 00-META/checks/index.py | 3 +-- 00-META/process/01-research.md | 4 ++-- 00-META/process/02-graduation.md | 2 +- 01-RESEARCH/README.md | 4 ++-- 02-DECISIONS/README.md | 4 ++-- 03-DESIGN/01-to-be/46-the-conversation-with-the-operator.md | 2 +- 10 files changed, 15 insertions(+), 15 deletions(-) diff --git a/.claude/skills/hq-graduate/SKILL.md b/.claude/skills/hq-graduate/SKILL.md index 4869be10..f0db597f 100644 --- a/.claude/skills/hq-graduate/SKILL.md +++ b/.claude/skills/hq-graduate/SKILL.md @@ -20,7 +20,7 @@ written into this repository. 3. **Propose the decision record.** `mesh_call knowledge-base.propose` with the reserved `number`, `title`, `topic` (one of the six in [`02-DECISIONS/README.md`](../../../02-DECISIONS/README.md)), `date`, `deciders`, `clauses` (each `"**Lead.** the statement"`), `sections` (Context, Considered Options, - Consequences, How it is checked, References), `links` (`extends`, `supersedes`, `changes` with + Consequences, How it is checked, References), `links` (`extends`, `rests-on`, `supersedes`, `changes` with `"NNNN §N"`, `cites`), `homes` (the design's path), and `needs-operator: true` when the operator must approve it. A refusal names every rule broken: fix them all and propose again. The knowledge base reviews it itself; on `changes` revise and propose again with `why`. `knowledge-base.get` shows its diff --git a/.claude/skills/hq-new-research/SKILL.md b/.claude/skills/hq-new-research/SKILL.md index 8816a874..ed6917e8 100644 --- a/.claude/skills/hq-new-research/SKILL.md +++ b/.claude/skills/hq-new-research/SKILL.md @@ -22,7 +22,7 @@ All through the mesh MCP server (`mesh_describe` gives each verb's arguments). 3. **Propose the effort.** `mesh_call knowledge-base.propose` with `kind: research`, the reserved `number`, `title`, `status: active`, `date` (today), `sections` (the documents in order, each `name` and `text`; the first `00-overview.md`: **what** is investigated, **why**, and **what it touches**), and `links` - of kind `cites` for every record, effort, issue or design it touches. + of kind `touches` for every record, effort, issue or design it touches (`cites` for one it only names). 4. **Do the research** in further documents of the same effort. Each change is `propose` again with the effort whole and `why`. A refusal names every rule broken: fix them all and propose again. On review `changes`, revise and propose again; `knowledge-base.get` shows the reviews. diff --git a/.claude/skills/hq-status/SKILL.md b/.claude/skills/hq-status/SKILL.md index f91b6777..92425c3d 100644 --- a/.claude/skills/hq-status/SKILL.md +++ b/.claude/skills/hq-status/SKILL.md @@ -13,7 +13,7 @@ generated on demand and never written back to disk. | Section | Files | Frontmatter | |---|---|---| -| Research | the knowledge base, not a file: `knowledge-base.ask`, and `knowledge-base.get` with `kind: research` and a number | `status` (`active` / `graduated` / `abandoned`), `date`, links (`became`, `cites`) | +| Research | the knowledge base, not a file: `knowledge-base.ask`, and `knowledge-base.get` with `kind: research` and a number | `status` (`active` / `graduated` / `abandoned`), `date`, links (`became`, `touches`, `cites`) | | Design | `03-DESIGN/**/*.md` (not READMEs) | `layer` (`as-is` / `to-be`), `status` (`designed` / `in-progress` / `implemented` / `abandoned`), `code`, `updated`, `decisions` | | Decisions | the knowledge base, not a file: `knowledge-base.holds` with a topic (the clauses in force, with their records), `knowledge-base.get` with a number, `knowledge-base.links` | `status` (`proposed` / `accepted` / `superseded`), `topic`, `date`, `deciders`, each clause's status, links both ways, what changed it since | | Issues | the issue tracker, not a file: `mesh_call issue-tracker.list` (optionally `status`, `owner`, `phrase`) and `issue-tracker.get` | `status` (`open` / `diagnosing` / `located` / `fixing` / `resolved` / `wontfix`), `worker` and `stale` while `diagnosing` or `fixing`, `opened`, `located-in`, `fixed-by`, `amended-design`, `record` (the folder here, when it has one) | diff --git a/.claude/skills/hq-sync-constitution/SKILL.md b/.claude/skills/hq-sync-constitution/SKILL.md index e02ad2f2..175a5082 100644 --- a/.claude/skills/hq-sync-constitution/SKILL.md +++ b/.claude/skills/hq-sync-constitution/SKILL.md @@ -27,8 +27,9 @@ the claim "HQ is the source" is checked. 3. Publish it to the knowledge base under the constitution slug, replacing the body. 4. **Read it back and verify the change is present.** A publish that reported success and did nothing is exactly the failure class this repository exists to name — do not skip this. -5. Note the sync in the decision record's Consequences (in the knowledge base: `knowledge-base.propose` - the proposed record again with the note and `why`). +5. Note the sync in the decision record's Consequences (in the knowledge base: while the record is + proposed, `knowledge-base.propose` it again with the note and `why`; once it is accepted, `propose` it with + `insight`, saying what stood before). ## Do not diff --git a/00-META/checks/index.py b/00-META/checks/index.py index 9750c537..af833186 100644 --- a/00-META/checks/index.py +++ b/00-META/checks/index.py @@ -23,8 +23,7 @@ README = "02-DECISIONS/README.md" # A topic in the README's reading order, e.g. # 1. **What the mesh is** — `topic: the mesh`. What it is for, ... -# The knowledge base (mesh-knowledge, reference.go) and the records module's `records_decisions` read the -# same line, so the form is a contract. +# The knowledge base (mesh-knowledge, reference.go) reads the same line, so the form is a contract. TOPIC_LINE = re.compile(r"^\d+\.\s+\*\*(?P