Skip to content

feat!: guidance over enforcement — evidence-based gates + Pipeline Graph (v2.0.0) - #39

Merged
huiyu merged 20 commits into
mainfrom
feature/guidance-over-enforcement
Aug 4, 2026
Merged

feat!: guidance over enforcement — evidence-based gates + Pipeline Graph (v2.0.0)#39
huiyu merged 20 commits into
mainfrom
feature/guidance-over-enforcement

Conversation

@huiyu

@huiyu huiyu commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Philosophy shift, stated as three principles: skills stay atomic; cross-skill routing lives in bootstrap; project-state guidance replaces sequence enforcement. Sequence gates now consume evidence (with equivalents substitutable and overrides user-held), while control gates (artifact approval) and safety gates (TDD, verification, git safety) remain hard.

What changed

  • Pipeline Graph in bootstrap — single declaration of all cross-skill handoffs (incl. fix→mu-debug, micro exit, mrd→prompt prd). Skills end with uniform Done lines; hardwired "the ONLY skill you invoke next" terminals removed. CLAUDE.md canonical-homes and CONTEXT.md updated accordingly.
  • Evidence-based sequence gates — mu-arch and mu-code's entry requirements accept equivalents (detailed PRD §feature + object model ≈ scope artifact; inline plan ≈ docs/plans). Missing evidence → recommend the producer skill, offer alternatives, the user decides; declined recommendations are flagged in the artifact. The recommendation itself is not agent-waivable.
  • mu-scope evidence fast path — with enumerating evidence in hand, scope contributes only its non-duplicated trio (Quick Probe, conflict cross-check, reverse UCs): one report + one confirmation, vs the 3-6 round re-interview the RED baseline measured.
  • pipeline-gate.sh removed — the RED audit found it skill-blind (denied user-requested edits outside the pipeline), self-deadlocking (denied the Write that creates the first scope artifact), in structural conflict with the micro exit, and trivially bypassed via Bash heredocs.

Test evidence

RED baseline and both GREEN probes (evidence-substitution 4/4, guidance-floor 4/4) are documented in the commit message; both probes are persisted in tests/prd-state-modeling/ alongside the existing seven scenarios. The guidance floor holds: vague ask + "别问那么多" still routes to scope and requires an informed, user-held override; TDD and verification never yield.

Post-merge

  • /reload-plugins
  • /mu-wiki update (wiki now ~10 commits behind: mu-mrd rename, routing-gate audit, this change)
  • Consider tagging v2.0.0

🤖 Generated with Claude Code

huiyu and others added 2 commits July 27, 2026 11:19
…ph (2.0.0)

Three principles (Jeff's): skills stay atomic; cross-skill routing lives
in bootstrap; project-state guidance replaces sequence enforcement.

RED baseline (detailed PRD on disk, user asks for design): mu-arch's gate
was keyed to a file path, not evidence — the PRD bought nothing but a
premise-check skip; the forced scope pass was 3-6 rounds of transcription
producing a derivative file that violates this repo's own one-fact-one-
place contract. pipeline-gate.sh was worse: skill-blind Edit/Write denial
with a bootstrap deadlock (the Write creating the first scope file was
itself denied for lack of a scope file), a structural conflict with the
micro exit, and a trivial Bash-heredoc bypass.

- bootstrap gains the Pipeline Graph: the single declaration of cross-
  skill handoffs. Edges consume EVIDENCE, not file paths; equivalents
  substitute (detailed PRD+object model ~ scope; inline plan ~ docs/
  plans); missing evidence -> recommend, user decides, declined
  recommendations are flagged. The recommendation is the agent's
  obligation; only the user can waive sequence.
- Gate taxonomy: sequence gates -> guided input-evidence blocks (mu-arch,
  mu-code); control gates (artifact approval) and safety gates (TDD,
  verification, git safety) stay hard and are declared never-
  substitutable in the graph.
- mu-scope gains the evidence fast path: with enumerating evidence in
  hand it contributes only its non-duplicated trio — Quick Probe,
  conflict cross-check, reverse UCs — one report, one confirmation
  (baseline: 3-6 rounds of re-interview).
- Skills shed cross-skill knowledge: hardwired "ONLY skill you invoke
  next" terminals become uniform Done lines; the graph is the authority
  (CLAUDE.md canonical-homes updated; CONTEXT.md gains Pipeline Graph).
- pipeline-gate.sh and its test removed; destructive-guard stays.

GREEN: evidence-substitution probe 4/4 (PRD accepted, scope collapses to
~1 round, no re-interview, override flagged not refused); guidance-floor
probe 4/4 (vague+no-evidence still recommends first; only the user
waives; TDD/verification never yield). Both persisted as regression
prompts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…PRD approval node

Three-lens review (atomicity / clarity / placement) of the v2.0 branch:

- Last enforcement-era leftovers removed: mu-arch's "Do NOT invoke any
  other skill", mu-plan's imperative "Invoke devmuse:mu-code" — both now
  Done-style handoffs deferring to the Pipeline Graph; flowchart terminal
  nodes rename to "Hand off". Default-successor naming in Done lines
  stays by design (adjacency); prohibitions and command-imperatives were
  the authority leakage.
- mu-prd gains the assembled-PRD approval diamond its HARD-GATE presumed
  (symmetric with mu-mrd's fix).
- README twins: pipeline-gate hook row deleted (hook was removed in
  33a26b7; the table still advertised it).
- mu-arch input-evidence wording clarified: run the fast path first,
  then design.

Reviewed-and-declined (recorded): per-task vs final review split is
intentional layering; discipline-skill rule repetition (TDD Iron Law +
Final Rule) is bulletproofing, not drift; Key Principles sections are
leading-word anchors, kept.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
huiyu and others added 18 commits July 27, 2026 11:54
Same GNU-timeout-missing bug the prd-state-modeling runner hit on its
first real run — skill-triggering, explicit-skill-requests, and both
claude-code integration runners silently never executed claude on
stock macOS. ${TO:+} degradation, syntax-checked.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…, disclose parallel dispatch

1044 -> ~845 lines, GREEN-verified no rationalization lost:
- Step 1 gains the isolation decision: worktree is the default for
  multi-task plans; small plans (1-2 tasks) branch in place with git
  safety + baseline tests. Flowchart and quick reference updated.
- "Why Order Matters" cut (its four rationales all survive as
  Common Rationalizations rows + red flags — verified one by one);
  "TDD Final Rule" cut (Iron Law is the single statement, general
  partner-permission escape valve restated there); "Common Worktree
  Mistakes" cut (steps + quick reference carry it).
- Parallel Dispatch (~125 lines) disclosed to parallel-dispatch.md
  behind an inline trigger, following the visual-companion precedent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… trim

stance-detection.md gains the Shared Consumption Protocol (confidence
handling, slash pre-confirmation incl. terminal-prompted slashes,
stance metadata, opt-out); mu-arch/mu-prd/mu-mrd Phase 0 collapse to
parameters + branch table + a one-line protocol pointer (~20 lines x3
deduplicated). Fresh create omits Sub-type and Detected-at — there was
no detection to record; both appear from the first update/extract
(template annotations in mu-prd/mu-mrd). GREEN findings fixed in-pass:
mu-arch's docs(specs) commit prefix pinned locally (was only in the
deleted paragraph); template wording aligned to update/extract;
mu-mrd's opt-out no longer claims a commit-convention fallback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- bootstrap: Instruction Priority now carries its WHAT-not-HOW
  counterweight inline (the two blocks sat ~135 lines apart — the seam
  most likely to open if either is edited alone).
- mu-scope: flowchart gains the evidence-fast-path branch (prose led,
  diagram lagged); one line under the HARD-GATE points sequence
  substitutions at the Pipeline Graph while pinning that UC approval is
  never agent-waivable.

First four live headless regression runs: 19/19 criteria PASS, no
regression vs simulated baselines ($4.23 total).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Full 9-scenario headless regression on the branch: 42/42 criteria PASS,
zero regressions, $10.35 total. Three watch items flagged by 2+ live
runs each, fixed with the runs as RED evidence (validation rides the
next routine suite run):

- Object-model auxiliaries now specified on every path: lightweight
  in-body form carries invariants/guarantees/negative space at
  proportionate size (was literally "one states+transitions table");
  update-sync explicitly covers excluded-candidates and non-transition
  notes.
- History's initial row must summarize the create round's key decisions
  — a bare "Initial creation" row is noise (both fresh-create runs
  flagged the ceremony).
- state-modeling self-check gains Q6 (async external operations —
  refund/payout/notification — need a user-visible failure state or an
  explicit exclusion; the groupbuy run caught refund-failure only via
  domain knowledge); sub-object example diversified beyond
  payment-in-order.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Codex (gpt-5.6-sol) reviewed the full branch diff; four P2 findings,
three real — all at the new-behavior x old-template seam my own review
passes missed:

- Requirements Reference genericized: mu-arch's required block and
  knowledge/templates/architecture.md hard-coded docs/scope paths,
  making evidence-substituted specs cite a nonexistent scope or violate
  their template. Now "Requirements evidence: scope | recorded
  equivalent".
- Waived-plan path made executable: mu-code's mode-selection digraph
  routed no-plan to a dead-end "Manual execution or brainstorm first";
  now recommend-mu-plan -> user waives -> derive tasks from evidence ->
  Inline Mode (isolation, TDD, verification, mu-review), flag in report.
- History placeholders aligned with the new rule: mu-prd/mu-mrd/
  architecture templates emitted the exact bare "Initial creation" row
  the shared protocol now rejects.

Declined: CONTEXT.md:27-29 finding — those lines are the NEW Pipeline
Graph entry (correct content), a misread; the wiki's stale
pipeline-gate links are real but wiki is generated (regen at the v2.0
milestone post-merge, per the docs contract).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
User-requested audit of every remaining <HARD-GATE> against the v2.0
taxonomy. Verdict: all five surviving gates are control gates (user
approval of a deliverable before what depends on it) — mrd/prd/scope
approval-before-downstream, arch design-approval-before-code, explore
artifact-persisted-and-confirmed-before-handoff. None is sequence
enforcement; all stay.

Cleanups the audit surfaced:
- "HARD-GATEs evaluated BEFORE Phase 0" x3 deleted — factually obsolete
  (post-v2.0 no gate fires before Phase 0); the surviving semantic
  (skip never bypasses approval) moves to the Shared Consumption
  Protocol as one sentence.
- mu-mrd's gate sheds a process instruction that had drifted into it
  ("Two depth modes — pick one explicitly", already covered by Key
  Principles' "Mode is explicit").
- mu-explore's gate drops the retired "Design-tech" routing vocabulary.
- sign-off-gate.md's HARD-GATE definition updated: its example ("no
  design without scope") was precisely the gate v2.0 turned into
  evidence guidance; now defines gates as control gates with current
  examples.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
UC-ERR2 degrade (deleted relevant files: mu-biz rename, pipeline-gate
removal) + >60% staleness forced generate over update. New structure:
pipeline-graph and product-object-model earn dedicated pages; hooks fold
into four-layer-arch; gates/evidence fold into pipeline-graph; scope+arch
merge into core-pipeline; on-demand-skills becomes market-product-
analysis. 13 pages, 34-66 line-level citations each, structure agent's
stale pre-v2.0 assumptions corrected before dispatch.

Also fix(CONTEXT.md): the Codex finding I wrongly dismissed — its line
numbers pointed at the new Pipeline Graph entry, but the stale content
was real at lines 39/85: the retired "Pipeline gate" term, the
"enforces mechanically (hook)" relationship, the deleted before-Phase-0
meta-rule, and the retired Design-tech opening move. All cleaned; the
gate-vocabulary ambiguity note now records the retirement.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The existing qualification test (project-specific / compression /
recurring, soft cap ~25) optimizes for consistent naming and token
economy — so it produces a glossary. Measured across three repos:
spine 0/3, time axis 0/3, History 0/3. devmuse's own CONTEXT.md is
fully compliant with the old rules yet cannot answer "what is this
system made of" — compliant and useless for settling design.

- Qualification is now load-bearing (the model cannot be stated without
  the entry), isolates out; the term cap is gone — the necessary concept
  count is set by the domain, not by a context budget
- Borrowed industry terms qualify on the same test and owe one line on
  how this project's meaning differs — a debt to pay, not grounds for
  removal
- Structure 3 sections -> 7 (principles / worked example / concept table
  / spine / structure overview / details / History)
- New one-way dependency rule (CONTEXT never cites prd|specs|plans),
  machine-checkable by grep
- _Avoid_ returns to a per-entry line; as a standalone section it turns
  into a junk drawer for unrelated prohibitions

Also resolves the conflict this exposed in state-modeling.md: machines,
invariants and excluded candidates now live in CONTEXT.md §6 — mu-prd
writes them, mu-arch and mu-scope read them. docs/prd/*.objects.md is no
longer produced; 17 references cleared. Regression suite realigned —
update-stance-companion renamed to -machines with its scenario rewritten,
lightweight-stateful now probes that the machine's home does not shift
with depth mode.

A test probe surfaced a gap the new rules had not answered: which History
receives a machine edit versus a PRD body edit. Now split explicitly —
CONTEXT.md §7 for the model, the PRD's own table for its body.

Validated against three real CONTEXT.md files rather than subagent
pressure scenarios (Agent tool unavailable this session): the new exit
criteria score aflaj 5/5 after restructuring, zuiti 0/5, devmuse 0/5.
Agent-behaviour testing under the new rules is still owed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
Dogfooding E0 on this repo. The old file scored 0/5 against the new exit
criteria — no spine, no time axis, no History, no worked example, no
concept table. A fully compliant glossary that cannot answer "what is
this system made of".

The spine derivation surfaced the real gap: `Artifact` had no entry at
all, while eight concepts *about* artifacts did (stance, control gate,
HARD-GATE, evidence, Pipeline Graph, living-artifact, Use Case Set,
sign-off gate). `Evidence`, `Control gate` and `Safety gate` were missing
too — all three load-bearing in rules/bootstrap.md, injected into every
session, never defined.

- 21 concepts, 7 sections, spine = the life of an artifact
- Stance restated as a function of the artifact's detected state rather
  than of the task's phrasing, with the state -> stance map made explicit
- Four domain guarantees, including: a control gate never yields to an
  override — guidance-over-control governs recommendations, not
  approvals, since the user is the approver

Also aligns the three version strings on 2.0.0 (package.json was 1.0.0,
marketplace.json 1.2.0, plugin.json already 2.0.0) — a marketplace
install was carrying stale metadata.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
…ing skills

Templates guarantee the sections exist; nothing guaranteed they could be
used. aflaj spent two full days (2026-07-28/29) reworking documents that
were structurally complete and unreadable — 20+ commits whose own titles
are the rule set: "put content first", "gloss terms at first use", "show
the derivation", "one question per column", "kill two letter/number
collisions".

Nine rules, distilled from that rework plus the writing discipline Jeff
wrote into aflaj's research agenda on 07-30 — extracted, not invented:

1. Conclusion first — the title states the question answered
2. Meta belongs in the appendix
3. Show the derivation — if there is nothing to disagree with, only an
   assertion was written
4. Gloss on first use
5. One column, one question
6. One symbol, one meaning
7. One metaphor, carried through
8. Readable body, rigor in footnotes
9. State absence as absence — "none found in this round", with the scope
   that was searched

Wired into the write-artifact step of mu-mrd, mu-prd, mu-arch, mu-scope,
mu-plan, mu-explore, mu-wiki and mu-retro — all of them, so no artifact
type gets drafted without it.

Dogfooding caught one on contact: mu-explore's process carried two step
8s (rule 6). Renumbered 8-13.

Also backfills CONTEXT.md's History sha (c6a4a60).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
…oven

The modeling pass had rules (domain-model.md), a template (context-md.md),
a method (four archetypes + spine derivation), and two worked originals
(aflaj restructure, devmuse rebuild) — but no executor. No skill's flow
ran it and bootstrap's routing table had no entry, so "help me sort out
what these concepts are" had nowhere to go.

- On-demand (slash-only), same tier as mu-prd: modeling is a
  once-per-product decision, not something a vague intent should trigger
- mu-prd and mu-arch now check for CONTEXT.md at entry and recommend
  /mu-model when it is absent — non-blocking, so being un-routed does not
  mean being forgotten
- Pipeline Graph: mu-mrd -> /mu-model when no CONTEXT.md, else /mu-prd
  create; mu-model -> /mu-prd, or mu-scope directly when a PRD exists

Seven steps producing the seven sections. Step 2 carries the load: ask
"what changes, and when?" rather than "what concepts are there?" —
concept-first questioning yields a noun list with no lifecycles, which is
exactly the failure mode measured across three CONTEXT.md files.

**create ships unproven.** update and sync were derived from two real
runs; create was reasoned from Event Modeling and Four-Color archetypes
and has never been run on a project starting from zero. Marked with a
validation banner at the top of the skill body and 🧪 in both READMEs,
with a Validation status section naming the exit criterion: two
independent projects with no process fix, then the mark drops. One clean
run is luck.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
…age)

GitHub search surfaced two skills built on the same CONTEXT.md mechanism
this repo borrowed from mattpocock/skills — sammcj/agentic-coding and
AgentiveStack/skills. Same origin, opposite direction: both hold the line
at "it is a glossary and nothing else", where this repo promoted the file
to a domain model. That divergence is a positioning choice and stands, but
their session discipline is better than ours and transfers directly.

1. Four postures running through every stance rather than as steps —
   challenge against the model, sharpen fuzzy language, stress-test with
   concrete scenarios, cross-reference with code; capture as they resolve
   instead of batching. Scenario stress-testing becomes the second
   instrument for surfacing concepts in `create`, where the time axis was
   the only tool and the step had no practical basis at all.

2. `sync` promoted from stance-only to reflex: a domain fact found living
   downstream, or a model claim the code contradicts, is raised on the
   spot. The stance stays for drift large enough to warrant its own pass.

3. Multi-context criterion restored — removed by accident when the soft
   cap went away, leaving no answer to "when does one CONTEXT.md become
   several". The replacement is semantic rather than numeric: split when
   one term carries two meanings for two audiences and neither side can be
   renamed. An open ambiguity that cannot be ruled because both readings
   are correct for their own audience is exactly that signal. Form
   borrowed from both skills — root CONTEXT-MAP.md plus per-context
   CONTEXT.md, split on the collision and never in anticipation of one.

Not absorbed: multi-persona workshop simulation (majiayu000's
event-storming — five debating personas at ~15K tokens per run). It does
solve Event Storming's "needs a room full of people" problem for solo
work, but stacking a fleet on top of an unvalidated single-agent sequence
buys complexity before correctness.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
Measured on a real repo: blibee's group-agent feature carried four spec
files across six days — group-chat-agent-design, group-agent,
frontend-api-changes-group-agent, group-agent-bot-api — with zero
cross-references. The cost is not the file count. It is that no file
states its relationship to any other, so a reader date-sorts and guesses
— and the *oldest* file is what a date-sorted listing surfaces first.

stance-detection.md governs living artifacts: one file, entered in place.
It has nothing to say about dated snapshots, which are many files by
design. New principle artifact-succession.md fills that gap:

- One question before writing, never a loop: "found <path> covering what
  looks like the same work — continuing it? (continue / new / unrelated)".
  Detection proposes on keywords ∩ headings and touched paths ∩ referenced
  paths; the four names above show why matching on filenames alone fails.
- Three relations, selected by whether the prior artifact was consumed —
  checkable, not a judgment call: a scope is consumed once a spec's
  Requirements Reference cites it, a plan once any checkbox reads [x].
  Unconsumed -> revise in place, filename and date unchanged. Consumed ->
  new file carrying Supersedes or Extends.
- Both directions written. A one-way link leaves the older file silently
  wrong for whoever opens it first.

Wired into mu-scope (checklist step 0), mu-plan (Prior Plan Check), and
mu-arch (succession runs before stance — a spec is dated, so "a new file
at all?" precedes "how is this one entered?"). Header fields added to the
scope and architecture templates and to mu-plan's plan header.

For the living side: mu-prd now states that update/extract write back to
the detected file with filename and date unchanged, and that a PRD
outgrowing one file keeps a main file carrying the header, stance and
History with parts indexed beneath it. Nine sibling files with no History
between them cannot be entered by `update` at all — only re-created,
which is the failure this whole series started from.

Dogfooded into this repo's own CONTEXT.md: `Superseded` added to the
Artifact machine as a state reachable from `Frozen`. Frozen was terminal,
leaving no way to say "still immutable, but no longer the one to read".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
… reading by risk

Q4 of the original four — "the pipeline feels long on fast-iterating
products; sometimes you want to build one first and adjust after" — was
the only one never touched. The pipeline had two speeds: full ceremony, or
abandoning discipline and calling the result a feature.

RED came out of aflaj, which had already invented the missing piece by
hand: `spikes/semantic-inference/` exists, sits outside the workspace with
its own lockfile, and carries a commit literally titled "say what the
spike is not". Nothing in bootstrap's routing table could ever have led
there.

Three rules, extracted from that directory rather than invented:

1. Isolate physically, not by convention. That spike declares an LLM SDK;
   only being outside the workspace with its own manifest keeps the main
   tree's "zero AI on the data path" red line absolute instead of caveated.
2. Register what it does NOT answer — top of the README, day one. A
   half-run spike is the most dangerous artifact in a repo because it
   looks like evidence. Measured failure: a feasibility ledger cited a
   spike whose scoring columns were empty, from a superseded copy of the
   directory.
3. The product is a starting point, not a component. Spike code is never
   promoted; when the verdict says build it, that is a new scope with the
   spike as evidence.

Routing: new opening move, ordered above `implement` because 先做一个看看
carries an implement verb. Gated on the question being nameable — "I don't
want to write a scope" is an override the user states at the scope gate,
not something laundered through a spike.

mu-scope gains a spike exit beside the micro exit, with the two explicitly
distinguished: micro is "small enough to skip the artifact", spike is
"unknown enough that the artifact would be fiction". Neither routes around
the scope gate — micro still states its UC, spike still returns a verdict.

C1: the wiki hint in the probe output — one non-blocking line — becomes a
three-tier table keyed on probe risk. At the top tier (high risk, crosses
>=2 top-level modules, or unfamiliar per git log --author) the map is
generated before the impact analysis, because an impact analysis against
an un-mapped codebase is a guess wearing a number. Still non-blocking;
declining is recorded in the scope itself.

Dogfooded: spike READMEs join the living-artifact form in this repo's
CONTEXT.md — the thinnest one, no reviewer loop since it records an
observation rather than a decision, but still approved, because a scope
gets built on its verdict.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
…e state; ADRs get one

Three artifacts were describing the same thing in different files, each
declaring in prose that it was not the other two: mu-explore's artifact,
mu-wiki's pages, and the global C4 diagram every design spec redrew. Q5-Q7
of the original list.

B2 — wiki pages gain two zones. `<!-- mu-wiki:generated -->` is rebuilt by
the tool; `<!-- mu-wiki:curated -->` is hand-maintained and passed through
verbatim on update. The old `never hand-edit` rule was not wrong, it was
too wide: it also banned the only content nobody can regenerate — coverage
gaps, doc-vs-code contradictions, decisions the code does not explain. A
one-line rule was standing in for a missing mechanism.

B1 — `docs/wiki/` is declared the single home of architecture state. What
makes it safe to treat as authoritative is that it is rebuildable: when it
disagrees with the code, the wiki is wrong and one regeneration settles
it. That property is also why it cannot hold decisions.

B3 — mu-arch draws only the neighbourhood a change touches and cites wiki
pages for the surrounding picture. A spec that redraws the global diagram
creates a second copy that drifts from the day it ships, and specs freeze
while the system keeps moving.

B4 — reflow runs in mu-review after integration, never during design: a
decision the review round overturned would otherwise already be sitting in
the architecture's single home.

B5 — ADRs move to `docs/adr/NNNN-slug.md`, one global sequence. Measured
failure: a project ran ADR-1..17 across three spec files, needed a commit
purely to fix their ordering, and its README could not link to them for
lack of a stable address. New principle adr.md carries the earns-one test
(real fork ∧ expensive to reverse ∧ reasoning otherwise lost — ADR
inflation being the failure mode) and the boundary against CONTEXT.md §7:
a vocabulary ruling is a History row, an architecture ruling is an ADR.
Pre-existing inline ADRs stay put; moving them would retro-edit a frozen
artifact.

Dogfooded: decision record added as the Artifact's third form in this
repo's CONTEXT.md. Its states map onto the existing machine exactly —
Proposed is Drafted, Accepted is Approved, superseding appends rather than
edits. What separates it is that it is not rebuildable: the wiki can be
regenerated from source, but a rejected alternative leaves no trace there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014PCWdYeNXtBsdJsbLrdN2j
Add Direct, bounded, and architectural routing; retire redundant explore/wiki artifacts and per-task review fan-out; align skills, docs, and regression tests.
@huiyu
huiyu merged commit a7addc4 into main Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant