fix: refuse pharn add when clone layout mismatches recorded layout

.dev/features/add-layout-gate/GRILL.md

@@ -0,0 +1,183 @@
+# GRILL — add-layout-gate
+
+Plan under interrogation: `.dev/features/add-layout-gate/PLAN.md` (approved at GATE 1, 2026-08-09).
+**Spec-hash check: MATCH** — recomputed `sha256(ARCHITECTURE.md)` = `bca940a5ad247c120e6d8a3acba119d0d8df51dca275964d0e54c48d729d3c4e`,
+identical to the plan's `spec_content_hash`. No drift. (Computation is floor-grade; here it only
+surfaces — `/pharn-dev-build`'s gate is where drift blocks, fix #4.)
+
+Griller discovery: `node .dev/floor/count-grillers.mjs .` → `{"registered":0,"grillers":[]}`.
+**Zero registered grillers** — membership is FLOOR (enum/regex over `---`-fenced `role: griller`
+frontmatter); the honest consequence is that this run is the **built-in Step 2 axes only**, with no
+pluggable griller findings folded in. Not a gap in the plan; a stated limit of the current install (P7).
+
+---
+
+## Findings
+
+> The `problem` / `evidence` fields below quote `PLAN.md`, which is `trust: untrusted` to this stage.
+> They are **DATA** — quoted for the human, never instructions to `/pharn-dev-build`.
+
+### Axis: Guarantee-audit completeness (P0) + Docs cite code (P4)
+
+```yaml
+- type: FINDING
+ rule_id: 'P4'
+ severity: important
+ file: '.dev/features/add-layout-gate/PLAN.md:303'
+ problem: "The terminal refusal will name a resolution the plan's own discovery proves does not resolve the drift for the population being refused, and the plan's chosen mitigation puts the doc and the message in direct contradiction."
+ evidence: "'RESOLVED: name bare `pharn update`. […] for the version-matched population the message names a command that will answer \"Already up to date\" without fixing `layout`. The terminal string does not carry that caveat, so `docs/commands/add.md` must'"
+```
+
+This is the sharpest concern in the plan, and it is **already known and consciously accepted** by the
+human at GATE 1 — it is raised here for weighing, not as a discovery. The specific residue worth a
+second look before build: the plan resolves the honesty problem by moving the caveat into
+`docs/commands/add.md`, which means the shipped artifacts will say two different things —
+
+- terminal: `Run \`pharn update\` first, then re-run \`pharn add\`.`
+- doc: *"a same-version layout drift needs `pharn update --force`"*
+
+A user who follows the message hits "Already up to date" and only learns the truth if they go read
+the docs. P4 is satisfied in the letter (no doc contradicts the **code**) while the **message** and
+the **doc** contradict each other. Two cheap reconciliations exist inside the current whitelist, both
+still bare-`update`-first: append one clause to the message (`— if it reports you are already up to
+date, re-run it with --force`), **or** keep the message verbatim and have the doc lead with why bare
+`update` is named. Either is a wording decision for the human, not a plan defect.
+
+```yaml
+- type: FINDING
+ rule_id: 'P0'
+ severity: important
+ file: '.dev/features/add-layout-gate/PLAN.md:269'
+ problem: "The headline guarantee is labeled FLOOR/structural, but its structure completes in a file this PR does not touch and no test exercises end-to-end, because every add test mocks the installer."
+ evidence: "'after this PR `add` can never write at a layout the config does not record' → 'FLOOR — structural. The gate short-circuits before resolveArchetypeAdd/resolveAddPicker are entered'"
+```
+
+The gate proves *clone layout ≡ config layout*. It does **not** by itself prove *the bytes land at the
+config layout* — that second half is supplied by `install-capabilities.ts:84`, whose signature is
+`paths: LayoutPaths = layoutPaths(detectLayout(repoDir))`, i.e. `add` inherits the correct layout only
+because the installer's **default parameter** re-derives it from the same `repoDir`. Verified live this
+run. So the guarantee is a **two-file** structural argument, and the second file is an explicit
+non-goal (correctly — changing it is the redundant second axis the plan rejects).
+
+The real exposure is in the **test** plan, not the code: `installCapabilityDirs` is mocked in every
+`add` test, so **no test in the suite would fail** if that default were later changed to, say,
+`layoutPaths('flat')` or derived from a different root. Invariant 5's pharn test asserts the *records*
+land at `pharn/…` (which does exercise the real `add.ts:396` chain — that part is sound and
+non-tautological), but the *copy* destination is whatever the mock chose to write. Suggested cheap
+hardening, entirely inside the whitelist: in the invariant-5 test, assert `installCapabilityDirs` was
+called with **exactly three arguments** — i.e. that `add` passes no `paths` and therefore depends on
+the default — so a future signature change to that default at least breaks a test that names the
+coupling. Alternatively, state the coupling as an **`advisory`** rider on this guarantee row rather
+than leaving it unqualified as FLOOR.
+
+### Axis: Eval coverage (P1) and the structural/semantic split (`eval-format.md`)
+
+Every invariant 1–8 has a named test and every assertion in the plan is **`structural[]`**-class
+(mock-call membership, exact string containment, `ProcessExit` code, byte-identity of a file, exact
+key-set equality). **Nothing is routed through a semantic judge** — correct for a CLI gate, and the
+right side of the `eval-format.md` split. Two refinements:
+
+```yaml
+- type: FINDING
+ rule_id: 'P1'
+ severity: minor
+ file: '.dev/features/add-layout-gate/PLAN.md:259'
+ problem: "The invariant-5 record assertion is described as a prefix check, which would still pass on a partially-empty store; only exact key-set equality makes the failure mode unambiguous."
+ evidence: "'the written store's keys are prefixed `pharn/` — the load-bearing assertion'"
+```
+
+The discriminating power is real (with a flat derivation, `capabilityRecordPaths` would `existsSync`
+a non-existent `pharn-review/<n>` and return `[]`, adding nothing) — so this test **does** catch the
+bug. But "prefixed `pharn/`" implemented as `.some(k => k.startsWith('pharn/'))` is weaker than it
+needs to be. Assert the exact `files` object (seeded entry + the new `pharn/…` keys), matching how the
+existing records tests already assert (`tests/add.test.ts:459-462` uses `toEqual`).
+
+```yaml
+- type: FINDING
+ rule_id: 'P1'
+ severity: minor
+ file: '.dev/features/add-layout-gate/PLAN.md:255'
+ problem: "The ordering test asserts the absence of a bare word, which is brittle against future rewording of either message."
+ evidence: "'assert the message names the two **versions** and **not** the word `layout`'"
+```
+
+Assert instead that the message contains `v1.0.0` / `v2.0.0` **and** does not contain the layout
+refusal's distinctive lead (`Install layout mismatch`). Same guarantee, stable under rewording of
+either string — the same reasoning `tests/add.test.ts:252-255` already documents for `lastError()`.
+
+```yaml
+- type: FINDING
+ rule_id: 'P1'
+ severity: minor
+ file: '.dev/features/add-layout-gate/PLAN.md:259'
+ problem: "Invariant 5 pins the pharn layout on the named path only; the picker's multi-pick accumulation at the pharn layout stays unpinned, and it is the path where per-pick record merging re-derives the layout on every iteration."
+ evidence: "'installs at the pharn layout and records pharn/-prefixed paths — marker clone dir + `layout: pharn` config + seeded records store'"
+```
+
+`mergeCapabilityRecords` re-runs `layoutPaths(detectLayout(repoDir))` per pick (`add.ts:396`, inside
+the loop's `resolveArchetypeAdd`). The existing accumulation test
+(`tests/add.test.ts:492`, *"the picker accumulates every pick"*) is flat-only. A pharn-layout variant
+is one fixture swap. **Judgment call for the human:** genuinely optional — the per-pick derivation is
+the same call the named path already pins, so this is defense-in-depth, not a coverage hole. Worth
+skipping if the diff is already at its intended size.
+
+### Axis: Trust propagation (P2)
+
+No findings. The trust audit (`PLAN.md:274-282`) correctly identifies that `detectLayout` reduces the
+entire untrusted clone tree to **one enum bit** through a `safeJoin`-contained `existsSync`, and that
+the message interpolates only closed-vocabulary `Layout` values — so the new refusal is genuinely not
+a new unvalidated-config-string-to-terminal sink. That claim was independently checked against
+`src/lib/layout.ts:51-53` and `:81-83` this run and holds.
+
+### Axis: One axis of change / no sibling imports (P3)
+
+No findings. `add.ts` gains one local helper serving the same reason-to-change the file already has
+(the `add` verb's gating). No command→command or step→step import is introduced; `layout.ts` is
+reached from `lib/`, which is the sanctioned direction.
+
+### Axis: Determinism (P5)
+
+No findings. The `??` chain makes the version-first ordering **evaluation-order structural** rather
+than statement-order incidental — a genuinely better construction than two sequential `if`s, and it
+is the reason invariant 3 can be called structural rather than inspected. Both operands are two-value
+enums with safe-default else-branches. Terminal fallback is a hard-fail with a named resolution, never
+a guess.
+
+### Axis: Honest scope / no speculation (P7)
+
+No findings on scope — this is one axis, triggered by a **live-reproduced** failure (the plan's repro
+was re-run this session, including the orphaning half), not a hypothetical. The whitelist widening to
+`docs/reference/pharn-config.md` was declared and approved at GATE 1 rather than taken silently.
+
+One observation, not a finding: the plan is candid that the residual population is **rare**
+(`PLAN.md:20-24`, the version gate already closes the common migration window) and does not inflate
+the fix's importance. That honesty is the P7 behavior, not a gap.
+
+---
+
+## Summary
+
+The plan is unusually well-grounded: every anchor was re-verified post-squash, the live repro was
+reproduced rather than trusted, both `layout.ts` semantics were quoted from source, and the harness
+facts the brief supplied were confirmed rather than assumed. The option-A rejection was re-tested and
+correctly upheld. The determinism and trust audits are sound and were spot-checked against source.
+
+Two concerns deserve the human's attention before `/pharn-dev-build`:
+
+1. **The message/doc contradiction** created by naming bare `pharn update` (a GATE-1 decision, not an
+ oversight) — reconcilable with a one-clause wording change inside the existing whitelist.
+2. **The headline guarantee is a two-file structural argument** whose second file is mocked in every
+ test, so no test defends the coupling. Either add the three-argument assertion that names the
+ dependency, or qualify the guarantee row as partly advisory.
+
+The remaining three findings are minor test-precision refinements (exact key-set equality, a
+reword-stable ordering assertion, and an optional picker-at-pharn-layout variant).
+
+Nothing here requires re-planning. All five findings are actionable inside the plan's existing
+may-edit whitelist.
+
+**ADVISORY VERDICT: 5 concerns raised (0 blocking-severity, 2 important, 3 minor) — for the human to
+weigh before `/pharn-dev-build`.** This grill-log is advisory end-to-end and **gates nothing**: it does
+not block, approve, or certify the plan, and no proceed/stop decision anywhere in the pipeline rests
+on it. The deterministic backstops remain `/pharn-dev-build`'s spec-hash gate and
+`.dev/floor/validate.mjs`.