@event4u/agent-config 14.9.0 → 14.11.0

package/docs/guidelines/agent-infra/roadmap-deferred-resolution-provenance.md

@@ -0,0 +1,54 @@
+---
+title: Roadmap deferred-item resolution — provenance
+description: Why the preservation test routes a preserving disposition to the council and a dropping one to the owner, what it deliberately does not fix, and the two council decisions behind it.
+type: guideline
+---
+
+# Roadmap deferred-item resolution — provenance
+
+Migrated from [`roadmap-progress-sync`](../../../src/rules/roadmap-progress-sync.md)
+§ *Who resolves it — the preservation test* under the P4 pattern
+(`road-to-standing-payload-diet` step 1.3). The rule keeps the Iron Law, the
+route table, the fail-closed clause and the recorded-or-it-did-not-happen
+clause — everything an agent must act on. What moved here is the provenance and
+the argument: read once, not on every session.
+
+It lives in its own file rather than in
+[`roadmap-progress-mechanics`](roadmap-progress-mechanics.md), which is the
+topical home, for a mechanical reason worth stating so the next migration does
+not repeat the attempt: that file sits ~134 characters under the 16,000-char
+`check_depth_budget` ceiling, so appending this block — or even a stub pointing
+at it — turns a green ratchet red. The ceiling is a growth ratchet rather than a
+measured quality threshold, and the fix it asks for is a smaller destination,
+not a raised baseline.
+
+## The residual hole, stated not papered over
+
+Both authoring seats named it in their own strongest counter: a carried
+follow-up can still become an indefinite deferral, so the preservation test
+bounds *who decides*, not *whether the work happens*. Only fix-now discharges
+it. A carried item untouched at the next task boundary is raised again per
+[`active-remediation`](../../../src/rules/active-remediation.md).
+
+## Why the routing changed
+
+Adopted 2026-08-19, unanimous 2/2 council (blind peer review). The prior text —
+*"Wait for the user"* — handed back a fully analysed choice carrying four costed
+options, which is the low-value interruption
+[`no-cheap-questions`](../../../src/rules/no-cheap-questions.md) forbids. The
+gate exists to protect the item, not the maintainer's attention; routing a
+preserving disposition to the council keeps the protection and drops the
+interruption.
+
+## `deferred_policy` provenance
+
+The declared-contract branch that removes the options round without moving the
+route is `decision 2026-08-20`, AI council 2/2. It is reversible by
+construction: `wait` is the default, so removing the field restores always-wait.
+A declared field never moves a row from owner to council — it changes only
+*when* the round happens.
+
+## See also
+
+- [`roadmap-progress-sync`](../../../src/rules/roadmap-progress-sync.md) — the live obligation, Iron Law 3 and the route table.
+- [`roadmap-progress-mechanics`](roadmap-progress-mechanics.md) — glyph semantics, regen cadence, the deferred-resolution menu.

package/docs/guidelines/design-antipatterns.md

@@ -107,8 +107,8 @@ Within-project invariants + repetition caps. Override = declare the value in
 | T4 | Eyebrow / ALL-CAPS label above every section heading | Overuse collapses the emphasis; maximum is 1 eyebrow per 3 sections (countable: grep tracking classes) | Used for genuine section-type differentiation with meaningful vocabulary (not just "FEATURES", "PRICING") |
 | T5 | Repeated section kickers ("Our mission", "What we offer", "Why choose us") | Filler vocabulary; every AI-generated page has the same three section titles | Every kicker is substantive and uses brand-specific vocabulary, not generic marketing speak |
 | T6 | Crushed letter-spacing on display text (`letter-spacing` < −0.04em) | Below −0.04em glyphs collide optically; reads as "designer-ish effect" with no grounding | Intentional tight display treatment with a documented minimum floor; verify at the actual render size |
-| T7 | Overused fonts without a brand reason: Inter, Roboto, DM Sans, Geist, Space Grotesk, Instrument Serif | These are the default AI-coding-tool font picks; every generated UI uses one of them | Brand has explicitly adopted one of these AND there is a documented reason (e.g., Inter for its variable metrics in a data-dense dashboard) |
-| T8 | Single typeface for everything | Missed typographic contrast opportunity; all-Inter reads as "I did not think about fonts" | Intentional mono-typeface aesthetic (e.g., terminal-inspired); must be stated in the brief |
+| T7 | Overused fonts without a stated reason: Inter, Roboto, DM Sans, Geist, Space Grotesk, Instrument Serif | These are the default AI-coding-tool font picks; every generated UI uses one of them | **Register-scoped.** In the **brand** register: the brand has explicitly adopted one of these AND there is a documented reason. In the **product** register: a single reliable family is the sanctioned strategy ([`design-modes`](design-modes.md) § The two registers), so one of these is legitimate on a **stated** product-register choice — the register itself is the reason, and it must be stated (DESIGN.md, the surface brief, or `design-slop-disable`). Neither register admits an *undeclared* pick. |
+| T8 | Single typeface for everything | Missed typographic contrast opportunity; in the **brand** register an unexamined single family reads as "I did not think about fonts" | **Register-scoped like T7.** Intentional mono-typeface aesthetic (e.g., terminal-inspired), stated in the brief — *or* the **product** register, where one reliable family is the sanctioned strategy ([`design-modes`](design-modes.md) § The two registers) and contrast is carried by weight and scale rather than by a second family. |
 | T9 | All-caps body paragraphs or field labels | Reduces legibility below WCAG AA for sustained reading; reads as flair over function | Short UI labels (e.g., button text in a brutalist layout); never for body paragraphs |
 | T10 | Wide letter-spacing on body text (`letter-spacing` > 0.05em) | Reduces readability for sustained reading; reserved for display use | Display text (headlines, pull quotes) where intentional tracking is a brand element |
 
@@ -162,6 +162,7 @@ Within-project invariants + repetition caps. Override = declare the value in
 | CP3 | Aphoristic manufactured contrast ("We don't do X. We do Y." / "Not just A, but B.") | A generated sentence rhythm that sounds like brand writing but carries no specificity | Aphoristic copy is legitimate when the contrast reveals a genuine product distinction; test by asking whether the Y side says something concrete |
 | CP4 | "Theater" framing — copy that announces what the product does without saying how or why | "The platform for modern teams." communicates nothing; it is content-shaped noise | Every tagline must pass the "so what" test: can a skeptic follow it with "but how?" and get a concrete answer? |
 | CP5 | Emoji-decoration in UI markup — 🚀/✅/🎉 prepending headings, buttons, list items, or CTAs (`🚀 Get Started`) | Performative-enthusiasm coating; the default-startup-template tell. No emoji is better than decorative emoji | Brand/`DESIGN.md` declares a systematic emoji strategy, or the emoji is functional (status indicator, category marker tied to real meaning) |
+| CP6 | Stock render subject named instead of the product's own subject matter — "floating abstract shapes", "gradient mesh", "glowing orb", "particle field", "futuristic HUD" | These name the default thing a render becomes when nobody decided what it is about; same delete-test as CP2, applied to art direction — swap the phrase for what the product actually shows and the brief says more | The subject IS abstract by decision (a generative-art surface, a data-driven field whose data is named), and the brief says which decision and why |
 
 ---
 
@@ -261,6 +262,7 @@ are listed in § Quality floors.
 | CP3 | judgment-only | copy phrase-list; that mechanism is council-rejected |
 | CP4 | judgment-only | copy phrase-list; that mechanism is council-rejected |
 | CP5 | backed | |
+| CP6 | backed | copy-engine phrase list, same mechanism as CP2; a CSS engine cannot see subject matter |
 
 ---
 

package/docs/guidelines/design-asset-discipline.md

@@ -0,0 +1,38 @@
+# Design Assets & Imagery — ownership, delivery, honesty
+
+> What a visual artifact may ship as an asset, who delivers it, and what counts as fabricated evidence
+
+_Split out of [`design-fidelity-mechanics`](design-fidelity-mechanics.md) § Asset & imagery discipline, which carries the obligation surface and routes here. The split is the per-file depth ceiling doing its job, exactly as it was for [`design-handover-extraction`](design-handover-extraction.md): the mechanics file crossed 16k when the artefact-maturity axis was migrated into it, and compressing this material to fit would have cost the ownership sentence ADR-205 rests on and the fixture ids that make each bullet falsifiable._
+
+Visual artifacts carry **real assets or honest placeholders — never fabricated
+brand evidence**. The design-surface instance of the no-invented-facts floor.
+
+- **Copy owned assets through the project's accepted path.** Reference or copy
+  project-owned assets (logos, icons, fonts, images) via the target project's
+  asset directory/pipeline — never hotlink a design-system's internal URL, never
+  bulk-copy a huge source folder. (fixtures: `daf-missing-asset`, `daf-external-asset-url`.)
+- **Third-party asset delivery is self-hosted by default — this section owns that
+  decision.** An asset whose delivery path crosses a third party (a webfont from
+  a font CDN, an icon set from a CDN, a hosted stylesheet) transmits the
+  **visitor's IP address** to that third party on every page view. Deliver it
+  through the target project's own route instead — the framework's font/asset
+  primitive, a bundled package, or a locally-served file. A third-party hotlink
+  is emitted **only** on an explicit consumer opt-in, and the opt-in is stated
+  with what it transmits — never chosen silently because it is the shorter line.
+  A discovery URL is not a delivery URL: keeping a font's browse/share link as
+  *where to find it* is fine. Ownership: this bullet is the single owner of the
+  third-party delivery decision ([`ADR-205`](../decisions/ADR-205-webfont-delivery-ownership.md));
+  emitters (`typography-system`, UI-apply directives, brand-asset paths) are
+  consumers and point here rather than restating it. (fixture:
+  `daf-webfont-delivery`.)
+- **Real imagery where inspection matters.** On visual pages/decks, use actual
+  product / place / object / state imagery where the image IS the proof (a
+  product screenshot, a real dashboard state). Decorative atmosphere is not proof
+  — never pass a stock-like or invented image off as the real product. An
+  invented product screenshot is fabricated evidence. (fixture: `daf-invented-screenshot`.)
+- **Icons follow the iconography floor** — no emoji-as-icon in serious UI, no
+  hand-rolled icon when a set exists; see the `iconography` skill § Iconography floor.
+- **Ask before adding material — no unrequested filler.** Never generate copy,
+  placeholder sections, or decorative blocks the user did not ask for to "complete"
+  a design. Brief silent on a region → surface the gap (`ask-when-uncertain`)
+  or leave an honest placeholder; never invent filler to fill space.

package/docs/guidelines/design-fidelity-mechanics.md

@@ -148,35 +148,25 @@ always owed.
 Visual artifacts carry **real assets or honest placeholders — never fabricated
 brand evidence**. The design-surface instance of the no-invented-facts floor.
 
-- **Copy owned assets through the project's accepted path.** Reference or copy
-  project-owned assets (logos, icons, fonts, images) via the target project's
-  asset directory/pipeline — never hotlink a design-system's internal URL, never
-  bulk-copy a huge source folder. (fixtures: `daf-missing-asset`, `daf-external-asset-url`.)
-- **Third-party asset delivery is self-hosted by default — this section owns that
-  decision.** An asset whose delivery path crosses a third party (a webfont from
-  a font CDN, an icon set from a CDN, a hosted stylesheet) transmits the
-  **visitor's IP address** to that third party on every page view. Deliver it
-  through the target project's own route instead — the framework's font/asset
-  primitive, a bundled package, or a locally-served file. A third-party hotlink
-  is emitted **only** on an explicit consumer opt-in, and the opt-in is stated
-  with what it transmits — never chosen silently because it is the shorter line.
-  A discovery URL is not a delivery URL: keeping a font's browse/share link as
-  *where to find it* is fine. Ownership: this bullet is the single owner of the
-  third-party delivery decision ([`ADR-205`](../decisions/ADR-205-webfont-delivery-ownership.md));
-  emitters (`typography-system`, UI-apply directives, brand-asset paths) are
-  consumers and point here rather than restating it. (fixture:
-  `daf-webfont-delivery`.)
-- **Real imagery where inspection matters.** On visual pages/decks, use actual
-  product / place / object / state imagery where the image IS the proof (a
-  product screenshot, a real dashboard state). Decorative atmosphere is not proof
-  — never pass a stock-like or invented image off as the real product. An
-  invented product screenshot is fabricated evidence. (fixture: `daf-invented-screenshot`.)
-- **Icons follow the iconography floor** — no emoji-as-icon in serious UI, no
-  hand-rolled icon when a set exists; see the `iconography` skill § Iconography floor.
-- **Ask before adding material — no unrequested filler.** Never generate copy,
-  placeholder sections, or decorative blocks the user did not ask for to "complete"
-  a design. Brief silent on a region → surface the gap (`ask-when-uncertain`)
-  or leave an honest placeholder; never invent filler to fill space.
+Owned-asset paths, the third-party delivery decision this repository pins to
+self-hosting ([`ADR-205`](../decisions/ADR-205-webfont-delivery-ownership.md)),
+the real-imagery-as-proof floor, the iconography floor and the
+no-unrequested-filler clause — each with its `daf-*` fixture:
+[`design-asset-discipline`](design-asset-discipline.md).
+
+## Artefact maturity — the second axis
+
+The Iron Law and both discriminator clauses stay in
+[`design-fidelity`](../../src/rules/design-fidelity.md) § Two axes; this is the table.
+
+| The artefact declares | The spec is | The spec is NOT |
+|---|---|---|
+| low fidelity — greyscale, box-and-line, placeholder copy | layout · element set · hierarchy · states shown | greys · placeholder text · borders · exact spacing |
+| finished — colour, real copy, real assets | everything visible (the 1:1 floor, unchanged) | — |
+
+Grounded in [`wireframe`](../../src/skills/wireframe/SKILL.md) § Gotchas. The near-miss
+class is pinned in `ROUTING_MATRIX`, its rationale beside the assertions in
+`design_fidelity_routing.test.ts`.
 
 ## Provided-artifact precedence
 
@@ -240,6 +230,32 @@ unmarked finding is treated as actionable, so the default failure direction is
 
 Regression witness: `daf-slop-vs-provided`.
 
+## Value-level provenance — the finer grain beside the flag
+
+The block above is finding-level and stays the default: `artifact_covered` is a
+boolean on a **finding**, and every consumer of it — `partition_artifact_covered`
+and the ceiling check it feeds — is unchanged by this section.
+
+What a per-finding boolean cannot answer is *"where did this `16px` come from"*.
+The flag says a finding is answered by the artifact; it does not say which value
+carried the expectation, so two rows that disagree about the same element look
+identical to a reviewer.
+
+`src/scripts/schemas/fidelity-measurement-sheet.schema.json` adds that grain and
+nothing else: each measurement row carries `expectation_source` — a `kind`
+ordered by authority (`provided_artifact` › `design_token` › `brand_token` ›
+`house_heuristic` › `agent_inference`) plus a `ref` naming the token, `file:line`
+or artefact anchor. `agent_inference` is the row a reviewer filters for.
+
+Two boundaries, because this is an addition and not a replacement:
+
+- **The coarse flag stays the default channel.** A row's optional
+  `expectation_source.artifact_covered` mirrors the flag for one value; it never
+  substitutes for setting the flag on the finding, and no gate reads it.
+- **The ordering above is a mirror, not a second source of truth.** Precedence
+  is decided in the block above; a `kind` that disagreed with it would be a
+  defect in the schema, not a competing chain.
+
 ## Failure modes
 
 - Swapping the prototype's font / typeface because another "reads better".

package/docs/guidelines/design-handover-extraction.md

@@ -74,11 +74,41 @@ ladder requires you to **name**, not to pass off as a source-based build.
 ## Coverage — stated honestly
 
 No fixture scores this class yet. `daf-source-over-screenshot` scores the rung
-choice on an *attached* artifact, not a URL handover, and it is itself recorded
-as SKIPPED on 2026-08-13 for want of a page-reaching capture primitive. Closing
-the gap needs a fixture whose host actually has one; claiming a regression
-witness before then would be the fabrication this package's evidence discipline
-exists to prevent.
+choice on an *attached* artifact, not a URL handover.
+
+**Its blocking reason changed on 2026-08-23 and the new one is narrower.** It was
+SKIPPED since 2026-08-13 "for want of a page-reaching capture primitive". That
+primitive now exists — `agent-config ui:render`, a Class-A headless capture at
+desktop / 375 px / 320 px, executed against a real fixture. So the fixture is no
+longer blocked on a missing capability; it is **unscored**, pending a live eval
+run that puts an agent through an artifact port and judges the rung it chose.
+
+The discipline is unchanged and still binds: claiming a regression witness before
+that run would be the fabrication this package's evidence discipline exists to
+prevent. What moved is which sentence is true — "we cannot measure this" became
+"we have not measured this yet", and those are different claims.
+
+### The skip register — every fixture gated on the same primitive
+
+`daf-source-over-screenshot` is no longer the only one, so the reason string is
+recorded once here rather than restated per fixture. Every row below is
+**SKIPPED** with `b-page-capture-primitive` as its reason, and none is silently
+absent:
+
+| Fixture | Registered | Reason |
+|---|---|---|
+| `daf-source-over-screenshot` | 2026-08-13 | `b-page-capture-primitive` |
+| `daf-render-absent-scoped` | 2026-08-23 | `b-page-capture-primitive` — its render-dependent assertions only; the static-scope assertions run and pass |
+| `daf-render-absent-control` | 2026-08-23 | `b-page-capture-primitive` — synthesises `render_ok: true` as state rather than rendering, and says so |
+
+**Probed, not assumed** (2026-08-23). The `playwright` library resolves in this
+tree, which reads as a capture primitive until you run it: launching chromium
+fails with *"Executable doesn't exist at
+…/chromium_headless_shell-1234/chrome-headless-shell"*. The library is present
+and **no browser binary is installed**, so the primitive is
+`not-available: headless-browser-binary`. Recorded as execution evidence because
+"playwright is in node_modules" is exactly the inference that would have made a
+fabricated witness look justified.
 
 ## See also
 

package/docs/guidelines/design-modes.md

@@ -14,7 +14,7 @@ wrong is the root cause of most AI-generated design failures:
 | **Primary failure** | Flatness / genericness — looks like every other AI startup | Strangeness without purpose — "clever" choices that obscure the tool |
 | **The user's question** | "How was this made?" (genuine curiosity) | "Where do I click?" (the tool disappears into the task) |
 | **Key skill cluster** | `brand-identity`, `iconography`, `fe-design § Aesthetic direction`, `design-intelligence` | `accessibility-auditor`, `ui-component-architect`, `fe-design § Table/Form Design` |
-| **Typography strategy** | Distinctive pairing — two contrasting families, deliberate tracking | One reliable family — Inter or equivalent; predictable hierarchy |
+| **Typography strategy** | Distinctive pairing — two contrasting families, deliberate tracking | One reliable family — predictable hierarchy. A default AI font pick (Inter, Roboto, DM Sans, Geist, Space Grotesk, Instrument Serif) is a legitimate product-register choice, and [`design-antipatterns` T7](design-antipatterns.md) scopes itself accordingly — but the register is the reason, so state it: an undeclared Inter is still an undeclared font choice. |
 | **Color strategy** | Brand identity — often unexpected; the palette IS the differentiator | Semantic function — primary/danger/success/neutral; predictable meaning |
 | **Motion strategy** | Expressive — motion reinforces the brand's personality | Utilitarian — motion confirms state changes; nothing decorative |
 | **Spacing strategy** | Breathing room; generous whitespace as a brand signal | Dense/efficient; optimize for information density |
@@ -41,6 +41,46 @@ a product-mode dashboard). The register applies per-surface, not per-product.
 When unclear: ask — *"Is the user here to be impressed, or to accomplish a
 task?"*
 
+## The second axis — surface job
+
+The register answers *how expressive may this be*. It does not answer *what is
+this surface for*, and conflating the two is why a persuade surface inside a
+product repo gets dense, utilitarian defaults. So there are two axes, and they
+are independent.
+
+| Surface job | The user's situation | Density | Hierarchy | Expressiveness |
+|---|---|---|---|---|
+| `persuade` | arrived, deciding, will leave in seconds | generous | one dominant claim per viewport | high — this is the job |
+| `operate` | returning, task in mind, wants it done | dense | scannable, predictable, repeated | low — strangeness costs time |
+| `read` | sustained attention on prose or data | measured | typographic, not chrome-led | restrained |
+| `experience` | exploring, no task, willing to be surprised | spacious | narrative, sequential | high, and sequenced |
+
+```
+SURFACE JOB IS PER-SURFACE AND LIVES IN THE SURFACE BRIEF.
+IT IS NEVER READ OFF PRODUCT.md, AND A RUN NEVER WRITES IT THERE.
+```
+
+**Why not in PRODUCT.md.** PRODUCT.md describes the product, and a product has
+many surfaces with different jobs — an investor one-pager and an ops console
+belong to the same product and share no defaults. A run that resolves the job
+from PRODUCT.md flattens the persuade surface into the product register, which
+is the `surface-mode-not-product-mode` near-miss in
+`tests/eval/frontend-corpus/near-miss/`.
+
+**Register stays.** The two axes compose: a `persuade` surface in the `brand`
+register and a `persuade` surface in the `product` register are both persuade
+surfaces, and the register decides how far the expressiveness may go.
+
+**Quality floors do not vary by either axis.** Density, hierarchy and
+expressiveness defaults move; contrast, minimum font size, line length,
+reduced-motion, heading order and focus visibility do not. A floor that moved
+with the surface job would be a preference wearing a floor's name.
+
+The machine-readable form is `surface_mode` in
+[`ui-authority`](../contracts/ui-authority.md), which is also the one place the
+precedence between an explicit instruction, the brief and these defaults is
+written down.
+
 ## Brand-mode failure modes
 
 - **Genericness:** Choosing the safe AI-slop palette (cream + brass, purple/violet gradient, three equal cards). The product is invisible in its category. Cross-check with `docs/guidelines/design-antipatterns.md` § Color and Visual.

package/docs/guidelines/monorepo-antipatterns.md

@@ -0,0 +1,141 @@
+# Monorepo anti-patterns — the diff-detectable set
+
+Task-graph mistakes a reviewer can catch by **reading a diff**, with no build
+run and no repository checked out. That is the whole selection criterion: a
+review judge sees a patch, not a running pipeline, so a rule it cannot evaluate
+from the patch is not a rule it can enforce.
+
+> **Own analysis, corroboration outstanding.** The six rows below describe
+> publicly documented behaviour of Turborepo and Nx and are stated from that
+> behaviour, not adopted from a third-party artefact — so no
+> `provenance/borrows.jsonl` entry backs them, and none should be read into
+> them. The roadmap that commissioned this file recorded specific source line
+> numbers in an external MIT-licensed reference; that reference is **not
+> reachable from this checkout** (it was never cloned here, and the consumed
+> inbox copy carrying the real identifiers is gitignored), so those line numbers
+> could not be re-read and are deliberately **not** reproduced as citations. A
+> citation nobody in this tree can follow is worse than an honest own-analysis
+> label. See § Not harvested for what that leaves open.
+
+## The six rows
+
+### 1. A root script that bypasses the task runner
+
+```jsonc
+// root package.json — WRONG
+{ "scripts": { "build": "tsc -b packages/ui && vite build apps/web" } }
+```
+
+The runner exists to know the graph, cache the results, and parallelise. A root
+script that invokes the underlying tools directly gets none of that, and — worse
+— becomes a second, divergent definition of what "build" means. Route through
+the runner: `"build": "turbo run build"`.
+
+**In a diff:** a root `scripts` entry naming a compiler, bundler, or test runner
+directly instead of `turbo run` / `nx run-many`.
+
+### 2. `prebuild` that builds a sibling
+
+```jsonc
+// packages/ui/package.json — WRONG
+{ "scripts": { "prebuild": "cd ../tokens && npm run build" } }
+```
+
+npm lifecycle hooks are invisible to the task runner. The dependency is real but
+undeclared, so the runner may build the two in the wrong order, in parallel, or
+skip the sibling entirely on a cache hit. Express it as a dependency
+(`dependsOn: ["^build"]` plus a real `workspace:` dependency) so the graph
+carries it.
+
+**In a diff:** a `pre*` / `post*` script containing `cd ..`, a sibling path, or
+another workspace's name.
+
+### 3. `&&`-chained runner tasks
+
+```jsonc
+{ "scripts": { "ci": "turbo run lint && turbo run test && turbo run build" } }
+```
+
+Three sequential invocations, each with its own graph walk, forcing full
+serialisation and discarding the parallelism the runner would have found. It
+also makes the cache less effective, because each invocation is scoped to one
+task. Pass the tasks together: `turbo run lint test build`.
+
+**In a diff:** two or more `turbo run` / `nx run-many` invocations joined by
+`&&` in one script.
+
+### 4. Shared code inside `apps/`
+
+```
+apps/web/src/shared/format-currency.ts   ← imported by apps/admin
+```
+
+`apps/*` are leaves: deployable things nothing else depends on. The moment a
+second app imports from the first, the two are coupled with no declared edge,
+the affected-set calculation is wrong, and neither app can be built or released
+alone. Shared code belongs in a `packages/*` workspace with a real dependency
+declared ([`workspace-link`](../../src/skills/workspace-link/SKILL.md)).
+
+**In a diff:** an import whose specifier reaches into `apps/<other>/`, or a new
+`shared/` `common/` `utils/` directory added under `apps/*`.
+
+### 5. `../` traversal in a task's `inputs`
+
+```jsonc
+// turbo.json — WRONG
+{ "tasks": { "build": { "inputs": ["src/**", "../tokens/src/**"] } } }
+```
+
+`inputs` are scoped to the workspace on purpose: they define that task's cache
+key. Reaching outside it makes the key depend on files the runner does not
+consider part of this task, which produces both false cache hits (the sibling
+changed in a way the key did not capture) and false misses. The sibling's output
+should be an input *because it is a declared dependency*, not because a glob
+walked up the tree.
+
+**In a diff:** a `../` segment inside `inputs`, `outputs`, or a task-scoped glob
+in `turbo.json`.
+
+### 6. A file-producing task with no `outputs`
+
+```jsonc
+{ "tasks": { "build": { "dependsOn": ["^build"] } } }   // writes dist/, declares nothing
+```
+
+With no `outputs`, the runner caches the task's *logs* and not its artefacts. A
+cache hit then restores nothing, so the next task in the chain runs against a
+missing or stale `dist/` — and the failure is intermittent, because it only
+appears on a hit. Declare what the task writes: `"outputs": ["dist/**"]`.
+
+**In a diff:** a task whose command runs a compiler or bundler while its config
+block carries no `outputs` key.
+
+## Not harvested
+
+The external reference this file was commissioned from carries a substantially
+longer anti-pattern list. The rows above are the ones whose violation is visible
+in a patch; the classes below were deliberately left out, each for a reason that
+is a property of the *check*, not of the advice:
+
+| Class not harvested | Why it cannot be a diff rule |
+|---|---|
+| Cache hit-rate and timing regressions | Needs two runs to compare; a diff has no runtime. |
+| Task-graph cycles | Requires resolving the whole graph, not reading one file. |
+| Over-broad `inputs` causing cache misses | "Too broad" is a judgement against observed hit rates. |
+| Remote-cache and CI configuration mistakes | Lives in CI/runner settings, not in the reviewed diff. |
+| Dependency-order races that only appear under `--parallel` | Needs a running build to observe. |
+| Environment-variable declarations missing from the cache key | Detectable only once a build produces a wrong artefact. |
+
+**Honest limit on this table:** it enumerates *classes* reasoned about from what
+such a list contains, not a row-by-row disposition of the source — which, per
+the note above, could not be opened here. So it does not establish that every
+source row is accounted for. Closing that needs the reference reachable in a
+checkout; until then this section states what was decided and on what basis,
+rather than implying a completeness it does not have.
+
+## See also
+
+- [`monorepo-workspace`](../../src/skills/monorepo-workspace/SKILL.md) — read the graph and the task list before judging either.
+- [`workspace-link`](../../src/skills/workspace-link/SKILL.md) — the `workspace:` declaration rows 2 and 4 both come back to.
+- [`blast-radius-analyzer`](../../src/skills/blast-radius-analyzer/SKILL.md) — § Monorepo, for the affected set of an edit.
+- [`design-antipatterns.md`](design-antipatterns.md) — sibling diff-detectable catalog for a different surface.