@erclx/canon 4.104.0 → 4.106.0

package/claude/skills/session-relay/SKILL.md

@@ -1,27 +1,92 @@
 ---
 name: session-relay
-description: Composes the relay a worker or planner owes its controller when the session holds no message-sending tool, carrying the sender's own name, the addressee the calling role's own ladder resolves, and the message body that role already names, opened with a header naming all three so an operator can copy the block whole. Fires only from inside `role-worker` or `role-planner`'s own `## The channel` section, at the point that section finds no tool to send through. Do NOT invoke it when a message-sending tool exists, which is the ordinary channel, and do NOT invoke it to resolve an addressee for anything other than a channel obligation those two roles already state.
+description: Relays a message to another session, turning the sessionId the caller named into an address at the moment of sending and composing a copyable block where no send tool exists. Use when asked to "relay this", "message the controller", "send this over to the session that dispatched me", or "tell the other session", with or without a role. Do NOT use to decide what the message says, and do NOT use to assert what a session may write or is on the hook for, which is `role-worker` or `role-planner`.
 ---
 
 # Session relay
 
-`role-worker` and `role-planner` each owe their controller a set of messages, and each assumes a message-sending tool exists to carry them. A session holding none has nothing to send through, and the paragraph stating what to do about that used to sit inline in both bodies, repeating the same protocol twice. This skill is that paragraph, and both role bodies point to it instead of each carrying their own copy.
+This is the one place a session sends to another session. It holds the
+mechanical half of the send: naming the sender, turning a `sessionId` or a
+branch into an address that reaches, and putting the text through whichever
+route exists. It holds none of the other half. What the message says and who it
+goes to come from whatever dispatched this session, and from the calling role's
+own `## The channel` section where the session holds a role.
 
-Read the calling body's `## The channel` section for the message owed and the ladder that resolves its addressee. This skill does not restate either.
+It fires for a session holding a role and for one holding none. A roleless
+session reaches this body directly and finds everything it owes stated here,
+rather than reading a ladder written for a role it does not have.
 
-## Guards
+## Step 1: name the sender
 
-- Refuse to fire when the calling session holds neither `role-worker` nor `role-planner`. Say so, and state what it owes instead: resolve the addressee at send time through `canon sessions list --json`, never by name prefix, and send a block out as a message before it becomes an interactive prompt, leaving the message content to whatever dispatched it. Checked first, since a caller that never held either role never had a ladder here to run, and the tool guard below reads as the whole reason only once this one has cleared.
-- Refuse to fire when a message-sending tool is available. Say so, name the tool, and send through it. This skill exists for the gap, never as an alternative to the ordinary channel.
+Read this session's own name from `canon sessions list --self --json`. A
+message an operator relays by hand needs a sender as much as an addressee, and
+a message arriving through a tool is read against whoever sent it.
 
-## Steps
+A refusal carrying `no-self-identity` or `no-self-row` means the roster holds
+nothing to name the sender with. Report the refusal and its reason in place of a
+name rather than guessing one.
 
-1. Read this session's own name from `canon sessions list --self --json`. A refusal here, `no-self-identity` or `no-self-row`, means the roster carries nothing to name the sender with. Report the refusal and its reason in place of a name rather than guessing one.
-2. Resolve the addressee. Run the calling role's own `## The channel` ladder to the letter rather than a second one here, and take its outcome, whatever it is, as this skill's addressee.
-3. Carry the message body the calling role's bullet already names, verbatim. This skill composes and never drafts, so the pull request announcement, the address-review announcement, or the blocked question is exactly the text that bullet states, with its own facts filled in.
-4. Open the composed text with a header naming the sender, the addressee, and what the message is. Close the turn with nothing after it, so the block above is the whole of what an operator copies.
+Where the installed CLI answers `--self` with an unknown option, that flag is
+newer than the release this session holds, so there is no refusal and no reason
+to report. Name the sender from what the environment states instead, and say the
+roster did not answer, so the reader knows the name was not confirmed against
+it.
 
-Where the installed CLI answers `--self` with an unknown option, that flag is newer than the release this session holds, so step 1 meets no refusal with a reason to report. Name the sender from what the environment states instead, and say the roster did not answer, so the reader knows the name was not confirmed against it.
+## Step 2: resolve the addressee
+
+The caller names the addressee as a `sessionId` or as a branch, never as a name.
+A name is derived from what a session turns out to be doing and goes stale
+inside the window a build or a plan takes, so resolve it at the moment of
+sending rather than at launch.
+
+- From a `sessionId`: run `canon sessions list --json`, find the row carrying that id, and take the `name` on it.
+- From a branch: run the same read and take the row whose `branch` matches. Nothing renames a session when it takes a role, which is why an id is the stronger key and a branch is the fallback rather than the default.
+
+Then check that name against the agent listing before sending it. A name is not
+unique, and the roster carries no field separating two live sessions holding
+one, so the resolution can end on a string that reaches the wrong session.
+
+- One row under the name: send it bare.
+- More than one row: complete the address with the `[ref]` that listing prints beside each row, rather than sending to the name alone, which lands on whichever row the channel resolves first. Two sessions differing only by a trailing ` (3)` is the shape this meets in practice.
+
+Never filter that roster by a name prefix. Every self-dispatched worker is named
+`worker-<project>-<slug>`, so a prefix scan returns a sibling or this session
+itself, which is the defect that sent messages owed to a controller somewhere
+else.
+
+Report a resolution that returns nothing rather than falling back to a guess.
+The roster and the send channel enumerate different populations in both
+directions, measured at one moment: a live background session sat on the roster
+that the agent listing did not carry, and nine sessions were addressable there
+with no roster row at all. Those nine were driving through Remote Control, which
+writes no local process record.
+
+Where the caller named nobody at all, the calling role's own `## The channel`
+section carries the last rung, since a worker and a planner infer differently
+and a roleless caller has no ladder to defer to. Ask the operator where one is
+present, put the candidate rows through the structured question surface so they
+pick a row rather than recall a name, and say the addressee was inferred
+wherever an inference decided it.
+
+## Step 3: send
+
+- A message-sending tool exists: send through it, addressed to what Step 2 resolved. This is the ordinary route.
+- No message-sending tool, or Step 2 found no row to address: compose the block below and close the turn with nothing after it, so the block is the whole of what an operator copies.
+
+Send the block out as a message before it becomes an interactive prompt. A
+session already waiting on input never reaches the tool round that drains an
+inbound message, so an answer relayed afterwards arrives under the open question
+and changes nothing. This holds on both routes.
+
+The shipped channel rule states the same thing for a session holding neither
+role, so the restatement here is for the target that installed the plugin and
+not governance, where that rule never arrives. A session that does load it reads
+the rule and this body in agreement rather than one of them alone.
+
+Carry the message body verbatim from whatever names it. This skill composes and
+never drafts, so a pull request announcement, an address-review announcement, or
+a blocked question is exactly the text the calling bullet or the dispatch
+states, with its own facts filled in.
 
 ## Header
 
@@ -30,8 +95,12 @@ Relay: from <sender> to <addressee>, <what the message is>
 <message body>
 ```
 
-States a default rather than a fixed vocabulary. A session may write the header in its own words, since it exists to be read once and copied rather than parsed by anything downstream. Name the same three parts however phrased.
+States a default rather than a fixed vocabulary. A session may write the header
+in its own words, since it exists to be read once and copied rather than parsed
+by anything downstream. Name the same three parts however phrased.
 
 ## Output
 
-Nothing beyond the composed block. Report the Guards refusal instead when the roster cannot answer for the sender, and report the calling body's own halt or inference when its ladder cannot resolve the addressee.
+The sent message, or the composed block and nothing beyond it. Report Step 1's
+refusal in place of a sender the roster cannot answer for, and report the halt
+or the inference in place of an addressee Step 2 cannot resolve.

package/docs/agents/tasks.md

@@ -54,6 +54,8 @@ An outcome whose body is struck reads as cut rather than open or closed, whateve
 
 The task carries its plan with it. When the closing task is the last live one whose `Plan:` line resolves onto that file, the plan moves to `.canon/plans/archive/` under its own name and the archived task's line is rewritten as `Plan: [feature-<slug>](../../plans/archive/feature-<slug>.md)`, a folder deeper than the live task wrote it. The `plan` field on the success record carries that `from` and `to`, and is `null` when nothing moved.
 
+Every other relative link in the task is re-resolved for the deeper folder too, whether its target moved or not: `Groundwork:`, `Intake:`, a `Plan:` or `Ready:` line whose target stayed put, and a link in the body. Fenced blocks, inline code spans, absolute URLs, `#` anchors, and rooted paths are left alone. `canon tasks decline` applies the same rebase, since `declined/` sits at the same depth. The rebase runs before the plan and ready retargets, so a moved plan keeps its own line.
+
 The ready folder the task's `Ready:` line names moves with the plan to `.canon/ready/archive/`, falling back to a `.canon/ready/<nn>-<slug>/` path in the plan when the line is absent. The `Ready:` line and the plan's literal path to the folder are retargeted, and the `ready` field on the success record carries `from` and `to`, or `null` when nothing moved. A folder that resolves to nothing, sits already archived, or meets a taken destination moves nothing and refuses nothing.
 
 A plan several tasks share stays where it is, and its ready folder with it, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.
@@ -325,22 +327,24 @@ canon tasks validate
 canon tasks validate --json
 ```
 
-Seven checks run. Plan and Collisions reach one half each of the `## Run now` test the board standard states. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
+Seven checks run. Collisions reaches one half of the `## Run now` test the board standard states, and Plan reaches every group, reading the Plan column under `## Run now` and the task file's own line under the other two. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
 
-| Check      | What it reports                                                                                                         |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed    |
-| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line        |
-| Mapping    | A row or backlog line naming no task file                                                                               |
-| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                             |
-| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
-| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                       |
-| Blockers   | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined     |
+| Check      | What it reports                                                                                                                                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed                                                                                                 |
+| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line, a `## Needs a plan` row whose task cites a live plan, or an `## Up next` row whose task cites none |
+| Mapping    | A row or backlog line naming no task file                                                                                                                                                                            |
+| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                                                                                                                          |
+| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all                                                                                              |
+| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                                                                                                                    |
+| Blockers   | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined                                                                                                  |
 
 Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
 
 The Plan check reads the row and the task file both, because the two are written by different hands and only the task's own `Plan:` line reaches the archive. A row carrying a plan whose task states none is `plan-uncited`, and a pair naming two different plans is `plan-mismatched`. Both sides resolve against the board and against the project root before they compare, so a row writing `../plans/x.md` and a task writing `.canon/plans/x.md` name one file rather than two.
 
+The other two groups have no Plan column, so the same check reads the task file's own `Plan:` line against what the group name claims. A `## Needs a plan` row whose task cites a plan that sits live on disk is `plan-parked`, since the group says no such plan exists and the row is either misplaced or its plan is stale and belongs in the archive. An `## Up next` row whose task cites no live plan is `plan-absent`, since that group says one is written. A plan already archived, or a cited path with no file behind it, reads as not live on both sides. A row whose task file is gone is left to `task-unresolved`. An `## Up next` row with nothing left to build, waiting on an act only a person can take, reports `plan-absent` once its plan archives while the task stays live. That report is expected, since the check reads the task file and not the `Waiting on` prose, so a row in that state moves to `## Needs a plan` or closes.
+
 Mapping spans two surfaces, because a task sits on `priority.md` when it would plausibly be planned soon and on `backlog.md` otherwise. A row or a backlog line naming no task file is `task-unresolved`, and a file both surfaces name is `row-duplicated` for the reason a task in two groups is: it claims two things about itself and only one can hold. A task file neither surface names is `unplaced` rather than a finding, since that is the normal state between a session filing it and a live orchestrator placing it on the board. One check across both is what lets a task move between them without the move reading as a dropped file.
 
 A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name still lands in the `unplaced` array below rather than the findings. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.

package/docs/workflow/ai-workflow.md

@@ -272,15 +272,15 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Run several tracks at once
 
-| Skill                     | When to use                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------- |
-| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR  |
-| `canon:role-planner`      | To assert the planner role for a cold session writing one plan under one task   |
-| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan |
-| `canon:session-relay`     | When a worker or planner owes its controller a message and holds no send tool   |
-| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                  |
-| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board  |
-| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff       |
+| Skill                     | When to use                                                                                          |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                       |
+| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass |
+| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                      |
+| `canon:session-relay`     | When this session owes another session a message, with or without a role                             |
+| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                       |
+| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board                       |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                            |
 
 ### Keep the project current with the toolkit
 

package/docs/workflow/visual-design-workflow.md

@@ -42,7 +42,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
 - `canon:ux-walkthrough` for a multi-finding inspection pass over a running app with the operator, drafting arms from the app's own markup and recording each pick for a builder
-- `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
+- `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/governance/rules/ui/410-a11y.md

@@ -55,3 +55,8 @@ paths:
 - Alt text for functional images (icons, buttons) should describe the action, not the graphic.
 - Give the visual boundary of a control and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG Non-text Contrast, 1.4.11).
 - Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG Use of Color, 1.4.1).
+
+## Reflow
+
+- Let content reflow at a viewport 320 CSS pixels wide with no loss of content or function and no two-dimensional scrolling. Only content whose meaning depends on both axes, such as a data table, a map, or a diagram, may scroll sideways (WCAG Reflow, 1.4.10, Level AA).
+- Treat 320 as the criterion's own test condition rather than a device width. It is equivalent to a 1280 pixel window at 400 percent zoom, so a layout that breaks there breaks for a person who zooms.

package/governance/rules/ui/440-surface-capture.md

@@ -25,7 +25,13 @@ paths:
 
 ## What a capture covers
 
-- Capture the full page at the viewport its case declares. Do not capture a component in isolation.
+- Capture the full page. Do not capture a component in isolation.
+- Declare the widths a layout case captures. Always include 320, the reflow floor from the reflow criterion in `410-a11y`, then add each breakpoint bucket the project writes rules for, read from the `## Layout` section of `DESIGN.md`.
+- Fall back to the 320 floor alone when the project has no `DESIGN.md` or its record carries no `## Layout` section. Do not impose another project's breakpoints.
+- Apply the declaration to a case that covers layout only. A case driving a menu open or an answer chosen tests a state, so it takes one width rather than the full set.
+- Read a capture at 320 as proof that a frame was taken there, not that the page reflows correctly. The criterion is stated in `410-a11y` and nothing here enforces it.
+- Write the capture into a folder named `evidence`. The image is collected for the pull request comment when any segment of its path is literally `evidence` and its filename carries an image extension, so the folder name is fixed and its position in the tree is the project's own.
+- Several `evidence/` folders in one project is the ordinary shape rather than a problem to consolidate. One per surface is how a project with more than one rendered surface ends up.
 - Drive a state a screenshot cannot reach. An initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling.
 - Add a case to the capture record when adding a surface.
 - Remove a surface's case in the change that removes the surface.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.104.0",
+  "version": "4.106.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -155,7 +155,7 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt:
-      'I owe my controller the pull request announcement but I have no message-sending tool. Compose the relay so an operator can copy it over.',
+      'Relay this over to the session that dispatched me. It gave me a sessionId rather than a name, so work out who that is and send it.',
     expect: 'session-relay',
   },
 

package/src/commands/tasks.ts

@@ -218,6 +218,7 @@ export function register(program: Command): void {
         '',
         'Checks:',
         '  every Run now row points at a plan file that resolves',
+        '  no Needs a plan row has a live plan, and every Up next row has one',
         '  every task file carries a board row or a backlog line, never both',
         '  no task carries more than one row',
         '  no two Run now rows touch the same file',

package/src/design/document.ts

@@ -134,6 +134,8 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
       ),
     ),
     '',
+    section('Layout', tokens.layout),
+    '',
     section('Motion', tokens.motion),
     '',
     section('Iconography', tokens.iconography),

package/src/design/tokens.ts

@@ -70,6 +70,7 @@ export interface DesignTokens {
   readonly spacingNote: string
   readonly borders: readonly BorderToken[]
   readonly bordersNote: string
+  readonly layout: string
   readonly motion: string
   readonly iconography: string
   readonly preamble: string
@@ -371,6 +372,9 @@ export const TOKENS: DesignTokens = {
     },
   ],
 
+  layout:
+    'Capture widths are 320, 768, 1280 and 1536 pixels, declared once in `tooling/web/configs/e2e/screenshot.ts`, with 320 and 1280 committed as evidence. 320 is the reflow floor and the rest are the breakpoint buckets. The landing page under `web/` sets its own `max-width` media queries between 430 and 1100 pixels per component rather than from a shared scale.',
+
   motion:
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
 

package/src/gate/measures.ts

@@ -818,9 +818,17 @@ export const readmeCitations: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Globs `pr-visual-checks.yml` carries with no `deploy-site.yml` counterpart,
+ * because the path changes no byte of the built site. The capture harness is
+ * the one case: a change there should report the capture job and never deploy.
+ */
+const VISUAL_ONLY_GLOBS: readonly string[] = ['tooling/web/configs/e2e/**']
+
 /**
  * `deploy-site.yml` and `pr-visual-checks.yml` each carry their own literal
- * copy of the eight path globs a landing-page change should trigger on, per
+ * copy of the eight path globs a landing-page change should trigger on, plus
+ * the `VISUAL_ONLY_GLOBS` the visual workflow adds for itself, per
  * Question 2 in `.canon/plans/archive/feature-render-visibility.md`. A YAML
  * anchor cannot cross files here, so the two copies are read live and compared
  * rather than one asserting a literal the other could drift behind unnoticed,
@@ -858,14 +866,25 @@ export const visualPathGlobs: Measure = async (ctx) => {
     }
   }
 
-  const onlyDeploy = deployPaths.filter((path) => !visualPaths.includes(path))
-  const onlyVisual = visualPaths.filter((path) => !deployPaths.includes(path))
+  const onlyDeploy = deployPaths.filter(
+    (path) => !visualPaths.includes(path) || VISUAL_ONLY_GLOBS.includes(path),
+  )
+  const onlyVisual = visualPaths.filter(
+    (path) => !deployPaths.includes(path) && !VISUAL_ONLY_GLOBS.includes(path),
+  )
+  const declaredVisualOnly = visualPaths.filter((path) =>
+    VISUAL_ONLY_GLOBS.includes(path),
+  )
 
   if (onlyDeploy.length === 0 && onlyVisual.length === 0) {
+    const visualOnlyNote =
+      declaredVisualOnly.length > 0
+        ? `, plus visual-only ${declaredVisualOnly.join(', ')}`
+        : ''
     return {
       emissions: [
         info(
-          `${deployPaths.length} path glob(s) agree between ${deployPath} and ${visualPath}`,
+          `${deployPaths.length} path glob(s) agree between ${deployPath} and ${visualPath}${visualOnlyNote}`,
         ),
       ],
     }
@@ -874,7 +893,11 @@ export const visualPathGlobs: Measure = async (ctx) => {
   return {
     emissions: [
       ...onlyDeploy.map((path) =>
-        warn(`${deployPath} carries ${path}, absent from ${visualPath}`),
+        warn(
+          VISUAL_ONLY_GLOBS.includes(path)
+            ? `${deployPath} carries ${path}, which is visual-only and must not trigger a deploy`
+            : `${deployPath} carries ${path}, absent from ${visualPath}`,
+        ),
       ),
       ...onlyVisual.map((path) =>
         warn(`${visualPath} carries ${path}, absent from ${deployPath}`),

package/src/tasks/archive.ts

@@ -792,15 +792,16 @@ export async function archiveTask(
 
   await mkdir(destination, { recursive: true })
   await rename(from, to)
-  if (plan) {
-    const retargeted = retargetPlanLine(text, linkTo(destination, plan.to))
-    await writeFile(
-      to,
-      ready
-        ? retargetReadyLine(retargeted, `${linkTo(destination, ready.to)}/`)
-        : retargeted,
-    )
-  }
+  const rebased = rebaseRelativeLinks(text, dir, destination)
+  const retargeted = plan
+    ? retargetPlanLine(rebased, linkTo(destination, plan.to))
+    : rebased
+  await writeFile(
+    to,
+    ready
+      ? retargetReadyLine(retargeted, `${linkTo(destination, ready.to)}/`)
+      : retargeted,
+  )
 
   const priorityRowRemoved = await clearPriorityRow(dir, stem)
   const regen = await regenOne(dir, { dryRun: false })
@@ -918,6 +919,69 @@ export function linkTo(taskDir: string, plan: string): string {
   return relative(taskDir, plan).split(sep).join('/')
 }
 
+const MARKDOWN_LINK_PATTERN = /(\]\()([^)\s]+)/g
+/** The capture group makes `split` keep each code span, at the odd positions. */
+const INLINE_CODE_PATTERN = /(`+[^`]*`+)/
+const BARE_ORIGIN_PATTERN =
+  /^((?:Plan|Ready|Groundwork|Intake):[ \t]*)([^\s[\]()]+)[ \t]*$/
+
+function isRelativeTarget(target: string): boolean {
+  return !/^(?:[a-z][a-z0-9+.-]*:|\/|#)/i.test(target)
+}
+
+function rebaseTarget(target: string, fromDir: string, toDir: string): string {
+  if (!isRelativeTarget(target)) return target
+
+  const suffixAt = target.search(/[#?]/)
+  const path = suffixAt === -1 ? target : target.slice(0, suffixAt)
+  const suffix = suffixAt === -1 ? '' : target.slice(suffixAt)
+  if (path === '') return target
+
+  const rebased = relative(toDir, resolve(fromDir, path)).split(sep).join('/')
+  const slash = path.endsWith('/') ? '/' : ''
+
+  return `${rebased}${slash}${suffix}`
+}
+
+/**
+ * Re-resolves every relative link in a task written for `fromDir` so it reads
+ * the same target from `toDir`. Every link rather than the four origin lines,
+ * since the body breaks one folder short the same way. Fenced samples stay
+ * verbatim, and a URL, an anchor, or a rooted path names nothing depth changes.
+ */
+export function rebaseRelativeLinks(
+  text: string,
+  fromDir: string,
+  toDir: string,
+): string {
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+
+  return lines
+    .map((line, index) => {
+      if (fenced[index]) return line
+
+      const bare = BARE_ORIGIN_PATTERN.exec(line)
+      if (bare?.[2].includes('/')) {
+        return `${bare[1]}${rebaseTarget(bare[2], fromDir, toDir)}`
+      }
+
+      return line
+        .split(INLINE_CODE_PATTERN)
+        .map((part, position) =>
+          position % 2 === 1
+            ? part
+            : part.replace(
+                MARKDOWN_LINK_PATTERN,
+                (_whole: string, open: string, target: string) =>
+                  `${open}${rebaseTarget(target, fromDir, toDir)}`,
+              ),
+        )
+        .join('')
+    })
+    .join('\n')
+}
+
 async function clearPriorityRow(dir: string, stem: string): Promise<boolean> {
   const path = join(dir, 'priority.md')
   if (!existsSync(path)) return false
@@ -984,7 +1048,10 @@ export async function declineTask(
   await rename(from, to)
 
   const date = new Date().toISOString().slice(0, 10)
-  const declined = insertDeclinedLine(text, declineLine(reason, by, date))
+  const declined = insertDeclinedLine(
+    rebaseRelativeLinks(text, dir, destination),
+    declineLine(reason, by, date),
+  )
   const final = plan
     ? retargetPlanLine(declined, linkTo(destination, plan.to))
     : declined

package/src/tasks/validate.ts

@@ -8,6 +8,7 @@ import {
   readOutcomes,
   readPlanTarget,
   readPullRequest,
+  resolveLivePlan,
   tasksDir,
 } from '@/tasks/archive'
 import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
@@ -38,6 +39,8 @@ export const FINDING_KINDS = [
   'plan-unresolved',
   'plan-uncited',
   'plan-mismatched',
+  'plan-parked',
+  'plan-absent',
   'task-unresolved',
   'row-duplicated',
   'row-misshapen',
@@ -747,6 +750,70 @@ async function planDisagreement(
   }
 }
 
+/**
+ * Tests the claim a group name makes about a plan. `## Needs a plan` says none
+ * is live and `## Up next` says one is written, and neither group has a `Plan`
+ * column, so the task file's own `Plan:` line is the only place either claim
+ * can be read against.
+ *
+ * A live plan is one the archive's resolution accepts and the disk holds, so a
+ * plan already archived reads as not live and a cited path with no file behind
+ * it reads the same way. A row whose task file is gone is left to
+ * `task-unresolved`, which owns that report.
+ */
+async function checkGroupClaims(
+  rows: readonly BoardRow[],
+  dir: string,
+  root: string,
+): Promise<Finding[]> {
+  const parked = rows.filter(
+    (row) => row.group === 'Needs a plan' || row.group === 'Up next',
+  )
+
+  const found = await Promise.all(
+    parked.map(async (row) => groupClaimFinding(row, dir, root)),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
+async function groupClaimFinding(
+  row: BoardRow,
+  dir: string,
+  root: string,
+): Promise<Finding | undefined> {
+  if (!row.stem) return undefined
+
+  const file = join(dir, `${row.stem}.md`)
+  if (!existsSync(file)) return undefined
+
+  const target = readPlanTarget(await readFile(file, 'utf8'))
+  const live = target ? resolveLivePlan(target, dir, root) : undefined
+  const hasLivePlan = live !== undefined && existsSync(live)
+
+  if (row.group === 'Needs a plan' && hasLivePlan) {
+    return {
+      kind: 'plan-parked',
+      group: row.group,
+      subject: row.stem,
+      message: `sits under ${row.group} and its task cites ${target}, a live plan. A row with a plan belongs under Up next or Run now, or the plan is stale and belongs in the archive.`,
+    }
+  }
+
+  if (row.group === 'Up next' && !hasLivePlan) {
+    return {
+      kind: 'plan-absent',
+      group: row.group,
+      subject: row.stem,
+      message: target
+        ? `sits under ${row.group}, which claims a written plan, and its task cites ${target}, which is not a live plan.`
+        : `sits under ${row.group}, which claims a written plan, and its task carries no Plan: line.`,
+    }
+  }
+
+  return undefined
+}
+
 /**
  * Where a plan pointer lands, resolved against the board and against the
  * project root the way the archive resolves the same line. Neither base
@@ -1186,6 +1253,7 @@ export async function validateBoard(
     ...checkMapping(rows, backlog, dir),
     ...checkPlans(rows, dir, root),
     ...(await checkPlanAgreement(rows, dir, root)),
+    ...(await checkGroupClaims(rows, dir, root)),
     ...checkCollisions(rows),
     ...checkOrdering(rows),
     ...parked.findings,

package/standards/design.md

@@ -51,7 +51,7 @@ Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `
 
 Add either optional section when the project has content for it:
 
-- `## Layout`: page width, breakpoints, and grid rules, as current constraints
+- `## Layout`: page width, breakpoints, and grid rules, as current constraints. The surface-capture rule reads the breakpoints from here, so a project with none declared here is captured at the 320 reflow floor alone.
 - `## Mark`: the logo's construction rules and the files that carry it
 
 ## Template