From 6b74924044307c509ac5b42b42bf9cf0a94ff359 Mon Sep 17 00:00:00 2001 From: Ako Date: Fri, 4 Sep 2026 09:10:50 +0000 Subject: [PATCH] =?UTF-8?q?docs(proposal):=20=C2=A74.5=20=E2=80=94=20the?= =?UTF-8?q?=20two=20further=20record=20kinds,=20and=20what=20separates=20t?= =?UTF-8?q?hem?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The proposal described one kind of record, a decision, while the store has three. Adds §4.5 with amendments A10 and A11. The separating property is not three separate arguments but one: what a FAILED anchor means. A decision's anchor points backward at what exists, so one that stops resolving means the decision is stale. A requirement's points forward, so one that does not resolve means not built yet. A question's points at what is under discussion, so it means nothing at all — the question is often whether the thing should exist. Identical syntax; only the direction differs, and that is the whole lifecycle. Records that this was measured before it was designed: as an ordinary entry, a single not-yet-built requirement takes `brain check` to exit 1, and so does a question. Neither could be more decisions without making the check useless. Also records where this departs from the AI-native SDLC playbook and where it was behind it. Departs: the playbook keeps a plan.md and recommends a hook enforcing that the diff still matches it — a self-reported artifact being policed, which is only necessary when there is no queryable model. Behind: the playbook's trigger for CLAUDE.md ("when Claude makes a mistake twice, the correction goes into CLAUDE.md") is the one thing this design was missing outright, and is now A11. And notes the defect the comparison exposed, because the lesson generalises: the proposal asserted project.md was loaded every session and justified the store's tightest cap on that basis, with nothing behind it — a generated project mentioned the brain once, in a skills-table row, behind a symptom-triggered description. A policy about what is loaded is worth nothing without the thing that loads it, and the same question should be asked of any future claim of that shape here. Co-Authored-By: Claude Opus 5 --- docs/11-proposals/PROPOSAL_project_brain.md | 81 ++++++++++++++++++++- 1 file changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/11-proposals/PROPOSAL_project_brain.md b/docs/11-proposals/PROPOSAL_project_brain.md index 14399f51b..16db0207a 100644 --- a/docs/11-proposals/PROPOSAL_project_brain.md +++ b/docs/11-proposals/PROPOSAL_project_brain.md @@ -412,13 +412,88 @@ first is the one that matters: 4. **Write the anchor, not the name.** `@Sales.Order.Status` is what makes an entry checkable and routable; the same fact written as prose is neither. +### 4.5 Two more record kinds, and the property that separates them + +The brief and §4.1–4.4 describe one kind of record: a **decision**. Two more are +needed, and the reason is a single property rather than three separate +arguments — **what a failed anchor means.** + +| Kind | Its anchor points | An anchor that does not resolve means | Checked? | +|---|---|---|---| +| decision | backward, at what exists | the decision is **stale** | yes — fails | +| requirement | forward, at what is intended | **not built yet** | counted, never fails | +| open question | at what is *under discussion* | nothing — the question is often whether it should exist | not at all | + +The syntax is identical in all three. Only the direction differs, and that is +the whole lifecycle. + +**This was measured before it was designed**, which is what settled it in one +command: recorded as an ordinary entry, a single not-yet-built requirement takes +`brain check` to exit 1. The same is true of a question. Requirements and +questions could not be more decisions without making the check useless. + +**Requirements** (`plan/.md`, `capture --slice`) exist because the source +of truth is frequently outside git — a specification document, a prototype, a +conversation. None of that is an issue or a commit message, so hours of work can +end with nothing recording what they were for, and a resumed session has no idea +what it was building towards. This is the gap the analogous store never had, +because mxcli's own work is driven by GitHub issues. + +The inversion then pays for the feature rather than merely accommodating it: a +requirement is **built** when its anchors resolve, so `brain plan` reports +progress *derived from the model*. Measured end to end — a slice at 0 built / +1 planned became 1 / 0 after creating the microflow its requirement named, with +the plan file untouched. There is no status column to maintain and none that can +be silently wrong, which is A6 applied to scope rather than to size. It is also +where this design departs from the AI-native SDLC playbook, which keeps a +`plan.md` and recommends a hook to enforce that the diff still matches it: that +is a self-reported artifact being policed, and it is only necessary when there is +no queryable model. There is one here. + +**Open questions** (`--open`, `brain resolve`) are decisions not yet made. They +live beside the decisions they will join rather than in a file of their own, +because the moment you need to see one is while reading what that module already +decided. Resolution converts the entry **in place**, keeping its id and position +— an answered question is the same piece of knowledge as the question — and from +then on its anchors are checked like any other decision. + +Two consequences worth stating, because both are the kind of thing that looks +like an oversight: + +- **A question filed against a slice is not scope.** It is counted apart from + the slice's requirements; counting an unanswered question as outstanding work + would overstate what is left to do. +- **Requirements and questions are never misfiled.** A slice spans modules by + design, and a question has no resolved anchor to compare a shard against. + +Two amendments follow, in the table's numbering: + +| # | Amendment | Because | +|---|---|---| +| A10 | Three record kinds, distinguished by anchor direction. Requirements live in `plan/.md`; questions live beside decisions and carry an `OPEN` marker | §4.5: measured — a requirement or question recorded as a decision takes `check` to exit 1 | +| A11 | Capture gets a **trigger**: a correction made twice, or a choice between real alternatives. `mxcli lint` reports unpromoted entries *and* unanswered questions | §4.5: the plan half fills at bootstrap while the decisions half fills only if someone remembers — A7 applied to the imbalance | + +A11's trigger is taken from the AI-native SDLC playbook's rule for `CLAUDE.md` +("when Claude makes a mistake twice, the correction goes into `CLAUDE.md`"), +which is the one piece of that document this design was missing outright. + +Its other contribution was to expose a defect: the playbook is explicit that +`CLAUDE.md` is read at the **start of a session**, and this proposal asserted the +same of `project.md` — using it to justify the tightest cap in the store — with +no mechanism behind it. A generated project mentioned the brain exactly once, in +a skills-table row, behind a symptom-triggered description. The generated +`CLAUDE.md` now names `docs/brain/project.md` directly. **A policy about what is +loaded is worth nothing without the thing that loads it**, and the same question +should be asked of any future claim of that shape here. + ## 5. Phasing Unchanged from the brief, with A4 inserted: -1. Storage, anchors, and the seven verbs of §4.3 — `init` / `capture` / - `staged` / `promote` / `drop` / `check` / `show` — plus the skill of §4.4. - Markdown destinations only. +1. Storage, anchors, and the verbs of §4.3 — `init` / `capture` / `staged` / + `promote` / `drop` / `check` / `show`, plus `plan` and `resolve` for the two + further record kinds of §4.5 — and the skill of §4.4. Markdown destinations + only. 2. The mxbuild error → resolution trigger. 3. **Documentation audit**, then promotion into model documentation and lint-rule generation. No longer gated on A4.