jschoubben
36d342f176
Every manifest in the system being replaced was read and every key counted, then set against what the new one can express. Three findings worth more than the table. **The most-used key was already covered and I expected a gap.** Depending on another module — 65 manifests, the commonest thing any of them says — is a requirement naming a module, which already means that module rather than anything providing the name. **The largest real gap is tool servers: 56 modules, over half.** A module can already run one; what is missing is anything saying it offers tools. That is plausibly a provision rather than new vocabulary, which would need nothing added — not yet decided, and recorded as undecided. **The gap most worth closing is health, at seven modules.** The mesh knows a container is running, which is not whether it answers, and this project has paid for that distinction twice. An action with a verify is exactly the right shape and may not arrive over the link, so a module cannot declare one. Two things are missing deliberately and say so: stage hooks, because the link may not carry an action and a module needing setup ships a program; and flavours, retired in favour of claims. Config merging is missing and should stay missing. A mechanism that understands TOML gets asked for YAML, then INI, which is how the thing being replaced became unholdable. Also records what the survey found that is not about coverage: manifests that had stopped matching what was actually brokered, one fact derived in two places giving two answers, and a live listing returning credentials in plaintext.
04-ISSUES
The front door for "something is wrong" at the level of the mesh's design or governance. Diagnosis happens here, where the whole mesh is in view; the fix lands in the owning code repository.
What belongs here
| Belongs here | Belongs in the knowledge base |
|---|---|
| The design permits a failure to be silent | How to fix one occurrence of it |
| A documented rule is enforced by nothing | A command that works around it |
| A stated invariant is false in practice | A node-specific quirk |
| The owner is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
The knowledge base already holds the operational record and is indexed on symptoms. This folder is not a second copy of it. An issue here is a question HQ must answer; an entry there is an incident someone must clear. An issue whose answer is a general lesson belongs in both.
Structure
NNN-short-name/
00-report.md the symptom as observed, with the evidence; status in frontmatter
01-diagnosis.md the investigation trail, dated, including what was ruled out
Frontmatter, on 00-report.md
---
status: open | diagnosing | located | resolved | wontfix
opened: YYYY-MM-DD
located-in: [] # owning repo(s) or module(s), filled by diagnosis
fixed-by: # pull request or commit reference, filled at resolution
amended-design: # design doc path, when the root cause was a design gap
---
Rules
- Anyone may open an issue. No localisation is required to report one.
- The full flow is playbook
00-META/process/03-issues.md. - Closed issues are never deleted — they are the mesh's symptom-to-component memory.
wontfixis legitimate and requires a sentence saying why.