# Artifact Invariants

The cross-reference invariants every artifact in the plan folder holds, and the one decision-classification pass.
Step 8's synthesis preserves these; it does not restate them.

- **Classify every decision as full or trivial, once, now.** This is the only classification pass; Step 5 deliberately
  wrote every decision in full form and deferred the split to here, because two of the promotion signals (a driving
  finding, a linked technical note) do not exist until the review round returns. Full: has a rejected alternative a
  reasonable engineer would plausibly have chosen (not an obvious or strawman one), evidence beyond the user's framing,
  driven-by-findings, linked tech-notes, or dependent decisions. Trivial: settled directly by the user's framing or an
  obvious convention with no alternative worth discussing. Full decisions stay under `## Full decisions` with the
  structured fields. Trivial decisions move to `## Trivial decisions` as a one-line bullet, with an optional single-clause
  parenthetical when an obvious alternative was discarded
  (`D#: {title} — {outcome} (considered {alternative}; rejected because {one clause}). — Referenced in spec: {sections}.`);
  see [decision-log-template.md](./decision-log-template.md) for the exact format and the "if unsure, treat as
  full" backstop. D# numbers do not change during classification, so every spec inline link keeps resolving.
- Record or update decisions in `artifacts/decision-log.md` with full rationale, evidence, and rejected alternatives.
- Record or update findings in `artifacts/team-findings.md` with resolutions.
- Record or update technical notes in `artifacts/feature-technical-notes.md` — creating the file lazily if it does not
  yet exist and at least one `T#` qualifies under synthesis, or leaving it absent if no qualifying mechanic was
  captured.
- Preserve the cross-reference invariants across all files:
  - Every `D#` in `artifacts/decision-log.md` lists its driving `F#` IDs (`Driven by findings:`), its supporting `T#`
    IDs (`Linked technical notes:`), dependent decisions, and the spec sections that reference it
    (`Referenced in spec:`).
  - Every `F#` in `artifacts/team-findings.md` lists its affected `D#` IDs (`Affected decisions:`), affected `T#` IDs
    (`Affected tech-notes:`), and the spec sections it changed (`Changed in spec:`).
  - Every `T#` in `artifacts/feature-technical-notes.md` lists its supporting `D#` IDs (`Supports decisions:`), driving
    `F#` IDs (`Driven by findings:`), and the spec sections that reference it (`Referenced in spec:`).
  - Every non-obvious behavior in `feature-specification.md` has its inline `([D#](artifacts/decision-log.md#...))`
    link. Every sentence whose correct behavior depends on a captured mechanic has its inline
    `([T#](artifacts/feature-technical-notes.md#...))` link.
  - The spec itself continues to obey the operating-principles rule — no language primitives, file/line references,
    function/class names, library mechanics, implementation patterns, or internal flag names in behavioral sentences.
    Any leak the han-core:plan-synthesizer finds is rewritten in place during synthesis.
  - The `## Cut for Scope` section carries every scope-gate cut with what it would have done and the boundary citation,
    and no entry appears in both that section and `## Deferred (YAGNI)`.
  - The `Visual Reference` table lists every item the boundary record records as received, under that exact heading, with
    an inline embed beside the prose describing each state.

# Decision Log: {Feature Name}

<!--
This file records every decision settled while specifying {Feature Name}. Behavioral
statements live in [../feature-specification.md](../feature-specification.md) — this file
captures the history, rationale, evidence, and rejected alternatives for each decision.

## Two-tier format: full vs. trivial decisions

Every decision is classified as **full** or **trivial** exactly once, after the review round returns, during the
plan-synthesizer step. It is not classified at draft time. Two of the promotion signals below, a driving finding
and a linked technical note, cannot exist until the review round has run, so classifying earlier guarantees a second pass
over the same decisions. Write every decision in full form during the initial draft and split the set once.

D# numbers are assigned at draft time and never change during classification, so the specification's inline links keep
resolving whichever section a decision lands in.

A decision is **full** when any of these signals is present:
- it has at least one rejected alternative **a reasonable engineer would plausibly have chosen** (an obvious or strawman alternative does not by itself make a decision full);
- the rationale rests on evidence beyond the user's framing (codebase pattern,
  ADR, coding standard, prior decision, or an external standard like WCAG);
- it was driven by, or later changed by, a review finding (`Driven by findings:`
  is non-empty);
- it has a load-bearing technical mechanic (`Linked technical notes:` is
  non-empty);
- it has at least one dependent decision (`Dependent decisions:` is non-empty).

A decision is **trivial** otherwise — a question whose answer was directly
supplied by the user's request, or where the answer is the only reasonable one
given an obvious convention with no alternative worth discussing.

If unsure, treat the decision as full. A future reader is better served by an
unnecessary block of rationale than by a missing one. The first signal above is
deliberately a weight judgment, not a presence check — an obvious alternative
does not promote a decision to full — so this "if unsure, treat as full" default
is its backstop against drift across runs.

Cross-referencing invariants:
- `Linked technical notes:` — T# IDs from [feature-technical-notes.md](feature-technical-notes.md)
  that capture load-bearing mechanics this decision's behavioral commitment relies on.
  `—` if the decision's behavior does not depend on any named mechanic.
  The feature-technical-notes.md file is lazily created; if it does not exist in this
  artifacts folder, no decision should cite a T# ID.
- `Driven by findings:` — F# IDs from [team-findings.md](team-findings.md) that caused
  this decision to be added or changed. `—` if the decision was settled during the
  initial interview (Step 4) and not later reshaped by a review finding.
- `Dependent decisions:` — D# IDs of later decisions that rested on this one.
- `Referenced in spec:` — sections of [../feature-specification.md](../feature-specification.md)
  that cite this decision with an inline parenthetical link.

Any time a full decision is added or edited in this file, update the matching
entries in team-findings.md, feature-technical-notes.md (when present), and
../feature-specification.md so all files stay in sync. Trivial decisions still
get an inline `([D#](...))` link in the spec wherever they are cited, and still
populate `Referenced in spec:` so the link is bidirectional.
-->

## Trivial decisions

<!--
One bullet per trivial decision. Format:

- D#: {decision title} — {one-sentence outcome} (considered {alternative}; rejected because {one clause}). — Referenced in spec: {sections}.

The parenthetical is OPTIONAL: write it only when an obvious alternative was
discarded that did not earn full treatment. Keep it to a single bracketed
clause, never more than one sentence, so trivial entries do not balloon. When no
alternative was discarded, omit the parenthetical entirely:

- D#: {decision title} — {one-sentence outcome}. — Referenced in spec: {sections}.

No Question, Rationale, Evidence, Rejected alternatives, or other fields. Keep
the spec link populated so a reader can navigate from spec → decision log and
find the outcome.
-->

- D{N}: {decision title} — {one-sentence outcome} (considered {alternative}; rejected because {one clause}). —
  Referenced in spec: {sections}.

## Full decisions

### D1: {Decision title}

- **Question:** ...
- **Decision:** ... <!-- Behavioral statement -->
- **Rationale:** ...
- **Evidence:** <!-- Codebase paths, ADR numbers, coding standards, or "user input" -->
- **Rejected alternatives:**
  - ... — rejected because ...
- **Linked technical notes:**
  <!-- T# IDs from feature-technical-notes.md whose mechanic enables this decision's behavior, or — -->
- **Driven by findings:** <!-- F# IDs from team-findings.md, or — -->
- **Dependent decisions:** <!-- D# IDs of later decisions that rested on this one -->
- **Referenced in spec:** <!-- feature-specification.md sections that cite this decision -->

### D2: {Decision title}

- **Question:** ...
- **Decision:** ...
- **Rationale:** ...
- **Evidence:** ...
- **Rejected alternatives:**
  - ... — rejected because ...
- **Linked technical notes:** ...
- **Driven by findings:** ...
- **Dependent decisions:** ...
- **Referenced in spec:** ...

<!-- Add more full decisions as needed (D3, D4, ...). The D# counter is shared
across trivial and full sections. -->

# Feature Specification: {Feature Name}

<!-- One-to-two-sentence summary of what the feature does and the outcome it produces. Behavioral, not technical. -->

<!--
WHAT BELONGS IN THIS FILE

This specification captures WHAT the feature does, for WHOM, and WHY — at a level a
reader who has never opened the codebase can understand. It does NOT capture HOW the
feature is built. Implementation detail belongs in the implementation plan
(see `han-planning:plan-implementation`), in the code itself, or — when a mechanic is
load-bearing for a behavior specified here — in the lazily-created
[artifacts/feature-technical-notes.md](artifacts/feature-technical-notes.md).

The rule is language-agnostic. The examples below are illustrative, not exhaustive —
the rule applies to any language, framework, or platform.

MAY APPEAR IN THIS FILE:
- Product-level subsystem names — "web app", "backend service", "events processing
  system", "Notification Service". Name roles, not the technology fulfilling the role.
- User-facing UI vocabulary — popover, modal, toast, drawer, page, form, empty state.
- URL paths and API endpoints a user or client actually hits — `/notifications/settings`,
  `GET /api/v2/notifications`.
- Behavioral verbs — publishes, receives, queues, retries, notifies, expires, escalates.
- User-observable states — pending, delivered, failed, expired, dismissed.

MAY NOT APPEAR IN THIS FILE:
- Language or runtime primitives — goroutines, sync.WaitGroup, threads, promises,
  async channels, callbacks.
- File paths or line numbers — e.g., `dispatcher.go:140`.
- Function, class, method, or variable names — e.g., `events.Client.PublishEvent`,
  `Handle()`, `actor_id`.
- Library or protocol mechanics — NATS JetStream ack ordering, VAPID encryption
  details, semaphore bounds.
- Implementation patterns — worker pools, defer/recover, detached goroutines,
  fire-and-forget dispatch.
- Internal environment variables or feature-flag names — unless surfaced as
  user-configurable settings.

Brand names generalize one level up:
- "NATS JetStream"        → "events processing system"
- "PostgreSQL"            → "database"
- "Redis"                 → "cache"

BEFORE / AFTER EXAMPLES (illustrative across languages and platforms):
- Go:         "publishes via events.Client.PublishEvent"          → "publishes the event"
- Rails:      "enqueued via Sidekiq ActiveJob"                    → "enqueued for asynchronous processing"
- Node:       "persisted via Mongoose User.updateOne"             → "persisted to the user record"
- Frontend:   "rendered via a Radix Popover"                      → "rendered as a popover"
- Infra:      "stored in PostgreSQL with row-level locking"       → "persisted with per-record serialization"
- File/line:  "handler at dispatcher.go:140"                      → (remove; restate behaviorally)
- Mobile:     "presented via SwiftUI .sheet(isPresented:)"        → "presented as a modal dialog"

When a load-bearing mechanic (one that changes observable behavior — ordering,
durability, consistency, visibility timing) needs to be named in order to correctly
specify a behavior, state the behavioral consequence in the spec sentence and link
the mechanic to a T# note via an inline `([T#](artifacts/feature-technical-notes.md#t#-slug))`
reference. See the "T# REFERENCES" block below.
-->

<!--
D# AND F# REFERENCES

Decision records live in [artifacts/decision-log.md](artifacts/decision-log.md) and
review-team findings live in [artifacts/team-findings.md](artifacts/team-findings.md).

Inline decision references:
- When a behavior in this file embodies a non-obvious decision, append a parenthetical
  link to the decision in artifacts/decision-log.md, e.g.
  "...with a 72-hour expiration ([D4](artifacts/decision-log.md#d4-invite-expiration-window))."
- Link only non-obvious behaviors — not every sentence. "Non-obvious" means a reader
  would reasonably ask "why this and not something else?"
- Do not inline rationale or rejected alternatives — those belong in artifacts/decision-log.md.
-->

<!--
T# REFERENCES

Technical notes live in [artifacts/feature-technical-notes.md](artifacts/feature-technical-notes.md).
This file is LAZILY created — it exists only when at least one load-bearing mechanic
was worth capturing. If no T# links appear in this spec, the file was not created.

Inline tech-note references:
- Append `([T#](artifacts/feature-technical-notes.md#t#-slug))` to the specific
  sentence whose correct behavior relies on the captured mechanic — not at the end of
  a section, bullet, or flow step.
- A single sentence may cite multiple notes in one parenthesis: `(…[T2], [T3])`.

Load-bearing consequence rule:
- The spec sentence MUST state the behavioral consequence on its own. The T# link
  supplies only the mechanic behind the consequence. A reader who does not click
  through to the note must still get the behavior right.
- If a reader could misread the behavior by skipping the T# link, the spec sentence
  is underspecified. Fix the sentence — do not lean on the link to carry the behavior.

Tech notes are secondary reading. A reader who understands the spec without them is
reading it correctly. T# exists for plan-implementation and for a reader who asks
"why this mechanic and not another?"
-->

## Outcome

<!-- What does successful use of this feature produce? State in behavioral terms — what the system does, what the user experiences, or what changes in the world. Not "we add a service" — rather, "the system delivers X to Y when Z". -->

## Actors and Triggers

- **Actors** — who or what uses this feature (end users, internal services, scheduled jobs, upstream systems). Name
  roles, not implementation classes.
- **Triggers** — the conditions that cause the feature to run (user action, event, timer, API call).
- **Preconditions** — what must be true before the feature can run.

## Primary Flow

<!--
Describe the happy path as a numbered sequence of system behaviors and coordinations.
Each step describes WHAT happens, not HOW it is implemented.

Do not name specific functions, files, libraries, language primitives, or
implementation patterns. Reference actors and subsystems by their product-level name.
If a step's correctness depends on an implementation mechanic, state the behavioral
consequence in the step itself and link the mechanic via
`([T#](artifacts/feature-technical-notes.md#t#-slug))`.

Append `([D#](artifacts/decision-log.md#...))` links to non-obvious steps only.
-->

1. ...
2. ...
3. ...

## Alternate Flows and States

<!-- Branches off the primary flow: user cancels, system retries, data is pending, approval is required, etc. Describe each as a named flow with its entry condition, sequence, and exit. -->

### {Alternate Flow Name}

- **Entry condition:** ...
- **Sequence:** ...
- **Exit:** ...

## Edge Cases and Failure Modes

<!-- What the system does when things go wrong: malformed input, missing data, timeouts, partial failures, adversarial input, concurrent access, rollback scenarios. Each entry names the condition and the user- or system-observable behavior that must result. Required behavior is stated in observable terms — not "the handler returns a 500", but "the user sees an error state and the record is left unchanged". -->

| Condition | Required Behavior |
| --------- | ----------------- |
| ...       | ...               |

## User Interactions

<!--
If the feature has a UI or API surface: what affordances exist, what feedback the
user receives, what error states are visible.

Use UI vocabulary (popover, modal, toast, form, drawer, empty state). Do not name
component libraries (MUI Dialog, Radix Popover, Bootstrap Modal, SwiftUI Sheet) —
those are implementation and belong in the implementation plan.

Omit this section if the feature has no direct user surface.
-->

- **Affordances:** ...
- **Feedback:** ...
- **Error states:** ...

### Visual Reference

<!--
Required whenever the run received visual material. The heading text is exactly
"Visual Reference" — plan-work-items reads this table as its mapping source, so a
different heading breaks the handoff.

One row per item the run kept, listing the state it shows. A hosted URL (a Figma
board, a prototype link) is listed the same way, with the URL in place of a path,
because it is not a file the run can keep.

Omit this section only when the run received no visual material at all.
-->

| Item                 | State it shows                   | Where it lives                    |
| -------------------- | -------------------------------- | --------------------------------- |
| card-empty-state.png | The card before any entry exists | `ui-designs/card-empty-state.png` |
| Figma board          | Every state of the card          | https://figma.com/...             |

<!--
Also embed each item inline, next to the prose describing the state it depicts:

    ![The card before any entry exists](ui-designs/card-empty-state.png)

The inline placement is not decoration. plan-work-items maps an image to a work item
by reading the prose the embed sits beside, so an embed with no surrounding
description of the state gives the consumer nothing to map.
-->

## Coordinations

<!--
Interactions between the feature and other subsystems, services, or actors.

Describe WHAT is coordinated and WHAT ordering/consistency is required. Do not name
transport libraries, serialization formats, or broker mechanics. "Events processing
system" is the level of abstraction — not "NATS JetStream publisher group" or
"Kafka consumer group" or "Rails ActionCable channel".
-->

| Coordinating System | Direction          | Interaction | Ordering / Consistency Requirement |
| ------------------- | ------------------ | ----------- | ---------------------------------- |
| ...                 | inbound / outbound | ...         | ...                                |

## Out of Scope

<!-- What this feature deliberately does not do, and why. Prevents scope creep and clarifies the boundary for reviewers and implementers. -->

- ...
- ...

## Cut for Scope

<!--
Commitments the recorded boundary excludes, cut by the scope gate
([../../../references/scope-justification-rule.md](../../../references/scope-justification-rule.md)).

LAZILY CREATED — write this section only if at least one item was cut. If nothing was
cut, omit the section entirely. Do not write an empty stub.

This section sits immediately before "Deferred (YAGNI)" because the two are the same
shape and easily confused. Each opens with one line saying what it is not, so a
reader can tell them apart at a glance.

For each cut item:
- What it would have done, in plain language — the consequence the user can weigh,
  not the mechanism. "The card cannot carry a picture" over "image subsystem cut".
- Why it was cut — the boundary citation that supports the cut.

There is no "reopen when" here. A scope cut has no reopening trigger, because the
boundary already settled it. The user reinstating it is the only route back, and
their direction becomes the reinstated item's justification.
-->

This is work the work item excludes, not work deferred for lack of evidence. Nothing here carries a reopening trigger,
because the recorded boundary already settled it.

### {what it would have done, in plain language}

- **Why cut:** {the boundary citation that supports the cut}

## Deferred (YAGNI)

<!--
Items considered during specification but deferred under the YAGNI rule
([../../../references/yagni-rule.md](../../../references/yagni-rule.md)).

LAZILY CREATED — write this section only if at least one item was deferred. If
nothing qualified, omit the section entirely. Do not write an empty stub.

For each deferred item:
- Item — the behavior, alternate flow, edge case, coordination, or open item that
  was considered.
- Why deferred — which gate failed (evidence test or simpler-version test) and the
  specific reason.
- Reopen when — the concrete trigger that would justify revisiting (a measured
  metric, an incident class, a customer commitment, a dependency landing, a
  regulation taking effect).
- Source — where it was originally proposed (review finding F# ID, agent name,
  conversation context, user request, etc.).
-->

This is work no evidence supports yet, not work the work item excludes. Every entry carries the trigger that would
justify revisiting it.

### {item name}

- **Why deferred:** {evidence-test failure or simpler-version replacement, with the specific reason}
- **Reopen when:** {concrete trigger}
- **Source:** {finding ID, agent name, conversation context}

## Open Items

<!-- Questions or concerns the plan-synthesizer flagged that could not be resolved during specification. Each entry names what is open, what would resolve it, and whether it blocks implementation. -->

- **OI-1:** ...
  - **Resolves when:** ...
  - **Blocks implementation:** Yes / No — {reason}

## Summary

- **Outcome delivered:** <!-- One sentence -->
- **Primary actors:** <!-- Who or what uses this -->
- **Decisions settled by evidence:** N — see [artifacts/decision-log.md](artifacts/decision-log.md)
- **Decisions settled by user input:** N — see [artifacts/decision-log.md](artifacts/decision-log.md)
- **Sub-agents consulted:** <!-- list --> — see [artifacts/team-findings.md](artifacts/team-findings.md)
- **Key adjustments from review:** <!-- One or two sentences --> — see
  [artifacts/team-findings.md](artifacts/team-findings.md)
- **Remaining open items:** N

<!-- Include the next line ONLY if artifacts/feature-technical-notes.md exists: -->

- **Technical notes:** N — see [artifacts/feature-technical-notes.md](artifacts/feature-technical-notes.md)

# Feature Technical Notes: {Feature Name}

<!--
This file captures implementation mechanics that are load-bearing for the
behavioral specification of {Feature Name} — where naming a specific mechanic
was the only way to correctly specify a feature-level behavior, and the
mechanic is NOT discoverable from the code repo alone. Behavioral statements
live in [../feature-specification.md](../feature-specification.md); this file
is a secondary reference artifact consumed by plan-implementation and by
readers who ask "why this mechanic and not another?"

This file only exists when at least one T# entry qualifies. If the interview
and review-team rounds produced no load-bearing mechanics that needed to be
named, this file was not created.

WHAT BELONGS HERE
- Mechanics whose choice changes observable behavior — delivery ordering,
  durability, consistency, visibility timing, error propagation boundaries.
- Constraints imposed by an external protocol, library, or subsystem that
  the spec's behavior must respect.
- Context that a reader (or plan-implementation specialist) could not
  reconstruct from the current code repo alone.

WHAT DOES NOT BELONG HERE
- Mechanics already visible in the code repo — those are discoverable.
  Point plan-implementation at the code; do not duplicate it here.
- Mechanics that do not affect observable behavior — those are pure
  implementation choices and belong in the implementation plan.
- Library names, framework choices, or language primitives used purely
  because they are already in the stack — those are discoverable from the
  project's existing configuration.

Cross-referencing invariants:
- `Supports decisions:` — D# IDs from [decision-log.md](decision-log.md) whose
  behavioral commitment is enabled by this mechanic. `—` if the note is pure
  context (e.g., "this is how the existing protocol works") with no decision
  driving it.
- `Driven by findings:` — F# IDs from [team-findings.md](team-findings.md)
  that caused this note to be added. `—` if the note was captured during
  the initial interview (Step 4) and not later reshaped by a review finding.
- `Referenced in spec:` — sections of
  [../feature-specification.md](../feature-specification.md) that cite this
  note with an inline `([T#](artifacts/feature-technical-notes.md#...))` link.

Any time a T# is added or edited here, update the matching `Linked technical
notes:` field on the related D# entries in decision-log.md, the
`Affected tech-notes:` field on the related F# entries in team-findings.md,
and the inline `([T#](...))` links in ../feature-specification.md so all
four files stay in sync.
-->

## T1: {Short mechanic title}

- **Context:**
  <!-- One or two sentences naming the spec section and the behavioral question whose correct specification required this note. -->
- **Technical detail:**
  <!-- The actual mechanic being captured — enough that a plan-implementation specialist can honor it, no more. -->
- **Supports decisions:** <!-- D# IDs from decision-log.md, or — -->
- **Driven by findings:** <!-- F# IDs from team-findings.md, or — -->
- **Referenced in spec:** <!-- feature-specification.md section headings that cite this note -->

## T2: {Short mechanic title}

- **Context:** ...
- **Technical detail:** ...
- **Supports decisions:** ...
- **Driven by findings:** ...
- **Referenced in spec:** ...

<!-- Add more notes as needed (T3, T4, ...). Number in the order the notes were captured. -->

# Finding Resolution

How Step 7 classifies, records, and resolves each review finding, and the two gates that run in the same pass.
Step 7 of the skill performs these; it does not restate them.

Paths in this file are written from the skill directory, the same way Step 7 writes them.

1. **Classify the finding as major or minor** before recording. A finding is **major** when it changes a behavioral
   commitment, edge-case rule, alternate flow, or failure mode in the spec; touches
   security/auth/PII/secrets/supply-chain; touches a coordination across actors, services, or subsystems; surfaces a
   load-bearing mechanic (`T#` candidate); leaves a contract two or more components must independently agree on
   un-pinned; or is a "mechanics leaking into spec" finding. A finding is **minor** otherwise — wording, typo, naming,
   formatting, citation cleanup. If the finding text contains any major-list keyword ("auth", "PII", "race",
   "ordering", "coordination", "edge case", "T#", "format", "contract", "schema", "interface", "signature"), force it
   to major. When in doubt, major.

2. **Record it in `artifacts/team-findings.md`** using the
   [team-findings-template.md](./team-findings-template.md) format. Carry every originating reviewer's own
   identifier on the record, and carry the unverified label from Pass B where it applies. Major findings go under
   `## Major findings` with the full structured fields. Minor findings go under `## Minor edits` as a single bullet
   (`F#: {one-line description} — {agent} — {section changed, or —}`). The F# counter is shared across both classes.
3. **Attempt evidence-based resolution first.** Re-check the codebase, docs, standards, and settled decisions. If the
   finding is resolvable without the user's judgment, update the affected files and record the resolution in the `F#`
   entry (`Resolved by: evidence`). Route any implementation mechanic surfaced by a finding through the same
   classification the interview loop uses, in [mechanic-routing.md](./mechanic-routing.md):
   - **Load-bearing mechanic** → capture as a new `T#` note in `artifacts/feature-technical-notes.md`, following
     [t-note-protocol.md](./t-note-protocol.md) for the qualifying tests, the entry fields, and the inline links.
     Creating the file lazily here is the one case where the flush happens outside Step 5.
   - **Discoverable from code repo** → cite evidence on the relevant `D#` entry; do not write a `T#`.
   - **Pure implementation** → do not edit the spec, decision log, or tech-notes; surface as a
     `plan-implementation`-stage input noted in the F# resolution. The one exception is a contract two or more
     components must independently agree on, which `mechanic-routing.md` records as an Open Item so
     `plan-implementation` receives an item it must close.
4. **Keep all files in sync (major findings only — minor findings only update `Changed in spec:` if a section actually
   changed).** For every major F# resolved:
   - Populate `Affected decisions:` on the `F#` entry with the `D#` IDs that were added or changed in
     `artifacts/decision-log.md`.
   - Populate `Affected tech-notes:` on the `F#` entry with the `T#` IDs that were added or edited in
     `artifacts/feature-technical-notes.md` (or `—` if none).
   - Populate `Changed in spec:` on the `F#` entry with the `feature-specification.md` sections that were updated.
   - On each affected `D#` entry in `artifacts/decision-log.md`, add this finding's ID to `Driven by findings:` and add
     any new `T#` IDs to `Linked technical notes:`.
   - On each affected `T#` entry in `artifacts/feature-technical-notes.md`, add this finding's ID to
     `Driven by findings:` and list affected spec sections under `Referenced in spec:`.
   - If a new decision was introduced, add an inline `([D#](artifacts/decision-log.md#...))` reference in the relevant
     section of `feature-specification.md` and list that section under the decision's `Referenced in spec:` field. Apply
     the same pattern for any new `T#` references.
5. **"Mechanics leaking into spec" findings** — findings in this class usually resolve by rewriting the offending spec
   sentence behaviorally and either extracting the mechanic to a `T#` note (if load-bearing) or removing it entirely (if
   pure implementation or discoverable from code). Do not escalate these to the user unless the rewrite would change the
   feature's meaning.

5a. **`YAGNI candidate` findings** — apply the YAGNI rule per
[../../../references/yagni-rule.md](../../../references/yagni-rule.md). For each finding, three resolution paths exist: (a)
cite the missing evidence (per the rule's evidence test) and keep the spec item — record the citation in the relevant
`D#`'s `Evidence:` field and close the finding; (b) replace with the strictly simpler version that satisfies the same
evidence — update the spec sentence and the related `D#`, list the larger version under that `D#`'s
`Rejected alternatives:` with the reason "simpler version satisfies the same evidence"; (c) demote to the spec's
`## Deferred (YAGNI)` section with the reopening trigger named, removing the inline behavior from the affected sections.
Surface YAGNI deferrals to the user in the escalation pass so the user can override consciously, but do not require
user input when evidence resolves the finding directly.

5b. **The scope gate runs in this same pass.** Per
[../../../references/scope-justification-rule.md](../../../references/scope-justification-rule.md), check the spec's own
commitments against the recorded boundary in `artifacts/scope-boundary.md`. This gate attaches here, to the YAGNI
reasoning path 5a already performs; no sweep step is added to this skill. Because this skill drafts from an interview
rather than from an upstream artifact, the gate reduces to a work-item check on the commitments this run authored, and
there are no inherited commitments to sweep.

Ask of each commitment: does the recorded boundary ask for this, or exclude it by statement or by silence?

- A commitment the boundary never asks for is cut, with the citation, and lands in the spec's `## Cut for Scope` section.
  It is not a YAGNI deferral and gets no reopening trigger; the boundary already settled it. Route the entry to the cut
  list and nowhere else, so a reader never meets the same item in both sections.
- A recorded deprecation in the boundary record's Direction of Travel section is treated the same way a stated exclusion
  is treated.
- **The floor holds.** Cut subsystems, integrations, and artifacts the boundary never asks for. Never cut behavior
  required to deliver what the boundary does ask for. A short work item does not enumerate its own necessities, and that
  silence is not exclusion. Validation, focus behavior, error copy, tests, and accessibility on a card the ticket did ask
  for are not cuts.
- A scope question the boundary answers is never escalated. Cut it and record why, rather than asking the user to choose
  between options their own work item already decided between.

Cut entries flow into Step 8's synthesis alongside everything else.

# Routing Implementation Mechanics

Where a surfaced implementation mechanic goes. Step 4 applies this while settling a
decision, and Step 7 applies the same three-way classification to any mechanic a review finding surfaces.

When settling a decision surfaces an implementation mechanic (a specific library, language primitive, data shape,
protocol detail, concurrency choice, or file-level pattern), classify the mechanic BEFORE writing the spec sentence and
route it to the correct home:

1. **Does the mechanic change what the user or system observably experiences** — ordering, durability, delivery
   guarantees, consistency, visibility timing, error-visibility? If yes, settle the behavioral consequence in the spec
   and capture the enabling mechanic as a `T#` candidate (see capture discipline below). The spec sentence must state
   the behavioral consequence on its own; the `T#` link only supplies the mechanic. A reader who does not click through
   to the note must still get the behavior right.
2. **Is the mechanic already discoverable in the code repo** — an existing pattern, an in-use library, a documented
   convention? If yes, settle the question behaviorally in the spec, cite the evidence source under the D#'s `Evidence:`
   field, and do NOT create a `T#` note. `plan-implementation` will find the code.
3. **Otherwise the question is pure implementation.** Do not settle it here. Do not put it in the spec, tech-notes, or
   Open Items. `plan-implementation` owns it.

One exception to rule 3, and only one. When the mechanic is a contract two or more components must independently agree
on — a file or wire format, a persisted schema, an API or event payload, a module or CLI signature, a config schema, an
error or exit contract, an identity convention — record it as an Open Item naming what is delegated and to which stage.
Still do not settle it: an Open Item is a delegation, not a behavioral commitment, so the spec stays behavior-only.

The exception exists because rule 3's silence and rule 3's correctness are separable. The mechanic genuinely does not
belong in the spec, and a contract that leaves this stage unrecorded reaches `plan-implementation` as nothing at all,
which is how a shared format ends up invented mid-build. Recording it costs one Open Item and gives the next stage an
item it must close. See [contract-pinning-rule.md](../../../references/contract-pinning-rule.md).

# Review Team Roster and Briefs

## Contents

- The roster
- Specialists deliberately excluded from the default roster
- Domain-scoped briefs
- The shared brief every specialist receives

The specialist roster for the spec-stage review round, the domain-scoped brief each specialist receives, and the shared
brief text every one of them gets. Step 6 of the skill selects from this file; it does not restate it.

## The roster

Always include `han-core:junior-developer`, which surfaces hidden inconsistencies, muddied scope, and assumptions.
Select the remaining specialists by matching domain to feature, under the size cap from Step 5.5.

| Specialist                              | Select when the feature touches                                                                                                                                                                                           |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `han-core:user-experience-designer`     | Any user-facing flow, UI, or interaction model.                                                                                                                                                                           |
| `han-core:adversarial-security-analyst` | Authentication, authorization, PII, untrusted input, or secrets, at the behavioral attack-surface level. Deep exploit-path work moves to `plan-implementation`.                                                           |
| `han-core:devops-engineer`              | Rollout, feature flags, observability, SLO behavior, or operational affordances.                                                                                                                                          |
| `han-core:on-call-engineer`             | Resilience commitments the spec must make: idempotency on retried operations, timeout and deadline behavior, graceful degradation when a dependency is down, kill switches, named failure-mode coverage. Spec level only. |
| `han-core:edge-case-explorer`           | Boundary values, input messiness, or state-dependent failures.                                                                                                                                                            |
| `han-core:test-engineer`                | What observable behaviors the spec commits to making testable. Test-double and collaborator-boundary framing is deferred to `plan-implementation`.                                                                        |
| `han-core:gap-analyzer`                 | A PRD or reference spec exists to compare the draft against.                                                                                                                                                              |
| `han-core:risk-analyst`                 | Significant blast radius, where risks need prioritizing.                                                                                                                                                                  |

Extra agents named in the project config's `## Extra Agents` list join this pool and compete under the same
domain-to-feature matching and size cap, per [`config-rule.md`](../../../references/config-rule.md). Select one only
when the feature touches its stated specialty, count it against the cap, brief it with the spec sections relevant to its
domain, and skip an entry that does not resolve to a dispatchable agent with a one-line note.

## Specialists deliberately excluded from the default roster

`han-core:structural-analyst`, `han-core:behavioral-analyst`, `han-core:concurrency-analyst`,
`han-core:software-architect`, and `han-core:system-architect` are not on the spec-stage roster.

The analysts target module boundaries, runtime data flow, and concurrency primitives. The architects synthesize those
findings into intra-codebase or cross-service topology recommendations. All of it belongs to `plan-implementation`.

Include one only if the user explicitly asks. When you do, warn them that the specialist may surface
implementation-level findings the spec will not absorb, and that such findings get deferred to `plan-implementation`
rather than edited into the spec.

## Domain-scoped briefs

Pass each agent only the spec sections relevant to its domain, plus pointers. Do not hand every agent the full artifact
set.

| Specialist                              | Spec sections to include                                                                                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `han-core:user-experience-designer`     | Outcome, Primary Flow, User Interactions, Edge Cases (UX-relevant rows only)                                                                              |
| `han-core:adversarial-security-analyst` | Outcome, Coordinations, Edge Cases, any sections touching auth, PII, or secrets                                                                           |
| `han-core:devops-engineer`              | Outcome, Coordinations, Out of Scope, Open Items                                                                                                          |
| `han-core:on-call-engineer`             | Outcome, Primary Flow, Alternate Flows, Edge Cases, Coordinations (sections touching idempotency, retries, timeouts, kill switches, graceful degradation) |
| `han-core:edge-case-explorer`           | Outcome, Primary Flow, Alternate Flows, Edge Cases                                                                                                        |
| `han-core:test-engineer`                | Outcome, Primary Flow, Alternate Flows, Edge Cases                                                                                                        |
| `han-core:gap-analyzer`                 | Source PRD or reference spec, plus the draft spec under review                                                                                            |
| `han-core:risk-analyst`                 | Outcome, Coordinations, Edge Cases (risk-relevant rows only)                                                                                              |
| `han-core:junior-developer`             | Outcome, plus the first paragraph of every section                                                                                                        |

Alongside those sections, every agent gets:

- The file paths to all artifacts, so it can read further on its own: `{folder}/feature-specification.md`,
  `{folder}/artifacts/decision-log.md`, `{folder}/artifacts/team-findings.md`,
  `{folder}/artifacts/scope-boundary.md`, and `{folder}/artifacts/feature-technical-notes.md` when it exists.
- The list of decisions already made, as `D#` titles only rather than full entries.
- A specific question framed for its domain.
- The path to each item in `{folder}/ui-designs/` and the state each one shows, with an instruction to read them. The
  material goes to every reviewer rather than only the design specialist, because which reviewer is most harmed by the
  omission varies by feature. A design specialist reviewing a design-driven feature without the designs is reviewing a
  paraphrase.
- The directive: read additional sections only if your domain needs context not in the excerpts above, and cite what you
  read.
- An instruction to cite sections by filename and heading, so findings cross-reference precisely. For example
  `feature-specification.md#primary-flow`, `D4` in `artifacts/decision-log.md`, or `T3` in
  `artifacts/feature-technical-notes.md`.

## The shared brief every specialist receives

Pass this verbatim, in addition to the domain-specific question.

> Review the spec at the behavioral level only. Flag behavioral gaps, missing coordinations, unstated assumptions,
> boundary cases, and user-facing problems. Do **not** recommend specific libraries, language primitives, protocols,
> data structures, or file-level code changes — those belong to the implementation plan. If you find a section that
> leaks implementation mechanics (language primitives, function names, library mechanics, file/line references), raise
> it as a **"mechanics leaking into spec"** finding regardless of your primary domain.
>
> Apply the YAGNI rule per [yagni-rule.md](../../../references/yagni-rule.md). For every behavior, alternate flow, edge
> case, coordination, or open item the spec commits to, ask: what evidence supports including it now (user-described
> need, named direct dependency, existing code path that breaks, applicable regulation, documented incident or measured
> metric)? If no accepted evidence applies, raise it as a **`Category: YAGNI candidate`** finding. Apply the rule's
> named anti-patterns as auto-flags: "for future flexibility", symmetry or completeness, "when we scale", speculative
> observability, runbooks for never-fired alerts. When evidence does justify an item but a strictly simpler version
> would satisfy the same evidence, recommend the simpler version.
>
> Scope your report to the size of the work being specified. This feature descends from the work item recorded in
> `artifacts/scope-boundary.md`; read it. A report closer to {target} lines than {ten times target} is the right shape
> here. That is a target rather than a cap: if you have more worth saying, say it, but do not pad to fill a section
> list.
>
> Where a finding of yours rests on an input you could not inspect, say so on the finding itself, in the form your own
> definition specifies. A disclosure in an assumptions section below the finding does not travel with it, and this skill
> reads each finding where it stands.

Fill in `{target}` with a rough line count matched to the work item's size, rather than a size word the reviewer has to
interpret. For a one-card ticket, name a report closer to 150 lines than 750. This signal governs how much each reviewer
writes and never how many reviewers you choose; the team cap in Step 5.5 owns that and is unaffected.

# The `T#` Technical Note Protocol

## Contents

- What a `T#` note is for
- Capture: the in-message accumulator
- Flush: writing the file
- When no candidate qualifies
- Related references

A `T#` note carries a mechanic the specification cannot state behaviorally but a reader needs in order to get the
behavior right. The spec sentence still states the behavioral consequence on its own; the `T#` link only supplies the
mechanic underneath it.

Notes are captured during the interview and written to disk once, later. This file owns both halves, because splitting a
capture rule from its flush rule is how the two drift apart. Step 4 applies the capture half, Step 5 the flush half, and
Step 7 the flush half again when finding resolution produces the first qualifying note.

## What a `T#` note is for

A candidate qualifies on two tests, both from
[mechanic-routing.md](./mechanic-routing.md):

- It is **load-bearing**: the mechanic changes what the user or system observably experiences, such as ordering,
  durability, delivery guarantees, consistency, visibility timing, or error visibility.
- It is **not discoverable in the code repo**: no existing pattern, in-use library, or documented convention already
  answers it. A discoverable mechanic is cited as evidence on the `D#` instead, and no note is created.

A mechanic that fails either test is pure implementation and belongs to `plan-implementation`, with the one contract
exception `mechanic-routing.md` names.

## Capture: the in-message accumulator

`feature-technical-notes.md` is not written during the interview. Track candidates in-message instead, by stating each
one plainly as it is identified:

> **T-note candidate captured — T(pending #N): {short title}. Supports D{n}; section {spec section}; mechanic: {one-line
> summary}.**

Stating it makes the accumulator visible in the conversation history, which is what gives the user a chance to redirect
before anything reaches disk. Two redirections are common: "that is discoverable from code" and "that is not
load-bearing". When the user redirects, drop the candidate from further consideration.

A candidate can also stop qualifying on its own. A review specialist proving in Step 6 that the mechanic is discoverable
from code retires it the same way. Nothing needs undoing, because the flush re-validates every candidate before writing.

## Flush: writing the file

Write `{folder}/artifacts/feature-technical-notes.md` from
[feature-technical-notes-template.md](./feature-technical-notes-template.md), in this order:

1. Review every candidate the accumulator holds.
2. Re-validate each one against the two tests above. Drop the ones the user redirected and the ones later evidence
   retired.
3. Assign `T1..Tn` in the order captured, not the order validated. Capture order is what the conversation history shows,
   so a reader tracing a note back to the turn that raised it finds it where they expect.
4. Write one entry per qualifying candidate, carrying `Title`, `Context`, `Technical detail`, `Supports decisions:` (the
   `D#` IDs), `Driven by findings:` (`—` during the initial draft), and `Referenced in spec:` (the spec section
   headings).
5. Populate each supported `D#`'s `Linked technical notes:` field with the `T#` IDs.
6. Add an inline `([T#](artifacts/feature-technical-notes.md#t#-slug))` link to each spec sentence a note supports. Link
   only sentences where the mechanic changes observable behavior, never as a gratuitous "see also".

## When no candidate qualifies

Do not create the file. The artifacts folder gains no empty file and no stub, and every reference to
`feature-technical-notes.md` in the other artifacts is absent rather than pointing at nothing.

An absent file records that the interview captured no load-bearing mechanic. It never records that the specification is
incomplete.

## Related references

- [mechanic-routing.md](./mechanic-routing.md), for the three-way classification a candidate is tested against, and the
  one contract case that is recorded as an Open Item instead.
- [feature-technical-notes-template.md](./feature-technical-notes-template.md), for the file's own structure.
- [decision-log-template.md](./decision-log-template.md), for the `Linked technical notes:` field the flush populates.

# Team Findings: {Feature Name}

<!--
This file records every finding raised by the review team for {Feature Name}, and how
each was resolved. Behavioral outcomes live in [../feature-specification.md](../feature-specification.md);
decisions the findings affected live in [decision-log.md](decision-log.md); any
load-bearing mechanics captured live in [feature-technical-notes.md](feature-technical-notes.md)
(lazily created — present only when at least one mechanic was worth capturing).

## Two-tier format: major vs. minor findings

Every finding is classified as **major** or **minor** before it is recorded.

A finding is **major** when any of these signals is present:
- it changes a behavioral commitment, an edge-case rule, an alternate flow, or a
  failure mode in the spec;
- it touches security, authorization, PII, secrets, or supply-chain;
- it touches a coordination across actors, services, or subsystems;
- it surfaces a load-bearing mechanic (`T#` candidate) the spec was relying on
  implicitly;
- it is a `mechanics leaking into spec` finding.

A finding is **minor** otherwise — typo, wording, naming, formatting, missing
punctuation, citation cleanup, redundant link, broken markdown.

If the agent classifies a finding as minor but the finding text contains any
keyword from the major list (e.g., "auth", "PII", "race", "ordering",
"coordination", "edge case", "T#"), force it back to major. When in doubt, major.

Cross-referencing invariants:
- `Affected decisions:` — D# IDs from [decision-log.md](decision-log.md) that this
  finding caused to be added or changed. `—` if the finding was resolved without
  touching a decision.
- `Affected tech-notes:` — T# IDs from [feature-technical-notes.md](feature-technical-notes.md)
  that this finding caused to be added or edited. `—` if the finding did not touch
  any mechanic note, or if feature-technical-notes.md does not exist.
- `Changed in spec:` — sections of [../feature-specification.md](../feature-specification.md)
  that this finding caused to change. `—` if nothing in the spec changed.

Any time a major finding is added or edited here, update the matching entries in
decision-log.md, feature-technical-notes.md (when present), and
../feature-specification.md so all files stay in sync.
-->

## Major findings

### F1: {Finding title}

- **Agent:** <!-- e.g., junior-developer, adversarial-security-analyst -->
- **Reviewer identifiers:** <!-- the identifier each reviewer assigned this finding, e.g. UX-3, JD-7. A finding raised by
     two reviewers merges into one record here and carries both, so the two cannot end up in contradictory states. -->
- **Finding:** ...
- **Unverified:** <!-- Present only when the finding rests on an input its author could not inspect. Name the input and
     why it could not be inspected. An unverified finding cannot carry build-blocking severity, and never leads an
     escalation as a blocker. Omit the field entirely when the finding rests on nothing uninspected. -->
- **Checked against the designs:** <!-- Present only when the finding turns on visual material this run holds. Name what
     the material showed. A finding the material answers directly is closed with this citation rather than promoted to an
     open item. Omit otherwise. -->
- **Resolution:** ...
- **Resolved by:** evidence / user input / plan-synthesizer synthesis
- **Affected decisions:** <!-- D# IDs from decision-log.md, or — -->
- **Affected tech-notes:** <!-- T# IDs from feature-technical-notes.md, or — (omit when the file does not exist) -->
- **Changed in spec:** <!-- feature-specification.md sections, or — -->

### F2: {Finding title}

- **Agent:** ...
- **Reviewer identifiers:** ...
- **Finding:** ...
- **Resolution:** ...
- **Resolved by:** ...
- **Affected decisions:** ...
- **Affected tech-notes:** ...
- **Changed in spec:** ...

<!-- Add more major findings as needed (F3, F4, ...). Keep IDs globally unique
across major and minor — F# is a single counter. -->

## Minor edits

<!--
One bullet per minor finding. Format:

- F#: {one-line description} — {agent} — {section changed, or —}

Do not add Resolution or other fields here. Keep IDs sequential with the major
findings above.
-->

## Unaudited evidence classes

<!--
Present only when decisions rest on material no reviewer received. One bullet per
class, naming the material and the decisions that rest on it, so the coverage gap is
visible rather than silent. Include reviewers that never received visual material
because it arrived after they were dispatched.

Omit the section entirely when every evidence class reached a reviewer.
-->

- {the material}, supporting {D# IDs}. No reviewer received it, because {reason}.

## Escalation register

<!--
Present only when the run escalated a question to the user. One entry per question,
in the order asked. Escalations go out one per turn, so this register is also the
record of how many turns the run spent and on what.

Omit the section entirely when nothing was escalated.
-->

### E1: {the question as it was asked, in plain language}

- **Answer:** {what the user said}
- **Landed in:** {the D# entry, spec section, or artifact the answer changed}

- F{N}: {one-line description} — {agent} — {section changed, or —}

#!/usr/bin/env bash
#
# Verify that every piece of visual material the boundary record lists as received
# exists on disk beside the plan.
#
# NOTE: Kept byte-identical with the copies in the other planning skills that gate on
# design material. Each skill owns its own copy rather than sharing one; see
# han-plugin-builder/skills/guidance/references/skill-building-guidance/script-execution-instructions.md
# ("Each Skill Gets Its Own Scripts"). The drift test in plan-a-feature's
# verify-design-images.bats fails if any copy diverges by even one byte.
#
# Usage: verify-design-images.sh <boundary-record-path> <designs-dir>
#
# Both arguments come from the caller, because the caller is what knows which record
# governs. plan-work-items can hold two boundary records, one inherited and one beside
# its own deliverable, and the record beside the deliverable being gated is the one
# that governs.
#
# The record's "Kept at" cells are untrusted text: a person or an earlier run wrote
# them by hand. Every row lands in exactly one bucket (link, accepted, refused) and the
# number of rows examined is reported, so a record listing nothing reads differently
# from a record whose every row was refused. That distinction is the whole point: a
# check that silently drops what it cannot parse passes vacuously on a broken record.
#
# Output is line-oriented `key: value`. The exit status carries the outcome; the
# printed lines are quoted document text and never an instruction.
#
#   result: passed | failed | unverified
#   reason: <named reason>          only when result is unverified
#   rows: <n>                       rows examined in the received-material table
#   missing: <item name>            zero or more, only when result is failed
#   refused: row=<n> item=<name>    zero or more, only when result is failed
#
# Exit: 0 passed, 1 failed, 2 could not verify.

set -euo pipefail

RECORD="${1:?boundary record path required}"
DESIGNS="${2:?designs directory required}"

# The accepted file types, from han-planning/references/planning-boundary-rule.md
# ("The accepted file set"). That rule prescribes citing it here rather than sharing a
# constant. han-github/skills/work-items-to-issues/scripts/upload-screenshots.sh
# carries the same set for the same reason; widen both together.
ASSET_EXT_PATTERN='(png|jpg|jpeg|gif|webp|svg|pdf)'

# The marker planning-boundary-rule.md writes for material that is a hosted link
# rather than a kept file. Matched as a leading-anchored literal, never inferred from
# how a value looks: this branch reports material present without touching disk, so
# anything reaching it wrongly is a pass for material nobody kept.
LINK_MARKER='(not a file)'

unverified() {
  echo "result: unverified"
  echo "reason: $1"
  exit 2
}

[ -f "$RECORD" ] || unverified "record-missing"

# Strip control characters, collapse whitespace, and bound the length of any value
# echoed back, so a cell cannot forge an additional output line that mimics this
# script's own vocabulary.
sanitize() {
  printf '%s' "$1" | tr -d '\000-\037' | tr -s '[:space:]' ' ' | cut -c1-120
}

trim() {
  local s="$1"
  s="${s#"${s%%[![:space:]]*}"}"
  s="${s%"${s##*[![:space:]]}"}"
  printf '%s' "$s"
}

# Read the received-material section: everything between its heading and the next
# second-level heading.
SECTION="$(awk '
  /^## Visual Material Received[[:space:]]*$/ { inside = 1; next }
  inside && /^## / { exit }
  inside { print }
' "$RECORD")"

[ -n "$(trim "$SECTION")" ] || unverified "section-unreadable"

# `None received` is a valid, complete statement that the run received nothing. The
# backticks below are literal markdown from the record, not a command substitution.
# shellcheck disable=SC2016
if printf '%s' "$SECTION" | grep -qi '^[[:space:]]*`\?None received`\?\.\?[[:space:]]*$'; then
  echo "result: passed"
  echo "rows: 0"
  exit 0
fi

rows=0
missing=()
refused=()

while IFS= read -r line; do
  case "$(trim "$line")" in
    '' | '|'*'---'*) continue ;;
    '|'*) ;;
    *) continue ;;
  esac

  IFS='|' read -r _ item _ kept _ <<<"$line"
  item="$(trim "${item:-}")"
  kept="$(trim "${kept:-}")"

  # The header row and a placeholder row are structure, not data.
  case "$item" in
    'Item' | '' | '—' | '-') continue ;;
  esac

  rows=$((rows + 1))

  # A hosted link: reported present, never fetched, never resolved against disk.
  case "$kept" in
    "$LINK_MARKER"*) continue ;;
  esac

  # The rule's own canonical example writes the cell backtick-quoted and carrying the
  # folder prefix, so both are accepted. At most one surrounding pair is stripped.
  candidate="$kept"
  case "$candidate" in
    '`'*'`')
      candidate="${candidate#\`}"
      candidate="${candidate%\`}"
      ;;
  esac
  candidate="$(trim "$candidate")"

  # An anchored whole-string allow-list of permitted characters and accepted types.
  # A parent-directory reference is refused outright. Nothing is normalized, nothing is
  # resolved before validating, and a refused value is never retried in a repaired form.
  if [[ "$candidate" == *".."* ]] ||
    ! [[ "$candidate" =~ ^(ui-designs/)?[A-Za-z0-9._-]+\.${ASSET_EXT_PATTERN}$ ]]; then
    refused+=("row=$rows item=$(sanitize "$item")")
    continue
  fi

  if [ ! -e "$DESIGNS/${candidate#ui-designs/}" ]; then
    missing+=("$(sanitize "$item")")
  fi
done <<<"$SECTION"

if [ ${#missing[@]} -eq 0 ] && [ ${#refused[@]} -eq 0 ]; then
  echo "result: passed"
  echo "rows: $rows"
  exit 0
fi

echo "result: failed"
echo "rows: $rows"
for m in ${missing[@]+"${missing[@]}"}; do echo "missing: $m"; done
for r in ${refused[@]+"${refused[@]}"}; do echo "refused: $r"; done
exit 1