@lyupro/codex-bridge 0.6.14 → 0.6.16

package/src/home/lib/order-rules/header-grants.mjs

@@ -0,0 +1,175 @@
+/** Plan_79 D4: owns rules for the grant labels of the task header: continue, retry and advice. */
+export const RULES = Object.freeze({
+  'grant-label-exclusive': Object.freeze({
+    data: Object.freeze([]),
+    topic: 'order',
+    rule: 'Keep exactly one grant label: continue and retry cannot both appear, even with invalid values.',
+    message: () => 'continue and retry cannot both be present; keep exactly one grant label',
+  }),
+  'advice-value-shape': Object.freeze({
+    data: Object.freeze([]),
+    topic: 'order',
+    rule: 'Give advice a non-empty single-line value in the task header.',
+    message: () => 'advice value must be non-empty and single line',
+  }),
+  'grant-value-shape': Object.freeze({
+    data: Object.freeze([]),
+    topic: 'order',
+    rule: 'Give continue or retry a bare run folder other than . or .. and a non-placeholder reason, ' +
+      'separated by an em dash, hyphen or colon.',
+    message: () => 'grant must name a bare run folder (not . or ..) and a non-placeholder reason',
+  }),
+  'continuation-grant-usable': Object.freeze({
+    data: Object.freeze(['violation', 'labelName', 'run', 'runsRoot', 'lastRun', 'orderId', 'spent', 'previous', 'example']),
+    topic: 'order',
+    rule: 'Grant continue to an existing last run of the task chain only when this order has not spent its ' +
+      'one continuation and its previous pass has a finished verdict with no running worker; ' +
+      'ask the orchestrator for the run and reason, and use a new order id for any further pass.',
+    message: ({ violation, labelName, run, runsRoot, lastRun, orderId, spent, previous, example, hints }) => {
+      if (violation === 'missing-folder' || violation === 'not-last') {
+        const repair = `Example: \`continue: ${example}\`. ` +
+          'Action: ask the orchestrator for an explicit grant naming the run and reason; ' +
+          'do not invent or reuse a continuation.';
+        if (violation === 'missing-folder') {
+          return `${labelName} is refused: the orchestrator named run “${run}”, but it does not ` +
+            `exist as a run folder in this project's runs directory ${runsRoot}. ` +
+            `${hints} ${repair} The submitted grant was not rewritten.`;
+        }
+        return `${labelName} is refused: grant ${run} is not the LAST run of this task's chain; ` +
+          `the current last run is ${lastRun}. A continuation is single-use: continuing the ` +
+          'last run appends a later run, so the old grant stops matching by itself — no counter or new ' +
+          `state is used. ${hints} ${repair}`;
+      }
+      if (violation === 'spent') {
+        return `${labelName} is refused: order “${orderId}” already spent its allowed continuation on ${spent}. ` +
+          `${hints} A further pass needs a new order id from the orchestrator.`;
+      }
+      if (violation === 'unfinished') {
+        return `${labelName} is refused: previous run ${previous} has no finished verdict and may still ` +
+          `be editing the worktree. Repeat without ${labelName} to attach to it. ${hints}`;
+      }
+      throw new Error(`unknown continuation-grant-usable violation: ${violation}`);
+    },
+  }),
+  'retry-grant-usable': Object.freeze({
+    data: Object.freeze(['violation', 'run', 'runsRoot', 'previousOrder', 'orderId', 'labelName']),
+    topic: 'order',
+    rule: 'Grant retry to a bare existing last run of the task chain under its own recorded order id, ' +
+      'only after a non-OK finished verdict and after its worker has stopped; retry repeats that pass, ' +
+      'while continue grants the next pass.',
+    message: ({ violation, run, runsRoot, previousOrder, orderId, labelName }) => {
+      if (violation === 'missing-folder') {
+        return `Retry is refused: ${run} is not a bare existing run folder in ${runsRoot}.`;
+      }
+      if (violation === 'not-last') {
+        return `Retry is refused: grant ${run} is not the LAST run of this task's chain; a retry is single-use.`;
+      }
+      if (violation === 'order-mismatch') {
+        return `Retry is refused: run ${run} order_id ${previousOrder} differs from order ${orderId}. ` +
+          'A retry repeats its own order; a run without order_id predates orders — start a new order.';
+      }
+      if (violation === 'unfinished') {
+        return `Retry is refused: run ${run} has no finished verdict or its worker may still be alive and writing. ` +
+          `Repeat without ${labelName} to attach to it.`;
+      }
+      if (violation === 'ended-ok') {
+        return `Retry is refused: run ${run} ended OK. A retry repeats a failed pass; use continue: for the next pass.`;
+      }
+      throw new Error(`unknown retry-grant-usable violation: ${violation}`);
+    },
+  }),
+  'ready-grant-line': Object.freeze({
+    data: Object.freeze(['variant', 'run', 'reason', 'orderId']),
+    topic: 'order',
+    rule: 'Write a ready continue grant with the latest run and the orchestrator\'s reason, or a retry grant ' +
+      'with that failed pass\'s recorded reason and order id; without a run there is no ready grant.',
+    message: ({ variant, run, reason, orderId }) => {
+      if (variant === 'none') return 'Ready grant line: none (there is no run to continue).';
+      if (variant === 'continue') return `Ready grant line: continue: ${run} — ${reason}.`;
+      if (variant === 'retry') {
+        return `Ready retry line: retry: ${run} — ${reason} (repeats that pass under order ${orderId}).`;
+      }
+      throw new Error(`unknown ready-grant-line variant: ${variant}`);
+    },
+  }),
+  'grant-last-run-hint': Object.freeze({
+    data: Object.freeze(['variant', 'run', 'status', 'reason']),
+    topic: 'order',
+    rule: 'Use the latest recorded run and its outcome when repairing a continue or retry header grant.',
+    message: ({ variant, run, status, reason }) => {
+      if (variant === 'none') return 'Last run: none. Outcome: none.';
+      if (variant === 'last') return `Last run: ${run}. Outcome: ${status} — ${reason}.`;
+      throw new Error(`unknown grant-last-run-hint variant: ${variant}`);
+    },
+  }),
+  'advisor-scope-continuation': Object.freeze({
+    data: Object.freeze(['phaseLabel', 'continueLabel']),
+    topic: 'order',
+    rule: 'Never continue an advisor scope pass; repeat failed scope with retry, or use a new order id without continue.',
+    message: ({ phaseLabel, continueLabel }) =>
+      `codex-advisor ${phaseLabel} scope refuses ${continueLabel}: a scope pass is never continued, and continuing one ` +
+      "spends the order's single continuation that its advise phase needs. Action: repeat the scope under a new order id " +
+      `without ${continueLabel} and without a continue: grant, then run advise as that order's continuation; a ` +
+      'scope run that failed is repeated with a `retry:` grant instead.',
+  }),
+  'retry-pass-identity': Object.freeze({
+    data: Object.freeze(['agent', 'phase']),
+    topic: 'order',
+    rule: 'Retry the named run with its own agent and phase.',
+    message: ({ agent, phase }) => `a retry repeats the named run's own agent and phase: ${agent}/${phase}.`,
+  }),
+  'repeat-task-grant-required': Object.freeze({
+    data: Object.freeze(['violation', 'continueLabel', 'slugLabel', 'slug', 'count', 'latest']),
+    topic: 'order',
+    rule: 'Ask the orchestrator for a continue grant before repeating an existing task, even under a different slug.',
+    message: ({ violation, continueLabel, slugLabel, slug, count, latest, hints }) => {
+      let previous;
+      if (violation === 'renamed') previous = `this task already ran in this repository under the name “${slug}”`;
+      else if (violation === 'existing') previous = `runs for task “${slug}” already exist in this repository`;
+      else throw new Error(`unknown repeat-task-grant-required violation: ${violation}`);
+      return `${continueLabel} is required: ${previous} (${count}), latest: ${latest}. ` +
+        'A repeat run is allowed, but the orchestrator decides, not the runner: it read the ' +
+        `previous response and knows whether work remains. Add ${continueLabel} if you are finishing ` +
+        `the same task; changing ${slugLabel} with the same task text does not stop it being a repeat. ${hints}`;
+    },
+  }),
+  'advisor-advise-continuation': Object.freeze({
+    data: Object.freeze(['phaseLabel', 'continueLabel']),
+    topic: 'order',
+    rule: 'Grant advise as the continuation of the scope run of the same order so it can settle the predicted risks.',
+    message: ({ phaseLabel, continueLabel }) =>
+      `codex-advisor ${phaseLabel} advise requires a ${continueLabel} grant naming the scope run: phase 2 continues the scope run of the same order ` +
+      'so it can settle the risks phase 1 predicted.',
+  }),
+  'build-advice-required': Object.freeze({
+    data: Object.freeze([]),
+    topic: 'order',
+    rule: 'Start a build order with advice naming an OK advisor advise run, or mechanical, revert, docs-only or test-only work without design choices.',
+    message: () => 'codex-build requires the task file to start with the header line `advice: <value>`, where the ' +
+      'value is mechanical | revert | docs-only | test-only ' +
+      'or an absolute path to an existing advisor run directory whose meta.json says agent codex-advisor, ' +
+      'phase advise, status OK. ' +
+      'An order that invents a construction needs a second opinion first; only work with no design choice may skip it.',
+  }),
+  'advise-scope-run-required': Object.freeze({
+    data: Object.freeze(['violation']),
+    topic: 'order',
+    rule: 'Name an OK codex-advisor scope run in the continue grant for advise.',
+    message: ({ violation, failed }) => {
+      if (violation === 'agent') return "agent must be 'codex-advisor'";
+      if (violation === 'phase') return "phase must be 'scope'";
+      if (violation === 'status') return "status must be 'OK'";
+      if (violation === 'meta') return `continued run meta.json failed ${failed}.`;
+      throw new Error(`unknown advise-scope-run-required violation: ${violation}`);
+    },
+  }),
+  'advice-retired-root': Object.freeze({
+    data: Object.freeze(['candidate', 'retiredRoot', 'destination', 'equivalent']),
+    topic: 'order',
+    rule: 'When advice points under a retired runs root, update advice to the equivalent path ' +
+      'under the current destination or pass that path explicitly; retired paths are never silently remapped.',
+    message: ({ retiredRoot, destination, equivalent }) =>
+      `Run records moved from ${retiredRoot} to ${destination}. Equivalent path: ${equivalent}. ` +
+      'Update advice: or pass this new path explicitly. No path was remapped.',
+  }),
+});

package/src/home/lib/order-rules/header.mjs

@@ -0,0 +1,206 @@
+/** Plan_79 D4: owns rules for values and placement of task-header labels. */
+export const RULES = Object.freeze({
+  'order-header-label-shape': Object.freeze({
+    data: Object.freeze(['label', 'violation']),
+    topic: 'order',
+    rule: 'Write header labels at column one with their exact spelling and a non-empty value.',
+    message: ({ label, violation }) => {
+      if (violation === 'empty') return `header label "${label}" has an empty value`;
+      if (violation === 'spelling') return `write the header label exactly as "${label}:"`;
+      throw new Error(`unknown order-header-label-shape violation: ${violation}`);
+    },
+  }),
+  'unknown-header-label': Object.freeze({
+    data: Object.freeze(['label', 'knownLabels']),
+    topic: 'order',
+    rule: 'Use only known header labels; an unknown lowercase label after a header line is refused.',
+    message: ({ label, knownLabels }) =>
+      `unknown header label "${label}"; known labels: ${knownLabels.join(', ')}`,
+  }),
+  'duplicate-order-label': Object.freeze({
+    data: Object.freeze(['label']),
+    topic: 'order',
+    rule: 'Write each header label at most once, even when the repeated values are identical.',
+    message: ({ label }) => `duplicate ${label} label`,
+  }),
+  'header-metadata-placement': Object.freeze({
+    data: Object.freeze(['label', 'violation']),
+    topic: 'order',
+    rule: 'Put grants and advice only in the header at the top of the task file, with a non-empty value; ' +
+      'quote examples with > or reword them inside a sentence, including examples in code fences.',
+    message: ({ label, violation }) => {
+      const repairHint = `move it into the header at the top of the file, spelled ${label}: <value>; ` +
+        'if it is an example, quote it with > or reword it inside a sentence';
+      if (violation === 'misplaced') return `misplaced ${label} metadata; ${repairHint}`;
+      if (violation === 'empty') return `${label} value must be non-empty and single line; ${repairHint}`;
+      throw new Error(`unknown header-metadata-placement violation: ${violation}`);
+    },
+  }),
+  'effort-value': Object.freeze({
+    data: Object.freeze(['value']),
+    topic: 'order',
+    rule: 'When effort is present, use a non-empty single word with no whitespace.',
+    message: ({ value }) =>
+      `must be a non-empty single word with no whitespace; got ${JSON.stringify(value)}`,
+  }),
+  'run-slug': Object.freeze({
+    data: Object.freeze(['value']),
+    topic: 'order',
+    rule: 'The slug, or order id when slug is absent or empty, must contain a letter or digit ' +
+      'after replacing characters outside A-Z, a-z, 0-9, dot, underscore and hyphen with hyphens.',
+    message: ({ value }) =>
+      `produces an unusable run folder name after sanitization: ${JSON.stringify(value)} must contain a letter or digit.`,
+  }),
+  'repository-path': Object.freeze({
+    data: Object.freeze(['violation', 'value', 'segment', 'context', 'label']),
+    topic: 'order',
+    rule: 'When repository is present, use an absolute path to an existing directory; ' +
+      'no path segment other than . or .. may end in a dot or a space, which Windows strips.',
+    message: ({ violation, value, segment, context, label, reason }) => {
+      if (context === 'task-input') {
+        return `${label} ${reason}\nThe run folder was not created; quota was not spent.`;
+      }
+      if (context !== undefined) throw new Error(`unknown repository-path context: ${context}`);
+      if (violation === 'relative') {
+        return `must be an absolute path to the repository; got ${JSON.stringify(value)}.`;
+      }
+      if (violation === 'altered-segment') {
+        return `has a path segment ending in a dot or a space (${JSON.stringify(segment)}), which Windows strips; ` +
+          `got ${JSON.stringify(value)}.`;
+      }
+      if (violation === 'not-directory') {
+        return `must name an existing directory; ${JSON.stringify(value)} is not one.`;
+      }
+      throw new Error(`unknown repository-path violation: ${violation}`);
+    },
+  }),
+  'agent-accepted-labels': Object.freeze({
+    data: Object.freeze(['label', 'agent']),
+    topic: 'order',
+    rule: 'Use only the header labels accepted by the agent assigned to this order.',
+    message: ({ label, agent }) => `label "${label}" is not accepted by ${agent}`,
+  }),
+  'order-value-placeholder': Object.freeze({
+    data: Object.freeze(['label']),
+    topic: 'order',
+    rule: 'Replace placeholder header values with the actual values assigned to this order.',
+    message: ({ label }) => `label "${label}" is still a placeholder`,
+  }),
+  'header-shell-safety': Object.freeze({
+    data: Object.freeze(['labelName', 'sequence']),
+    topic: 'order',
+    rule: 'Keep header values short and free of forbidden shell sequences; put free text in the task file body.',
+    message: ({ labelName, sequence }) =>
+      `${labelName} contains forbidden shell sequence ${JSON.stringify(sequence)}; ` +
+      'put free text in the task file body and keep header values short',
+  }),
+  'build-existing-scope-required': Object.freeze({
+    data: Object.freeze(['labelName', 'newLabelName']),
+    topic: 'order',
+    rule: 'For codex-build, declare at least one existing path pattern in scope; scope new does not replace it.',
+    message: ({ labelName, newLabelName }) =>
+      `${labelName} is required for codex-build: declare at least one existing path pattern; ` +
+      `${newLabelName} does not replace it.`,
+  }),
+  'required-order-labels': Object.freeze({
+    data: Object.freeze(['label', 'example']),
+    topic: 'order',
+    rule: 'Include every required header label for the assigned agent, using its example as a guide.',
+    message: ({ label, example }) =>
+      `missing required header label "${label}:"; example: ${label}: ${example}`,
+  }),
+  'scope-pattern-shape': Object.freeze({
+    data: Object.freeze(['violation', 'part', 'pattern']),
+    topic: 'order',
+    rule: 'Write scope and scope new as repository-relative file patterns with forward slashes, ' +
+      'no line breaks, parent-directory segments or service directories; name a file or use a glob for a directory.',
+    message: ({ violation, part, pattern }) => {
+      if (part !== 'reason' && part !== 'action') throw new Error(`unknown scope-pattern-shape part: ${part}`);
+      if (violation === 'line-break') return part === 'reason'
+        ? 'contains a newline or carriage return'
+        : 'use a glob instead of a literal path containing a line break';
+      if (violation === 'absolute') return part === 'reason'
+        ? 'is an absolute or drive-qualified path'
+        : 'use a path relative to the repository root with forward slashes';
+      if (violation === 'backslash') return part === 'reason'
+        ? 'uses backslash separators'
+        : 'replace backslashes with forward slashes';
+      if (violation === 'parent-directory') return part === 'reason'
+        ? 'contains a parent-directory (..) segment'
+        : 'remove the .. segment and keep the path relative to the repository root';
+      if (violation === 'service-directory') return part === 'reason'
+        ? 'lies inside a service directory that no scope can authorise'
+        : 'name the file outside the service directory, or make that edit yourself';
+      if (violation === 'directory' || violation === 'new-directory') {
+        if (part === 'reason') return 'names a directory rather than a file';
+        if (violation === 'directory') {
+          return `write ${pattern.replace(/\/$/, '')}/** for everything inside it, or name the file itself`;
+        }
+        return `write ${pattern}/** if it is a directory, or declare the new file by its own name with an extension; a new extensionless file is declared through its directory`;
+      }
+      throw new Error(`unknown scope-pattern-shape violation: ${violation}`);
+    },
+  }),
+  'scope-pattern-match': Object.freeze({
+    data: Object.freeze(['violation', 'part', 'repoRoot', 'labelName', 'message']),
+    topic: 'order',
+    rule: 'Each ordinary scope pattern must parse and match an existing repository path; ' +
+      'start from the git repository root, use UTF-8 file names, and declare intentionally new paths with scope new.',
+    message: ({ violation, part, repoRoot, labelName, message }) => {
+      if (part !== 'reason' && part !== 'action') throw new Error(`unknown scope-pattern-match part: ${part}`);
+      if (violation === 'missing') return part === 'reason'
+        ? 'does not match any existing path in the repository'
+        : `correct the pattern or declare an intentionally new path with ${labelName}`;
+      if (violation === 'not-repository') return part === 'reason'
+        ? `does not match any existing path under ${repoRoot}; ` +
+          'git could not list that folder as a repository, so it was walked instead'
+        : `start the run from the repository root (cd into it, or pass ${labelName} <repository root>); ` +
+          'if this folder is the intended one, correct the pattern';
+      if (violation === 'invalid-glob') return part === 'reason'
+        ? `could not parse the pattern: ${message}`
+        : 'correct the pattern and retry';
+      if (violation === 'non-utf8') return part === 'reason'
+        ? message
+        : 'rename the non-UTF-8 file using a UTF-8 file name and retry';
+      throw new Error(`unknown scope-pattern-match violation: ${violation}`);
+    },
+  }),
+  'run-phase-required': Object.freeze({
+    data: Object.freeze(['violation', 'phaseLabel', 'phase', 'agent', 'names']),
+    topic: 'order',
+    rule: 'Declare an allowed phase for the assigned agent; phase may be omitted only when default is its sole phase.',
+    message: ({ violation, phaseLabel, phase, agent, names }) => {
+      let reason;
+      if (violation === 'missing') reason = `${phaseLabel} is required`;
+      else if (violation === 'undeclared') reason = `undeclared ${phaseLabel} ${JSON.stringify(phase)}`;
+      else throw new Error(`unknown run-phase-required violation: ${violation}`);
+      return `${reason} for ${agent}. Action: pass ${phaseLabel} <name>; allowed phases: ${names.join(', ')}.`;
+    },
+  }),
+  'order-id-owner': Object.freeze({
+    data: Object.freeze(['violation', 'orderId', 'ownerDir', 'slug', 'startedAt', 'hashScheme', 'labelName']),
+    topic: 'order',
+    rule: 'Use a new order id for a new task; another pass of an owned order needs a continue or retry header grant.',
+    message: ({ violation, orderId, ownerDir, slug, startedAt, hashScheme, labelName }) => {
+      const identity = `Order id collision: ${JSON.stringify(String(orderId ?? ''))} already belongs to run folder ${ownerDir} ` +
+        `(slug ${slug}, started_at ${startedAt})`;
+      if (violation === 'predates-hash-scheme') {
+        return `${identity}, recorded before the task header (hash scheme ${hashScheme}), so its task cannot be compared. ` +
+          `Its answer is already on disk in that folder (codex-bridge read "${ownerDir}"). ` +
+          'Another pass of that order needs a continue:/retry: header line; a new task needs a new order id.';
+      }
+      if (violation === 'different-task') {
+        return `${identity} with a different task. Use a new order id (${labelName}), or a continue:/retry: header line ` +
+          'if this is another pass of that order.';
+      }
+      throw new Error(`unknown order-id-owner violation: ${violation}`);
+    },
+  }),
+  'scope-pattern-refusal': Object.freeze({
+    data: Object.freeze(['pattern']),
+    topic: 'order',
+    rule: 'Correct the refused scope pattern using its scope-check reason and action before starting a run.',
+    message: ({ pattern, reason, action }) =>
+      `pattern ${JSON.stringify(pattern)} refused: ${reason}. Action: ${action}.`,
+  }),
+});

package/src/home/lib/order-rules/task-document.mjs

@@ -0,0 +1,80 @@
+/** Plan_79 D4: owns rules for task-body sections. */
+export const RULES = Object.freeze({
+  'scout-questions': Object.freeze({
+    data: Object.freeze(['violation', 'line']),
+    topic: 'order',
+    rule: 'For codex-scout, include a non-empty Questions section in the task document. ' +
+      'Whenever Questions is present, put each question on its own line as a Markdown list item ' +
+      'using -, *, or a number followed by a dot.',
+    message: ({ violation, line }) => {
+      if (violation === 'non-list-line') {
+        return `Questions section contains a non-list line: ${JSON.stringify(line.trim())}`;
+      }
+      if (violation === 'empty') return 'Questions section is empty';
+      if (violation === 'missing') {
+        return 'a sub-question is required for codex-scout: put one Markdown list item per sub-question ' +
+          'under a `Questions` heading in the task document. ' +
+          'The runner will not infer questions from the task text; no quota was spent.';
+      }
+      throw new Error(`unknown scout-questions violation: ${violation}`);
+    },
+  }),
+  'question-context-marker': Object.freeze({
+    data: Object.freeze(['index', 'text', 'context']),
+    topic: 'order',
+    rule: 'If a question uses a context-only marker, spell it exactly [context-only] and place it ' +
+      'only once, at the start, followed by whitespace (such as a space) and non-empty question text.',
+    message: ({ index, text, context, refusal }) => {
+      if (context === 'task-input') {
+        return `${refusal}; the marker is exactly [context-only] followed by a space and the question; no quota was spent.`;
+      }
+      if (context !== undefined) throw new Error(`unknown question-context-marker context: ${context}`);
+      return `Q${index + 1} has an invalid context-only marker in ${JSON.stringify(text)}`;
+    },
+  }),
+  'verify-line': Object.freeze({
+    data: Object.freeze(['violation']),
+    topic: 'order',
+    rule: 'When a Verify section is present, put exactly one non-empty command line in it; ' +
+      'blank lines are ignored. The section runs until the next heading of the same or a higher level, ' +
+      'so any non-empty line after the command, including a paragraph or a second command, counts as another line. ' +
+      'Put ## Verify last or follow it with another heading.',
+    message: ({ violation }) => {
+      if (violation === 'empty') return 'Verify section is empty';
+      if (violation === 'multiple-lines') return 'Verify section must contain exactly one non-empty line';
+      throw new Error(`unknown verify-line violation: ${violation}`);
+    },
+  }),
+  'advisor-task-options': Object.freeze({
+    data: Object.freeze(['violation', 'lineNo', 'line', 'preference', 'optionId']),
+    topic: 'order',
+    rule: 'For an advisor task, write a ## Options section with at least two distinct options ' +
+      'as - option-id: description, using ids matching [a-z0-9][a-z0-9-]*; ' +
+      'remove preference markers from every line in that section (Plan_59 D5).',
+    message: ({ violation, lineNo, line, preference, optionId }) => {
+      if (violation === 'missing') return 'Options: add a "## Options" section with at least two options.';
+      const location = `Options line ${lineNo} ${JSON.stringify(line)}`;
+      if (violation === 'preference') {
+        return `${location}: remove preference marker ${JSON.stringify(preference)} (D5).`;
+      }
+      if (violation === 'option-shape') {
+        return `${location}: use "- option-id: description" with id matching [a-z0-9][a-z0-9-]*.`;
+      }
+      if (violation === 'duplicate') return `${location}: replace duplicate option id "${optionId}".`;
+      if (violation === 'too-few') return `${location}: provide at least two distinct options.`;
+      throw new Error(`unknown advisor-task-options violation: ${violation}`);
+    },
+  }),
+  'advisor-task-paths': Object.freeze({
+    data: Object.freeze(['violation', 'lineNo', 'line']),
+    topic: 'order',
+    rule: 'For an advisor task, write a ## Paths section with at least one repository-relative path as a list item.',
+    message: ({ violation, lineNo, line }) => {
+      if (violation === 'missing') return 'Paths: add a "## Paths" section with repository-relative paths.';
+      if (violation === 'empty') {
+        return `Paths line ${lineNo} ${JSON.stringify(line)}: add at least one repository-relative path as a list item.`;
+      }
+      throw new Error(`unknown advisor-task-paths violation: ${violation}`);
+    },
+  }),
+});

package/src/home/lib/order-rules.mjs

@@ -0,0 +1,77 @@
+/**
+ * Plan_79 D4 places each rule where the orchestrator writes what it governs:
+ * the call line or task file → call.mjs; a grant label (continue, retry,
+ * advice) → header-grants.mjs; any other header label → header.mjs;
+ * a body section → task-document.mjs (all under order-rules/).
+ * A file outgrowing the gate splits by the next level of the same place
+ * (header → label families), never by number.
+ */
+import { RULES as HEADER_RULES } from './order-rules/header.mjs';
+import { RULES as HEADER_GRANT_RULES } from './order-rules/header-grants.mjs';
+import { RULES as TASK_DOCUMENT_RULES } from './order-rules/task-document.mjs';
+import { RULES as CALL_RULES } from './order-rules/call.mjs';
+import { recordOrderText, checkOrderTextParameters } from './order-text-record.mjs';
+
+const places = [HEADER_RULES, HEADER_GRANT_RULES, TASK_DOCUMENT_RULES, CALL_RULES];
+const keys = new Set();
+for (const rules of places) {
+  for (const key of Object.keys(rules)) {
+    if (keys.has(key)) throw new Error(`duplicate order rule key: ${key}`);
+    keys.add(key);
+  }
+}
+export const ORDER_RULES = Object.freeze(Object.assign({}, ...places));
+
+export function orderRuleMessage(key, values = {}) {
+  if (!Object.hasOwn(ORDER_RULES, key)) throw new Error(`unknown order rule: ${key}`);
+  checkOrderTextParameters('orderRuleMessage', key, values, ORDER_RULES[key].data);
+  return recordOrderText(ORDER_RULES[key].message(values));
+}
+
+// Plan_79 B3b: adds a location to text built by the registry and owns no rule.
+export function orderRefusalAt(location, message) {
+  checkOrderTextParameters('orderRefusalAt', null, { location, message }, ['location']);
+  return recordOrderText(`${location}: ${message}`);
+}
+
+// Plan_79 B3c1: adds a source location to text built by the registry and owns no rule.
+export function orderProblemLine({ lineNo, reason, line }) {
+  checkOrderTextParameters('orderProblemLine', null, { lineNo, reason, line }, ['lineNo', 'line']);
+  return recordOrderText(lineNo === null ? reason : `line ${lineNo}: ${reason}: ${line}`);
+}
+
+// Plan_79 B3c2: adds a label name to text built by the registry and owns no rule.
+export function orderLabelReason(labelName, reason) {
+  checkOrderTextParameters('orderLabelReason', null, { labelName, reason }, ['labelName']);
+  return recordOrderText(`${labelName} ${reason}`);
+}
+
+// Plan_79 B3c2: renders the label schema owned by order-schema.mjs and owns no rule.
+export function orderHeaderHelp(labels) {
+  checkOrderTextParameters('orderHeaderHelp', null, { labels }, ['labels']);
+  return recordOrderText(labels.map(({ label, example }) => `${label}: ${example}`).join('\n'));
+}
+
+// Plan_79 D3: callers supply the topic catalogue so installed rules do not depend on the CLI tree.
+export function validateOrderRules(rules, topics, diagnostics) {
+  for (const [key, entry] of Object.entries(rules)) {
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(key)) {
+      throw new Error(`invalid order rule key: ${key}`);
+    }
+    if (Object.hasOwn(diagnostics, key)) throw new Error(`duplicate order key: ${key}`);
+    if (!entry || Object.keys(entry).length !== 4 ||
+        !['topic', 'rule', 'message', 'data'].every((field) => Object.hasOwn(entry, field))) {
+      throw new Error(`invalid order rule entry: ${key}`);
+    }
+    if (!Object.hasOwn(topics, entry.topic)) throw new Error(`unknown order rule topic: ${key}`);
+    if (typeof entry.rule !== 'string' || !entry.rule.trim() || entry.rule.includes('{{')) {
+      throw new Error(`invalid order rule text: ${key}`);
+    }
+    if (typeof entry.message !== 'function') throw new Error(`invalid order rule message: ${key}`);
+    if (!Array.isArray(entry.data) ||
+        ![...entry.data].every((name) => typeof name === 'string' && name.trim()) ||
+        new Set(entry.data).size !== entry.data.length) {
+      throw new Error(`invalid order rule data: ${key}`);
+    }
+  }
+}