@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/skills/design-review/SKILL.md

@@ -16,7 +16,7 @@ packs:
 ## When to use
 
 > **Render-verification gate.** A UI verdict is gated on the
-> [design-artifact verification checklist](../../../docs/contracts/design-artifact-verification.md#verification-checklist):
+> [design-artifact verification checklist](../../docs/contracts/design-artifact-verification.md#verification-checklist):
 > where render capability exists, do not pass a design task without render
 > evidence (checklist steps 1–5); where it is absent, scope the verdict to what
 > was statically checked and say so — never "looks good" without evidence.
@@ -213,7 +213,7 @@ Load the reference file whose sections the review needs — never all of them by
 ## Read the authority object — the review is scoped by it
 
 Read the resolved `ui_authority`
-([contract](../../../docs/contracts/ui-authority.md)) before reviewing. Three
+([contract](../../docs/contracts/ui-authority.md)) before reviewing. Three
 fields change what a finding *means*:
 
 - **`surface_mode`** sets the density, hierarchy and expressiveness a reviewer
@@ -288,7 +288,7 @@ structured review phases, add an explicit **Anti-Slop Check** section:
    `lint_design_slop` is **flags, never a block** (default exit 0; CI opts into
    failure via `--fail-on`).
 2. **Judge what the detector cannot** — load
-   [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
+   [`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md)
    for the tells that need structural/aesthetic judgment (e.g. T3 icon-tile
    stack, L2 three-identical-card grid, V2 glassmorphism intent). List any that
    appear, cite by entry ID, and check the override condition.
@@ -304,7 +304,7 @@ structured review phases, add an explicit **Anti-Slop Check** section:
    own design. The flag is scoped to decisions the artifact actually covers;
    anything it leaves open (a state it never showed) is generative work and
    keeps the full scan. Precedence + scope:
-   [`design-fidelity-mechanics`](../../../docs/guidelines/design-fidelity-mechanics.md)
+   [`design-fidelity-mechanics`](../../guidelines/design-fidelity-mechanics.md)
    § Provided-artifact precedence. Regression witness: `daf-slop-vs-provided`.
 
 For the **objective quality floors** (WCAG contrast, font-size, line-length,

package/dist/agent-src/skills/design-system-capture/references/design-system-json.md

@@ -11,6 +11,9 @@
 ```json
 {
   "source": { "kind": "url|repo|dir", "ref": "https://example.com", "captured_at": "<ISO-8601>" },
+  "spec":    { "maturity": "low|finished",
+               "maturity_source": "user|declaration|inference|default",
+               "maturity_signal": "<the concrete thing that decided it>" },
   "colors": {
     "light": { "<role>": "<value>" },
     "dark":  { "<role>": "<value>" }
@@ -39,6 +42,22 @@
   `components[].observed`). It informs the human; it never becomes a token.
 - **`source` is mandatory** — `kind` + `ref` + `captured_at`. An artifact with
   no provenance is rejected (you cannot confirm what you cannot trace).
+- **`spec.maturity` is a field, not a judgement made twice.** `design-fidelity`
+  branches on whether the artifact's pixel detail carries decisions — a
+  wireframe's placeholder grays are non-decisions, and reproducing them 1:1
+  honors the wrong half of the artifact. That axis used to live only as a prose
+  table, so every consumer re-derived it by eye and two consumers could disagree
+  without either misreading the text. `src/scripts/_lib/artifact_maturity.ts`
+  resolves it, and the block carries the verdict **with its provenance**:
+  `maturity_source` says which rung decided (a user signal beats the artifact's
+  own declaration, which beats inference from its content, which beats the
+  default) and `maturity_signal` names the concrete thing — *"the filename names
+  a wireframe"*, *"every colour in the body is greyscale"* — never a restatement
+  of the verdict. **Absent resolves `finished`, deliberately:** the 1:1 floor is
+  the stricter reading, and guessing *low* would make an artifact's silence a
+  license to redesign it. The block is OPTIONAL in the file; an importer that
+  omits it gets the same default, which is why `source` is mandatory and this
+  is not.
 - **`bundled_local`** on a font family is a flag, not an instruction: the
   package never downloads or bundles fonts (out of scope) — it records that the
   source did.
@@ -46,7 +65,7 @@
   a long time that meant nothing read it at all: the block was written by
   capture and consumed by nobody, so easing and duration were re-derived from
   taste on every port. On the **Port a provided artifact** branch
-  ([`design-artifact-lifecycle`](../../../../../docs/contracts/design-artifact-lifecycle.md))
+  ([`design-artifact-lifecycle`](../../../docs/contracts/design-artifact-lifecycle.md))
   the audit reads `motion.durations` and `motion.easings` as the answer. The
   extraction-only marking above still holds: `motion._meta.detected_libs`
   informs the human and never becomes a token.

package/dist/agent-src/skills/design-tokens/SKILL.md

@@ -87,6 +87,21 @@ scan the changed files, append the findings to
 (`var(--token)` over hardcoded hex — the validation rule the council's
 four-operation split assigns to *rules/linters*, not the corpus).
 
+**Set `artifact_covered: true` on a finding whose value traces to a provided
+design artifact.** Without it the polish round edits AWAY from the artifact:
+`polish.ts::partition_artifact_covered` drops flagged findings and treats every
+unmarked one as actionable, and this path appended `token_violation` findings
+without the flag — so a hex the handover states was converted to a project token
+by a loop nobody asked. The flag is per finding, not per run: a hardcoded hex
+the artifact never mentioned stays actionable and is still fixed. Marking is not
+suppression — the finding stays in the report as informational, so a reader
+still sees that the spec carries a value the token system does not.
+(AI council 2026-09-09 on `blocker: findings-actionability-default`, option (b):
+one call site, no package-wide default changed. Reopens if a second
+artifact-derived finding path reaches the loop without provenance — recurrence
+would argue for carrying provenance in the finding TYPE rather than at a third
+call site.)
+
 ## Procedure
 
 1. **Inspect the existing styling surface** — detect the stack (Tailwind
@@ -153,8 +168,8 @@ four-operation split assigns to *rules/linters*, not the corpus).
 
 ## See also
 
-- [`design-canon.md`](../../../docs/guidelines/design-canon.md) § Colour references — a11y-contrast + culturally-specific palettes + named-system token models.
+- [`design-canon.md`](../../guidelines/design-canon.md) § Colour references — a11y-contrast + culturally-specific palettes + named-system token models.
 - [`design-intelligence`](../design-intelligence/SKILL.md) — grounded value selection.
 - [`tailwind-engineer`](../tailwind-engineer/SKILL.md) — utility-discipline consumer.
 - [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — shadcn token conventions.
-- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — when authoring the colour layer, avoid the C5 cream/sand default palette (OKLCH L 0.84–0.97, C < 0.06) and C1 purple/violet primaries unless the brand explicitly defines them; the `brand-consistency` rule validates emitted tokens against the active brand profile.
+- [`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md) — when authoring the colour layer, avoid the C5 cream/sand default palette (OKLCH L 0.84–0.97, C < 0.06) and C1 purple/violet primaries unless the brand explicitly defines them; the `brand-consistency` rule validates emitted tokens against the active brand profile.

package/dist/agent-src/skills/design-variations/SKILL.md

@@ -79,7 +79,7 @@ existing design → [`design-review`](../design-review/SKILL.md).
 8. **Quality gate.** Novel ≠ sloppy: run `lint_design_slop` over the emitted
    file (every variation individually passes; a DESIGN.md-declared direction
    suppresses its flags) and honor the outward-artifact hygiene floor (Q13 in
-   [`design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)) —
+   [`design-antipatterns.md`](../../guidelines/design-antipatterns.md)) —
    no workspace paths, skill/tool names, or generator traces in the markup.
    Final pass before delivery → [`design-review`](../design-review/SKILL.md).
 
@@ -127,4 +127,4 @@ existing design → [`design-review`](../design-review/SKILL.md).
 - [`design-tokens`](../design-tokens/SKILL.md) — token emission for variation values.
 - [`fe-design`](../fe-design/SKILL.md) — production heuristics the by-the-book variation follows.
 - [`design-review`](../design-review/SKILL.md) — final gate before delivery.
-- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — catalog + Q13 outward-artifact hygiene.
+- [`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md) — catalog + Q13 outward-artifact hygiene.

package/dist/agent-src/skills/developer-like-execution/SKILL.md

@@ -135,14 +135,14 @@ If important information is missing:
 - Compare with requirements, tickets, current behavior, tests, existing patterns
 - Identify likely cause and smallest correct change
 - **Consult memory — invariants and prior decisions.** Via
-  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md), call
+  [`memory-access`](../../guidelines/agent-infra/memory-access.md), call
   `retrieve(types=["domain-invariants"], keys=<touched paths>, limit=3)`.
   A matching `domain-invariant` is a hard constraint — violating it = regression,
   surface the conflict to the user before proceeding. For architectural rationale
   (*why* the current shape exists), check the ADR index
   [`docs/decisions/INDEX.md`](../../../docs/decisions/INDEX.md); plan around it, do
   not silently overturn it. Cite matching `id`s / ADR numbers in the plan.
-  See [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
+  See [`engineering-memory-data-format`](../../guidelines/agent-infra/engineering-memory-data-format.md)
   for the schema.
 
 ### 4. Define expected behavior first

package/dist/agent-src/skills/discovery-interview/SKILL.md

@@ -36,7 +36,7 @@ quantitative survey design or scale-bound research.
 - **Mental model 22 — Data-informed, not data-driven.** Interview
   data is signal at low N; treat it as evidence to reason with, not
   a vote count. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 22.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 22.
 - **Mental model 15 — Signal vs noise.** A vivid quote from one
   articulate user can swamp three muted but consistent signals;
   frequency-rank by distinct people, never by quote count. See
@@ -47,7 +47,7 @@ quantitative survey design or scale-bound research.
   `mental-models.md` § 28.
 - **Product context-spine slot.** Read **product** for the focal job
   + competitor names; do **not** re-derive these inside this skill.
-  See [`context-spine`](../../../docs/contracts/context-spine.md).
+  See [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/doc-coauthoring/SKILL.md

@@ -15,7 +15,7 @@ packs:
 
 > **Cross-surface handoff.** When this document consumes upstream work (research
 > → document, spreadsheet → report), read the handoff envelope from
-> [`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md#cross-surface-handoff-envelope):
+> [`surface-agent-contracts`](../../docs/contracts/surface-agent-contracts.md#cross-surface-handoff-envelope):
 > trust `verification_already_done`, honour source restrictions, and don't
 > re-fetch what the source already grounded.
 
@@ -49,7 +49,7 @@ Move from a fuzzy ask to a complete document the user owns, by:
 ## Document format & export floor
 
 The document surface's floor (per
-[`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md)):
+[`surface-agent-contracts`](../../docs/contracts/surface-agent-contracts.md)):
 
 - **Choose the format by intent.** Markdown vs `.docx` vs PDF follows what the
   user will DO with it — when a named format is requested, produce THAT format
@@ -63,7 +63,7 @@ The document surface's floor (per
   selectable. (fixture: `ssac-pdf-screenshot-rasterized`.)
 - **Verify the output opens/exports.** Confirm the generated file opens /
   round-trips
-  ([`design-artifact-verification`](../../../docs/contracts/design-artifact-verification.md));
+  ([`design-artifact-verification`](../../docs/contracts/design-artifact-verification.md));
   where the format's tooling is absent, ship the source + say what could not be
   verified rather than claiming a produced file.
 

package/dist/agent-src/skills/editorial-calendar/SKILL.md

@@ -36,7 +36,7 @@ scope — channel-agnostic skill), or sequence a one-off launch wave
   the editorial beats produce 80 % of the audience pull. The
   calendar is the discipline of doubling down on the 20 % and
   letting the 80 % be reactive, not core. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 3.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 3.
 - **Mental model 18 — Pull vs. push systems.** Evergreen content is
   a *pull* system (the audience finds it); campaigns are a *push*
   system (we time the arrival). The calendar separates the two so
@@ -48,7 +48,7 @@ scope — channel-agnostic skill), or sequence a one-off launch wave
   for where the audience is in the awareness arc, and
   **funnel-stage** for whether a beat is top-of-funnel reach or
   mid-funnel proof. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -37,7 +37,7 @@ Do NOT use when:
 
 Any request to **recreate, redesign, mock, prototype, or improve** a UI runs
 this gate BEFORE styling — the Inspect stage of the
-[design-artifact lifecycle](../../../docs/contracts/design-artifact-lifecycle.md).
+[design-artifact lifecycle](../../docs/contracts/design-artifact-lifecycle.md).
 Design starts from project truth, not generic aesthetic memory.
 
 - **Search first (owned UI).** Before proposing anything, search the project
@@ -202,6 +202,49 @@ For each item in `state.ui_audit.components`, score similarity to `state.input.d
 
 If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.
 
+#### 6b. Conformance gate — when a provided artifact is the spec
+
+Similarity above is scored against `state.input.data`. That answers *"is this
+component like the thing being asked for"* and it does **not** answer *"does
+this component satisfy the artifact"* — which is a different question with a
+different answer, because a candidate can be an excellent name-and-props match
+and still use the wrong type scale, the wrong control, or a colour the artifact
+never states. Until this step existed nothing anywhere asked the second
+question, while [`ui-audit-gate`](../../rules/ui-audit-gate.md) carried *"reuse
+beats duplication"* as unqualified prose. Reused on an artifact port, an
+unconforming candidate is a fidelity deviation dressed as good hygiene.
+
+So when a provided design artifact is the spec
+([`design-fidelity`](../../rules/design-fidelity.md)), each candidate carries a
+**conformance verdict** alongside its score, and reuse is conditional on it:
+
+```
+[{path, name, score, reason,
+  conformance: {verdict: "conforms|deviates|unknown",
+                dimensions: {structure, values, behaviour, responsive},
+                refused_by: "values"}}, ...]
+```
+
+- **`conforms`** → reuse it. This is the ordinary case and nothing changed.
+- **`deviates`** → do **not** reuse silently. Name the dimension that refused
+  it — *"`Card` deviates on `values`: type scale 14/20 against the artifact's
+  16/24"* — and surface reuse-with-adaptation versus build-new as a choice.
+  A bare "candidate rejected" is not a discharge; the caller cannot act on it.
+- **`unknown`** → the candidate was not scored against the artifact (no
+  extraction yet, or a subtree the audit could not read). Treat as `deviates`
+  for the purpose of not reusing silently, and say which of the two it is —
+  "did not conform" and "was not checked" are different facts.
+
+**And the decision moves after extraction, not before it.** A conformance
+verdict needs the artifact's own values, so a reuse decision taken before
+extraction is taken without the evidence that decides it. Where the run has an
+artifact, order is: extract → audit → score → conform → decide. The unqualified
+reuse-first ordering stands only where there is no artifact to conform to.
+
+**Scope:** this is a gate on REUSE, not a license to rewrite the incumbent. A
+candidate that deviates is left alone; the choice is whether *this* work builds
+on it.
+
 ### 7. Greenfield branch
 
 If **all** are true:

package/dist/agent-src/skills/existing-ui-audit/references/anti-slop-cross-reference.md

@@ -9,7 +9,7 @@
 When the audit inventory reveals an existing aesthetic direction (dominant color
 scheme, border-radius convention, motion patterns), cross-check the findings
 against
-[`docs/guidelines/design-antipatterns.md`](../../../../docs/guidelines/design-antipatterns.md).
+[`docs/guidelines/design-antipatterns.md`](../../../guidelines/design-antipatterns.md).
 If the existing UI already uses a listed anti-pattern, surface it as a design-debt
 finding (separate from the reuse inventory) — flag by entry ID and severity.
 
@@ -26,6 +26,6 @@ A corrective direction change against a supplied spec is not a design
 improvement, it is overriding a decision the user already made — the failure
 [`design-fidelity`](../../rules/design-fidelity.md) exists to prevent, arriving
 through the audit's side door. Precedence and its exact scope:
-[`design-fidelity-mechanics`](../../../../docs/guidelines/design-fidelity-mechanics.md)
+[`design-fidelity-mechanics`](../../../guidelines/design-fidelity-mechanics.md)
 § Provided-artifact precedence. Where the two sources disagree, surface the
 conflict rather than picking (fixture `daf-slop-vs-provided`).

package/dist/agent-src/skills/expansion-playbook/SKILL.md

@@ -36,7 +36,7 @@ unattended by a human play (route to `retention-loops`).
   vendor pushes (because the quarter needs the number) corrodes
   the relationship and inflates churn the next cycle. Pick the
   trigger that signals pull. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 18.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 18.
 - **Mental model 9 — Hypothesis-driven thinking.** Each expansion
   trigger is a hypothesis: *"if signal X is true, the buyer will
   accept expansion Y at price Z."* Triggers without falsification
@@ -52,7 +52,7 @@ unattended by a human play (route to `retention-loops`).
   segment cannot use yet inflates churn), and the
   **customer-segment** slot for switch-event patterns that signal
   organic scope expansion. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/experiment-loop/SKILL.md

@@ -13,7 +13,7 @@ packs:
 
 > A bounded **change → commit → evaluate → keep-or-revert** cycle against a
 > **scalar metric**, where the decision input is an
-> [evaluator-output](../../../docs/contracts/evaluator-output.md) verdict and the
+> [evaluator-output](../../docs/contracts/evaluator-output.md) verdict and the
 > loop's entire state lives in an append-only register on disk.
 
 This file **routes**. The protocol, the register format, and the pivot ladder are

package/dist/agent-src/skills/experiment-loop/references/protocol.md

@@ -16,7 +16,7 @@ Loaded on demand by [`experiment-loop`](../SKILL.md). One iteration, in order.
 4. **Commit.** The revert is then a git operation rather than a manual undo, and
    the branch carries one commit per iteration whether it survives or not.
 5. **Evaluate** — run the evaluator, read its
-   [evaluator-output](../../../../../docs/contracts/evaluator-output.md) verdict.
+   [evaluator-output](../../../docs/contracts/evaluator-output.md) verdict.
 6. **Decide**, and update the row:
 
    | Verdict | Decision |

package/dist/agent-src/skills/fe-design/SKILL.md

@@ -246,13 +246,13 @@ When this skill's content is folded into a design brief or review:
 ## Read the authority object — never re-infer it
 
 Read the resolved `ui_authority`
-([contract](../../../docs/contracts/ui-authority.md)) before the loop:
+([contract](../../docs/contracts/ui-authority.md)) before the loop:
 `surface_mode`, `register`, `change_intent`, `reference_maturity`,
 `constraints`. This skill is a **declared consumer** — a second decision table
 beside the object is a drift surface, so do not re-derive any field.
 
 `surface_mode` sets density, hierarchy and expressiveness only, per
-[`design-modes`](../../../docs/guidelines/design-modes.md) § The second axis.
+[`design-modes`](../../guidelines/design-modes.md) § The second axis.
 
 ```
 QUALITY FLOORS DO NOT VARY BY SURFACE MODE.
@@ -274,7 +274,7 @@ provenance belongs to `road-to-frontend-fidelity-calibration` Phases 0 and 2.
 ## Anti-slop discipline
 
 Before proposing a direction, scan the Visual (V1–V8) and Layout (L1–L10)
-sections of [`design-antipatterns`](../../../docs/guidelines/design-antipatterns.md),
+sections of [`design-antipatterns`](../../guidelines/design-antipatterns.md),
 plus Motion (M1–M8) for the interaction layer.
 On a match, choose differently or invoke the entry's own override condition in
 the brief — every entry has one. Two of them, T7 and T8, are additionally

package/dist/agent-src/skills/fe-design/references/design-patterns.md

@@ -38,7 +38,7 @@ React island vs. Vue SFC) is the apply-step's concern, not this skill's.
 - **One stateful component per concern** — don't build mega-components.
 - **Compose with reusable UI components** for shared shells, headers, fields.
 - **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
-- **Extract a props-only UI shell when used 3+ times** — DRY applies to UI too; stateful components carry a higher bar (~4 + real state) — per-class canon: [`abstraction-thresholds`](../../../../docs/guidelines/abstraction-thresholds.md).
+- **Extract a props-only UI shell when used 3+ times** — DRY applies to UI too; stateful components carry a higher bar (~4 + real state) — per-class canon: [`abstraction-thresholds`](../../../guidelines/abstraction-thresholds.md).
 - **Component workshop when the project is large enough** — for a real, growing shared-component library, isolate and document each reusable component in a component workshop so it stays discoverable and reused, not re-invented; skip it for a small surface of one-offs. Tool-specific setup is a carve-out (Storybook et al.) — see the implementation skill (e.g. [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop), never a generic mandate.
 
 ## Form Design

package/dist/agent-src/skills/fe-design/references/design-read-and-memory.md

@@ -22,7 +22,7 @@ suggest adding to PRODUCT.md: [pattern description]."*
 ## Register — brand vs product
 
 Before applying heuristics, determine the register (see
-[`docs/guidelines/design-modes.md`](../../../../docs/guidelines/design-modes.md)):
+[`docs/guidelines/design-modes.md`](../../../guidelines/design-modes.md)):
 brand mode (impression-first) vs product mode (task-first). Form-heavy, table-heavy,
 and dashboard surfaces are almost always product mode — favour the standard
 patterns in this skill (Form Design, Table Design) over expressive variance.
@@ -42,7 +42,7 @@ Reading this as: <page-kind> for <audience>, <vibe> language, leaning <design-sy
 
 **Anti-Default Discipline:** Before committing to any layout or component
 pattern, cross-check your first impulse against
-[`design-antipatterns.md`](../../../../docs/guidelines/design-antipatterns.md) —
+[`design-antipatterns.md`](../../../guidelines/design-antipatterns.md) —
 the L1/L2 "AI landing page" layout (centered hero + 3-column grid + CTA), the
 V1 side-stripe card, the T7 default-font pick, and V2 decorative glassmorphism.
 If a tell was the first impulse, choose a different approach or explicitly
@@ -56,7 +56,7 @@ burden does not apply to them: build them as given. The carve-out is scoped to
 decisions the artifact actually covers — anything it leaves open (a state it
 never shows, a surface it never had) is your first impulse again and gets the
 full scan. See
-[`design-fidelity-mechanics`](../../../../docs/guidelines/design-fidelity-mechanics.md)
+[`design-fidelity-mechanics`](../../../guidelines/design-fidelity-mechanics.md)
 § Provided-artifact precedence.
 
 ## Aesthetic direction

package/dist/agent-src/skills/fe-design/references/source-led-port.md

@@ -1,7 +1,7 @@
 # Source-led port — adopt the mechanics, do not re-derive them
 
 Pulled when `ui_authority.reference_maturity` is `runnable-artifact`. Contract:
-[`ui-authority`](../../../../../docs/contracts/ui-authority.md).
+[`ui-authority`](../../../docs/contracts/ui-authority.md).
 
 When `reference_maturity` is `runnable-artifact`, the artifact's own markup, CSS
 and JS is the data basis and adapting it is the DEFAULT. A from-scratch

package/dist/agent-src/skills/feature-planning/SKILL.md

@@ -28,7 +28,7 @@ Do NOT use when:
 
 ## Procedure: Plan a feature
 
-1. **Gather requirements** — What problem does this solve? Who benefits? What's the expected outcome? Run a **cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): where the source ticket carries text + an attachment/mockup, or leaves a clearly-needed behavior unstated (weekend/holiday shift, empty/error state, timezone), surface the conflict/gap as an *Open question* before drafting phases — an inferred behavior is a scope expansion to confirm, not to bake in. See [`cross-source-consistency-mechanics`](../../../docs/guidelines/agent-infra/cross-source-consistency-mechanics.md).
+1. **Gather requirements** — What problem does this solve? Who benefits? What's the expected outcome? Run a **cross-source discrepancy scan** (per [`cross-source-consistency`](../../rules/cross-source-consistency.md), gated by `consistency.cross_source`): where the source ticket carries text + an attachment/mockup, or leaves a clearly-needed behavior unstated (weekend/holiday shift, empty/error state, timezone), surface the conflict/gap as an *Open question* before drafting phases — an inferred behavior is a scope expansion to confirm, not to bake in. See [`cross-source-consistency-mechanics`](../../guidelines/agent-infra/cross-source-consistency-mechanics.md).
 2. **Analyze scope** — Which modules, routes, models, services are affected?
 3. **Write the plan** — Create a feature plan document (see template below).
 4. **Verify** — Confirm all affected areas are identified, no missing dependencies.

package/dist/agent-src/skills/flux/SKILL.md

@@ -126,7 +126,7 @@ When `DESIGN.md` declares `## Taste Dials`, honour them: Variance → layout-fam
 ## Anti-slop
 
 Flux primitives carry sane defaults, but composition still drifts into slop —
-pull [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
+pull [`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md)
 and check Layout (L1/L2 hero-metric + identical-card grids) and Color
 (C1 gradient defaults) before shipping. Tailwind-level bans:
 [`tailwind-engineer`](../tailwind-engineer/SKILL.md).

package/dist/agent-src/skills/forecast-accuracy/SKILL.md

@@ -38,7 +38,7 @@ via the `forecast-construction-shape` interface).
   is lagging; per-stage conversion and MEDDIC-slot completeness
   are leading. A forecast built on lagging signals can only confirm
   the result after it lands. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 16.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 16.
 - **Mental model 29 — Premortem.** Before locking the call, write
   the post-quarter retro as if commit missed by 20 %. The premortem
   surfaces which categorisations are riding on weak evidence; demote
@@ -54,7 +54,7 @@ via the `forecast-construction-shape` interface).
   **customer-segment** slot for segment-historical close rates —
   pricing-power and cycle-length differ by segment and the forecast
   must too. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/forecasting/SKILL.md

@@ -32,7 +32,7 @@ Do NOT use to qualify a single deal (route to `deal-qualification-meddic`), cons
 - **Mental model 9 — Hypothesis-driven thinking.** Each forecast is
   a falsifiable claim about a window. If the call cannot be falsified
   inside the window, the call is a narrative, not a forecast. See
-  [`mental-models.md`](../../../docs/contracts/mental-models.md) § 9.
+  [`mental-models.md`](../../docs/contracts/mental-models.md) § 9.
 - **Mental model 29 — Premortem.** Before locking the call, write the
   post-window retro as if commit missed by 20 %. The premortem
   surfaces which construction inputs were riding on weak evidence;
@@ -47,7 +47,7 @@ Do NOT use to qualify a single deal (route to `deal-qualification-meddic`), cons
   reconcile against (monthly close vs quarterly board pack vs annual
   plan vs multi-year plan); the **customer-segment** slot for
   segment-historical close rates. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/fundraising-narrative/SKILL.md

@@ -35,7 +35,7 @@ are siblings, not the same artefact).
   the load-bearing claim and the one most often borrowed. Build
   it from the segment-shift up — what changed in the world, the
   customer, the technology — not from a deck template. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 1.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 1.
 - **Mental model 9 — Hypothesis-driven development.** A pitch is
   a falsifiable hypothesis: *if X is true, our round closes.*
   Name the X. Investors who disagree with the hypothesis are not
@@ -55,7 +55,7 @@ are siblings, not the same artefact).
   for the proofs the traction story can actually back; read
   **customer-segment** for the TAM/SAM argument that survives a
   bottom-up scrutiny. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/funnel-analysis/SKILL.md

@@ -32,7 +32,7 @@ Do NOT use for ranking features, valuation, or OKR decomposition (see Related Sk
   lagging; activation is leading; signup is upstream of both. A
   funnel decision built on the lagging stage can only confirm the
   miss; the leading stage names the binding fix. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 16.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 16.
 - **Mental model 13 — Occam's razor.** When a stage drops, the
   simpler explanation usually wins: *"acquisition mix shifted"*
   beats *"users no longer understand the product."* Pick the simpler
@@ -47,7 +47,7 @@ Do NOT use for ranking features, valuation, or OKR decomposition (see Related Sk
   **customer-segment** slot for which segments' switch-events the
   funnel is built for, and the **funnel-stage** slot for the
   position of each stage relative to the buying journey. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/gtm-launch/SKILL.md

@@ -36,7 +36,7 @@ post-launch retention loops (route to `retention-loops`).
   expectations after public launch costs more than re-shipping the
   product. Alpha and beta are reversible; treat them as the
   decision-quality buffer. See
-  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 10.
+  [`docs/contracts/mental-models.md`](../../docs/contracts/mental-models.md) § 10.
 - **Mental model 29 — Premortem.** Before the wave plan locks, write
   the post-mortem of the launch as if it failed. The premortem
   surfaces the gates that need to hold; the wave plan is the inverse
@@ -50,7 +50,7 @@ post-launch retention loops (route to `retention-loops`).
   **customer-segment** slot for who hears the launch on which wave,
   and the **channel-stage** slot for where each wave's audience lives
   in the awareness → decision arc. See
-  [`context-spine`](../../../docs/contracts/context-spine.md).
+  [`context-spine`](../../docs/contracts/context-spine.md).
 
 ## Procedure
 

package/dist/agent-src/skills/hiring-loop-design/SKILL.md

@@ -28,7 +28,7 @@ Do NOT use this for non-engineering hiring as the primary surface (sales / GTM h
 
 ## Cognition cluster
 
-- **Mental model 1 — First principles.** Strip hiring to: *what signal does each stage produce that no other stage can produce?* Stages that duplicate signal waste candidate-time and interviewer-time. The strongest loops have one stage per signal, not five stages probing the same thing. See [`mental-models.md`](../../../docs/contracts/mental-models.md) § 1.
+- **Mental model 1 — First principles.** Strip hiring to: *what signal does each stage produce that no other stage can produce?* Stages that duplicate signal waste candidate-time and interviewer-time. The strongest loops have one stage per signal, not five stages probing the same thing. See [`mental-models.md`](../../docs/contracts/mental-models.md) § 1.
 - **Mental model 28 — Inversion.** *"What would make a great hire withdraw from this loop?"* — usually: 7+ stages, take-home > 6 hours, no role-context conversation, long calendar gaps, no senior-IC time, no offer-narrative. Inversion surfaces the canonical withdrawal causes; great candidates have options and use them.
 - **Mental model 21 — Second-order thinking.** A loose bar at L4 produces a chain: weaker L4 → harder L5 calibration → erodes ladder credibility → ICs leave. A single accept-the-no-vote ripples for 2+ years. The cost of a wrong hire dwarfs the cost of a missed hire; bar discipline is a multi-year compounding decision.
 - **Mental model — Base rates.** Most signals in interviews are noise; the most-confident signal-claim is usually the most-overfit to one observation. Calibrate against the base rate: *"out of 10 candidates who passed this stage with this signal, how many succeeded at 12 months?"* If unknown, the stage is unfalsifiable.

package/dist/agent-src/skills/html-deck/SKILL.md

@@ -29,7 +29,7 @@ letterbox to any viewport. A deck is fixed-canvas media (default 1920×1080,
 
 > **Cross-surface handoff.** A deck often consumes upstream analysis
 > (spreadsheet → deck, research → deck). Read the handoff envelope from
-> [`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md#cross-surface-handoff-envelope):
+> [`surface-agent-contracts`](../../docs/contracts/surface-agent-contracts.md#cross-surface-handoff-envelope):
 > trust `verification_already_done` (don't recompute the source's numbers),
 > carry the asset list, and keep source restrictions intact.
 
@@ -44,7 +44,7 @@ options of one screen → [`design-variations`](../design-variations/SKILL.md).
 ## Deck fidelity floor
 
 The deck surface's floor (per
-[`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md)):
+[`surface-agent-contracts`](../../docs/contracts/surface-agent-contracts.md)):
 
 - **Outline before slides.** Draft the slide outline (title + one-line intent
   per slide) before building any slide; when audience or tone is ambiguous, ask
@@ -58,7 +58,7 @@ The deck surface's floor (per
   brand evidence ([`design-fidelity`](../../rules/design-fidelity.md) § Asset &
   imagery discipline).
 - **Export verification.** Verify the deck exports/renders
-  ([`design-artifact-verification`](../../../docs/contracts/design-artifact-verification.md));
+  ([`design-artifact-verification`](../../docs/contracts/design-artifact-verification.md));
   on a host without export capability, say what could not be verified rather
   than claiming a clean export.
 
@@ -98,7 +98,7 @@ The deck surface's floor (per
    per-slide `<aside hidden>`, never printed.
 6. **Quality gate.** Run `lint_design_slop` over the file; honor the
    outward-artifact hygiene floor (Q13 in
-   [`design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md))
+   [`design-antipatterns.md`](../../guidelines/design-antipatterns.md))
    — no workspace paths, skill/tool names, or generator traces in markup or
    comments; final pass → [`design-review`](../design-review/SKILL.md).
    Verify scaling + navigation + persistence once in a browser before
@@ -150,4 +150,4 @@ The deck surface's floor (per
 - [`design-intelligence`](../design-intelligence/SKILL.md) — direction/palette/type grounding.
 - [`design-tokens`](../design-tokens/SKILL.md) / [`brand-to-tokens`](../brand-to-tokens/SKILL.md) — token precedence and emission.
 - [`design-review`](../design-review/SKILL.md) — final review gate.
-- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — catalog, CP5, Q13.
+- [`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md) — catalog, CP5, Q13.

package/dist/agent-src/skills/humanizer/SKILL.md

@@ -26,7 +26,7 @@ install:
 - A drafted deliverable (post, article, README section on request, release
   note) reads AI-generated and should read human-written.
 - The write engine reaches step 4b (humanize audit) —
-  [`write-engine § 4b`](../../../docs/contracts/write-engine.md).
+  [`write-engine § 4b`](../../docs/contracts/write-engine.md).
 - The user pastes text and asks to remove AI-isms, de-slop, or "make it
   sound less like ChatGPT".
 

package/dist/agent-src/skills/humanizer/data/patterns.md

@@ -161,7 +161,7 @@ Not reliable indicators on their own — leave these alone:
 - **Mixed registers.** Often a person, not a bot.
 - **Unsourced claims.** Most human web writing is unsourced.
 - **Quoted text, titles, proper names, and discussed-not-used phrases.**
-  Never rewrite secondhand text ([`content-quoting-floor`](../../../src/rules/content-quoting-floor.md)).
+  Never rewrite secondhand text ([`content-quoting-floor`](../../../rules/content-quoting-floor.md)).
 
 Decide on **clusters**: two or more distinct pattern groups co-occurring.
 Below that, say "no reliable tells found" and stop.

package/dist/agent-src/skills/iconography/SKILL.md

@@ -89,7 +89,7 @@ rung 3 and is exactly the scaffold inheritance
 
 Before resolving any new icon, honour the project's existing icon system — the
 Inspect stage of the
-[design-artifact lifecycle](../../../docs/contracts/design-artifact-lifecycle.md).
+[design-artifact lifecycle](../../docs/contracts/design-artifact-lifecycle.md).
 
 - **Inspect first.** Detect the icon set already in use (imports, existing
   `set:name` usages, brand assets) before picking one. A new icon matches the
@@ -140,9 +140,9 @@ Inspect stage of the
 
 ## See also
 
-- [`design-canon.md`](../../../docs/guidelines/design-canon.md) § Icon systems — prefer a named system's icon set (Material Symbols / SF Symbols / Fluent / Carbon) when that system is in play.
+- [`design-canon.md`](../../guidelines/design-canon.md) § Icon systems — prefer a named system's icon set (Material Symbols / SF Symbols / Fluent / Carbon) when that system is in play.
 - [`design-tokens`](../design-tokens/SKILL.md) — token system the icon color/size variables should reference.
 - [`typography-system`](../typography-system/SKILL.md) — sibling visual-consistency skill.
 - [`fe-design`](../fe-design/SKILL.md) — broader frontend design discipline.
 - [`icon-consistency`](../../rules/icon-consistency.md) — enforced rule for set discipline across the project.
-- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — icon-relevant slop tells: V5 (hand-drawn SVG mixed with crisp icon-system icons) and T3 (small rounded-square icon tile above every feature heading — the universal AI feature-card template).
+- [`docs/guidelines/design-antipatterns.md`](../../guidelines/design-antipatterns.md) — icon-relevant slop tells: V5 (hand-drawn SVG mixed with crisp icon-system icons) and T3 (small rounded-square icon tile above every feature heading — the universal AI feature-card template).