diff --git a/.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md b/.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md new file mode 100644 index 000000000..3e6954300 --- /dev/null +++ b/.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md @@ -0,0 +1,141 @@ +--- +id: 0242 +title: the eight fabrika skill nouns enter the register, and build and review are redefinitions +status: accepted +date: 2026-08-09 +tags: [fabrika, glossary, vocabulary, pipeline] +--- + +# 0242 — the eight fabrika skill nouns enter the register, and `build` and `review` are redefinitions + +**What this decides:** the eight skill names the fabrika partition locked — `build`, `build-ui`, +`review`, `review-ui`, `governance`, `build-epic`, `front-door`, `check-epic-plan` — are canonical +domain nouns and get rows in [`.glossary/TERMS.md`](../.glossary/TERMS.md). Two of them displace a +meaning that is live in this repo today, and this entry is the dated record of that displacement. +`review-ui` also shares its spelling with a name coined, for a different scope, by ADR +[0144](0144-depo-internal-asset-cdn.md); §4 records how the two coexist. + +## Context + +The founder locked fabrika's skill set on wayfinder:map +[#4891](https://github.com/kamp-us/phoenix/issues/4891) (2026-08-08). Epic +[#4904](https://github.com/kamp-us/phoenix/issues/4904) transcribed that partition onto the board — +fourteen children, all landed — and its `### Vocabulary impact` block named the eight nouns the whole +authoring wave now builds against. It deliberately minted no child for the glossary rows: the epic's +item list was founder-fixed and transcription-only, so it routed them out as follow-up +([#4919](https://github.com/kamp-us/phoenix/issues/4919)). + +Until now the only durable statement of the eight names was an issue body, which is not canon. That +matters most for the two names that are not additions: + +- **`review` was a family.** ADR [0079](0079-reviewer-authored-acceptance-criteria.md) says "all four + `review-*`"; ADR [0226](0226-cp-advisory-never-carries-a-failing-criterion.md) says "the four review + gate templates". The directory is wider still — + [`claude-plugins/kampus-pipeline/skills/`](../claude-plugins/kampus-pipeline/skills/) carries **six** + `review-*` skills. So the word names a family of four in the decision corpus and six on disk, and + after #4904 it names one skill. +- **`build` was the general act.** `CLAUDE.md` uses `pnpm build` as the build verb; the `platform lane` + row in [`.glossary/TERMS.md`](../.glossary/TERMS.md) defines itself as "an active build lane"; every + ADR names the builder `write-code`. + +A renamed-but-unrecorded noun does not fail loudly. It gives a reader a confident wrong answer — the +failure mode this repo keeps paying for. And `TERMS.md` cannot fix it alone: the register is +present-tense with no history, so a row that replaces a meaning represents the *new* reading and +erases the fact that a reading moved. A register can state a term. It cannot state a diff. That is +what this entry is for. + +## Decision + +### 1. The eight nouns are canon, and each gets a `TERMS.md` row + +They name fabrika skills under the modality partition: the factory is cut by **text versus +rendered-visual**, symmetrically on both sides — `build` / `build-ui` constructing, `review` / +`review-ui` judging — plus `governance` (corpus integrity, guarding from outside), `build-epic` (the +conductor), `front-door` (the `/fabrika` operating entry) and `check-epic-plan` (plan-checking, in the +planning lane). + +Each row states **only the current reading**. The register describes what a word means now. + +### 2. `build` — from the general act to one skill, without erasing the general act + +**Before:** the act of building, in three live senses — the `pnpm build` compile step, the *build lane* +of the WIP model, and the v1 builder skill `write-code`. + +**Now:** `build` names fabrika's **text-construction skill** — code, prose and plans, and nothing +rendered-visual (brief [#4707](https://github.com/kamp-us/phoenix/issues/4707), amended under +[#4906](https://github.com/kamp-us/phoenix/issues/4906)). The three UI-only branches that lived inside +v1 `write-code` move out to `build-ui`. + +**The other senses survive as compounds and are not renamed.** `pnpm build` is still the compile step; +*build lane* is still the WIP unit. What changed is that the **bare noun**, in a fabrika context, now +names a skill. This is a homonym we accept rather than a rename we propagate: rewriting `pnpm build` +or *build lane* to dodge the collision would churn two settled vocabularies to protect a third. The +`Not` column carries the boundary. + +### 3. `review` — from a family to one skill, and the family disperses six ways + +**Before:** the review family. Four in the corpus, six on disk. + +**Now:** `review` names fabrika's **one text-review skill**, emitting **N namespaced verdicts** rather +than N skills each emitting one (brief [#4959](https://github.com/kamp-us/phoenix/issues/4959)). The +verdict-marker format already admits it: its namespace class is `/^review(-[a-z0-9]+)*$/` in +[`packages/fabrika-cli/src/wire/verdict-marker.ts`](../packages/fabrika-cli/src/wire/verdict-marker.ts), +so `review`, `review-code`, `review-doc` and `review-skill` all conform unchanged. + +The collapse is **not** a four-to-one merge, and calling it one understates what moved. The six v1 +`review-*` skills disperse four ways: + +| v1 skill | where its judgement goes | +|---|---| +| `review-code`, `review-doc`, `review-skill` | absorbed into `review` as three rubric **files**, under the leaf rule (a leaf becomes a skill only when consumed by ≥2 skills or needing its own eval identity) | +| `review-plan` | out of the review family entirely → **`check-epic-plan`**, in the planning lane ([#4948](https://github.com/kamp-us/phoenix/issues/4948)) | +| `review-design` | renamed → **`review-ui`** ([#4718](https://github.com/kamp-us/phoenix/issues/4718)) | +| `review-trivial` | killed ([#4715](https://github.com/kamp-us/phoenix/issues/4715)) | + +Two judgements are carved out of the absorbed three rather than travelling with them: +**governance-corpus integrity** (v1's ADR-contradiction sweep in `review-doc` plus its +gate-invariant-preservation check in `review-skill`) becomes the dedicated **`governance`** skill, +which `review` invokes and does not own; and **visual calibration** is `review-ui`'s. + +### 4. `review-ui` — two distinct names that coexist; this entry claims nothing over ADR 0144 + +ADR [0144](0144-depo-internal-asset-cdn.md) already coined `review-ui`: "the Playwright step that +captures UI screenshots on UI-affecting PRs and embeds them via `depo put` is a distinct new +**`review-ui`** skill, filed as its own epic." That is a narrower scope than #4904's visual-modality +gate, so a reader who meets the bare name needs to know which one is meant. + +**In a fabrika context, `review-ui` names the visual-modality review gate.** That is a statement about +fabrika's own vocabulary and nothing more. **ADR 0144 is not overturned** — it keeps `status: accepted` +and every word of its decision text (founder ruling (a), 2026-08-08 on epic +[#4904](https://github.com/kamp-us/phoenix/issues/4904), transcribed into +[#4951](https://github.com/kamp-us/phoenix/issues/4951)). The two names coexist, and the qualifying +note #4951 adds at 0144's clause is what tells a reader landing there which reading is which. + +The coexistence is safe because the two readings converge on one artifact rather than competing for it: + +- **0144's `review-ui` was never built as a skill.** No `review-ui` directory exists under any plugin. +- **Its function was built — inside the gate that now carries the name.** The capture-and-embed leg + landed as `review-design`'s evidence path over the `@kampus/design-capture` seam, with the bytes in + depo per ADR [0183](0183-golden-screen-storage-depo-git-pointer.md). +- **#4904 renames that gate `review-ui`**, and its brief is explicit that `review-design` "is **not** a + second skill and **not** a predecessor to be ported: it is this same skill under its superseded name." + +So the capture step is a **leg of the visual gate** rather than a standalone skill — a fact about what +got built, not a supersession this entry asserts. depo's own decision, and the decoupling 0144's clause +protects, stand untouched. + +## Consequences + +- `.glossary/TERMS.md` gains a `fabrika skill nouns` section with the eight rows. The `build` and + `review` rows carry their superseded reading in the `Not` column, pointing here. +- A reader of any pre-#4904 ticket, ADR or skill doc that says `build` or `review` has one place to + learn that the word moved and what it used to mean. +- **No landed ADR is edited by this entry — not its decision text, not its status line.** ADR 0144 + keeps `status: accepted`; the qualifying note that disambiguates the shared `review-ui` name is + #4951's to write, not this entry's. ADR 0079's "all four `review-*`" and ADR 0226's "the four review + gate templates" stay untouched too — nothing supersedes them; they describe v1, which is frozen and + still on disk. This entry is the bridge, not a retraction. +- The register alone would not have carried this. Every future redefinition of a live noun needs the + same pair — a row for the new reading, a dated entry for the change. +- Nothing here re-opens a ruling. Every name is founder-fixed on #4891 and transcribed by #4904; this + entry records vocabulary, it does not decide scope. diff --git a/.glossary/TERMS.md b/.glossary/TERMS.md index 95d9e7736..c43dc2d3c 100644 --- a/.glossary/TERMS.md +++ b/.glossary/TERMS.md @@ -377,6 +377,29 @@ and ADR [0162](../.decisions/0162-four-pillars-design-law.md) (the four-pillars | `@agent` directive | A **human-seeded JSDoc tag** on a component (ADR [0194](../.decisions/0194-design-law-jsdoc-firewall.md)) that steers the extractor — the *protected seed* the generate step must preserve rather than overwrite. Rides alongside the descriptive tags (`@component`, `@slot`, prop docs) that source the component inventory; keeps the tag vocabulary lean, a deliberately-minimal v1 expected to evolve with real use. | a descriptive tag the extractor regenerates (`@component`/`@slot`/prop docs are generated; `@agent` is preserved); design law (a directive steers extraction, it does not mint pillars/prohibitions/role tokens); a frozen final schema (the tag vocabulary iterates as gaps surface) | | taste skill (the taste voice) | The factory's design-taste primitive (ADR [0209](../.decisions/0209-taste-voice-per-aspect-skills.md)): a library of **per-aspect taste skills** — strict generative rules with the *why* attached (decision tables with hard thresholds, text flowcharts, imperative + concrete-value + one-line-why + named-counterexample rules) — loaded by name into existing generalist agent spawns (coder/planner) when creating UI. Grounded exclusively in the repo design law: the manifest (ADR [0162](../.decisions/0162-four-pillars-design-law.md)), the descriptive inventory (ADR [0194](../.decisions/0194-design-law-jsdoc-firewall.md)), the blessed goldens (ADR [0183](../.decisions/0183-golden-screen-storage-depo-git-pointer.md)); seeded from `emilkowalski/skills` (MIT, attributed) plus repo-grown manifest-grounded seeds for the uncovered aspects. **The taste voice** names the primitive as a whole. The library lives under [`claude-plugins/kampus-pipeline/skills/`](../claude-plugins/kampus-pipeline/skills/taste-library-conventions.md) as `taste-/` dirs (`taste--/` where one aspect needs several procedures), each `SKILL.md` optionally paired with a values-only `STANDARDS.md`, and every rule tagged **LAW** (cited to the design law, binding) or **CRAFT** (an advisory default that yields to LAW). | a persona agent or a new agent def (it loads into existing spawns); an author of normative design law (the 0194 firewall holds — law changes flow through ADR-ratify→transcribe); a fourth design artifact (it consults the three that exist); a replacement for the gate substrate (`agent-browser` composes with `design-capture`/`local-render` + the golden canon); a control-plane surface (a `taste-*` dir stays `.sh`-free, which is what keeps it out of CODEOWNERS) | +## fabrika skill nouns (the modality partition — epic #4904) + +The eight skill names the founder locked on wayfinder:map +[#4891](https://github.com/kamp-us/phoenix/issues/4891) and epic +[#4904](https://github.com/kamp-us/phoenix/issues/4904) transcribed. The factory is cut by +**modality** — text versus rendered-visual — and the cut is symmetric on both sides: `build` / +`build-ui` construct, `review` / `review-ui` judge. Two of the eight **redefine** a reading that is +live in this repo; the dated record of what each word meant before is ADR +[0242](../.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md), and the rows below carry +only the current reading. These name **fabrika** skills (`claude-plugins/fabrika/skills/`), not the +frozen v1 skills of `claude-plugins/kampus-pipeline/`. + +| Term | Definition | Not | +|---|---|---| +| build | fabrika's **text-construction** skill (brief [#4707](https://github.com/kamp-us/phoenix/issues/4707), renamed from v1's `write-code` under [#4906](https://github.com/kamp-us/phoenix/issues/4906)): it constructs code, prose and plans — one loop plus per-surface reference files, not a router. **Redefinition** — ADR [0242](../.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md) §2 records what the bare noun meant before. Rendered-visual construction is **not** its scope; that is `build-ui`. | the `pnpm build` compile step, or the **build lane** of the WIP model (both survive as compounds and are NOT renamed — the bare noun in a fabrika context names the skill, and ADR 0242 §2 accepts the homonym rather than propagating a rename); v1's `write-code` (the frozen baseline, read for its scars, never ported — ADR [0238](../.decisions/0238-fabrika-reimplements-v1-never-calls-it.md)); a router that hands off per surface | +| build-epic | fabrika's **epic conductor** (brief [#4950](https://github.com/kamp-us/phoenix/issues/4950)): the skill that turns a planned epic into **one** pull request — the conductor holds the plan and one branch, each commit is produced by a **fresh subagent**, and it trusts artifacts (commits, validator verdicts) over any subagent's self-report. Founder-named `build-epic`, superseding the working label *epic-conductor*. | one long session doing everything (the correction that produced this shape — each commit forks a fresh context); one PR per child (the whole point is one PR per epic); `plan-epic` (that writes the plan; this executes it) | +| build-ui | fabrika's **design-system construction** skill (brief [#4941](https://github.com/kamp-us/phoenix/issues/4941)): it generates and edits user-facing visual surfaces against the four-pillars design law (ADR [0162](../.decisions/0162-four-pillars-design-law.md)), and owns nothing textual. The visual half of the modality line, ruled on the measured evidence that the UI sample first-passes the design gate ~60% FAIL against ~12–20% for code. | `build` (code, prose and plans — anything text); `review-ui` (that **judges** a rendered surface; this **constructs** it); a mode or branch inside `build` (the split is structural, not conditional) | +| check-epic-plan | fabrika's **plan-checking** skill (brief [#4948](https://github.com/kamp-us/phoenix/issues/4948)), in the **planning lane** — the planner's downstream neighbour, not its replacement: a 100%-deterministic floor expressed as a verb (the hard-defect set of the epic ledger) plus a thin **advisory** judgement layer over it (acceptance-criteria checkability, brief fidelity) that annotates a pass and never blocks. | a member of the review family (plan-quality was moved **out** of it — `review` must not absorb it); `plan-epic` (that writes the ledger; this decides whether it clears the floor); a second blocking reviewer (the real judgement it holds is advisory by construction, ADR [0047](../.decisions/0047-review-plan-gate.md)) | +| front-door | fabrika's **operating** entry point (brief [#4952](https://github.com/kamp-us/phoenix/issues/4952)): the human-typed `/fabrika` skill that orients a cold **operating** session with live status and a command menu. It exists because fabrika orients a fresh *authoring* session completely (three convention docs) and a fresh *operating* session not at all. | an authoring entry point (the authoring docs already cover that); a dispatcher that does the work (it orients — what is in flight, what is blocked, which skill to reach for) | +| governance | fabrika's **governance-corpus integrity** skill (brief [#4949](https://github.com/kamp-us/phoenix/issues/4949)) — the single owner of one judgement with two halves, both homeless in v1: does a change **contradict the decision corpus** (v1's ADR sweep, embedded in `review-doc`), and does it **quietly weaken a gate** (v1's gate-invariant-preservation check, embedded in `review-skill`). It guards from **outside** the review skill: on a harness-touching diff its namespace is derived-required, so a `review` PASS with no governance verdict is not a complete gate result. | a part of `review` (`review` **invokes** it and does not own it); a general policy skill (exactly the two judgements above); a merge-gate substitute (it emits a verdict in its own namespace) | +| review | fabrika's **one text-review skill** (brief [#4959](https://github.com/kamp-us/phoenix/issues/4959)): a single gate that judges every *textual* artifact class — code, docs, skills — and emits **N namespaced verdicts** rather than N skills each emitting one (the marker format already admits it: namespace class `/^review(-[a-z0-9]+)*$/` in [`verdict-marker.ts`](../packages/fabrika-cli/src/wire/verdict-marker.ts)). Per-surface leaves are **rubric files**, promoted to a skill only when consumed by ≥2 skills or needing their own eval identity. **Redefinition** — see ADR [0242](../.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md) §3. | the v1 **review family** — four `review-*` in the decision corpus (ADRs [0079](../.decisions/0079-reviewer-authored-acceptance-criteria.md), [0226](../.decisions/0226-cp-advisory-never-carries-a-failing-criterion.md)) and **six** on disk. The six disperse four ways, not one: `review-code`/`-doc`/`-skill` absorbed as rubric files; `review-plan` → **`check-epic-plan`**; `review-design` → **`review-ui`**; `review-trivial` **killed** ([#4715](https://github.com/kamp-us/phoenix/issues/4715)). Also **not** the owner of governance-corpus integrity (that is `governance`, invoked from outside) or of visual judgement (`review-ui`) | +| review-ui | fabrika's **visual-modality review gate** (brief [#4718](https://github.com/kamp-us/phoenix/issues/4718)): it judges **rendered-visual** artifacts against the four-pillars design law (ADR [0162](../.decisions/0162-four-pillars-design-law.md)), as a **calibrated judge of this repo's founder-ratified law** — rubric-grounded pairwise screenshot judging, never a general taste model. Renamed from v1's `review-design`, which is the same skill under its superseded name, never a predecessor to port. | the same name as ADR [0144](../.decisions/0144-depo-internal-asset-cdn.md)'s `review-ui` — 0144 coined that spelling for a standalone Playwright-capture-and-`depo put` skill. The two are **distinct names that coexist**, and neither supersedes the other: 0144 keeps `status: accepted` (founder ruling (a), 2026-08-08 on epic [#4904](https://github.com/kamp-us/phoenix/issues/4904)), and a qualifying note at its clause ([#4951](https://github.com/kamp-us/phoenix/issues/4951)) is what disambiguates a reader landing there. 0144's skill was never built; its capture-and-embed function landed as a **leg** of this gate over the `@kampus/design-capture` seam (ADR [0183](../.decisions/0183-golden-screen-storage-depo-git-pointer.md)), and ADR [0242](../.decisions/0242-fabrika-skill-nouns-redefine-build-and-review.md) §4 records how the two readings coexist. Also not `build-ui` (that constructs; this judges) and not a text gate (`review`) | + ## Apps | Term | Definition | Not |