@mrciphersmith/keryx 0.3.27 → 0.3.29

package/dist/core.js

@@ -9178,12 +9178,19 @@ var init_export = __esm(() => {
   SKILL_RUNTIMES = [...HARNESS_SKILL_RUNTIMES, "plugin"];
 });
 
+// src/gdskills/model-version.ts
+var TRAILING_ALIAS_WORDS;
+var init_model_version = __esm(() => {
+  TRAILING_ALIAS_WORDS = new Set(["latest", "preview"]);
+});
+
 // src/gdskills/model-tier.ts
 function isModelTier(value) {
   return typeof value === "string" && MODEL_TIERS.includes(value);
 }
 var MODEL_TIERS, TIER_ALIASES, SKILL_TIER_KEY = "model_tier", TIER_DECLARATION;
 var init_model_tier = __esm(() => {
+  init_model_version();
   MODEL_TIERS = ["light", "standard", "deep"];
   TIER_ALIASES = new Map([["cheap", "light"]]);
   TIER_DECLARATION = new RegExp(`^\\s*(?:[-*]\\s*)?"?(?:${SKILL_TIER_KEY}|model-tier|modelTier)"?\\s*[:=]\\s*(.+?)\\s*,?\\s*$`, "i");
@@ -21620,6 +21627,7 @@ init_validator();
 var exports_service2 = {};
 __export(exports_service2, {
   AC_CHECK_TOKEN_BUDGET: () => AC_CHECK_TOKEN_BUDGET,
+  AC_KINDS: () => AC_KINDS,
   CONFIRMATION_CAVEAT: () => CONFIRMATION_CAVEAT,
   REVIEW_GATE_CONFIG_PATH: () => REVIEW_GATE_CONFIG_PATH,
   acCheckCacheKey: () => acCheckCacheKey,
@@ -21629,10 +21637,13 @@ __export(exports_service2, {
   assertAcIntact: () => assertAcIntact,
   baseBranchCondition: () => baseBranchCondition,
   batchAcCheckItems: () => batchAcCheckItems,
+  buildAcKindReport: () => buildAcKindReport,
+  classifyAcCriterionNotCheckable: () => classifyAcCriterionNotCheckable,
   classifyNotCheckable: () => classifyNotCheckable,
   computeAcFacts: () => computeAcFacts,
   confirmPreconditionError: () => confirmPreconditionError,
   createFlowService: () => createFlowService,
+  describeAcKind: () => describeAcKind,
   evaluatedVerdict: () => evaluatedVerdict,
   extractCriterionTokens: () => extractCriterionTokens,
   factsOnlyVerdict: () => factsOnlyVerdict,
@@ -21642,12 +21653,16 @@ __export(exports_service2, {
   parseAcceptanceCriteria: () => parseAcceptanceCriteria,
   readAcCheckCache: () => readAcCheckCache,
   readAcCheckEnabled: () => readAcCheckEnabled,
+  readAcKindRecords: () => readAcKindRecords,
   readFlow: () => readFlow,
   renderAcCheckAdvisoryNotice: () => renderAcCheckAdvisoryNotice,
   renderAcCheckReport: () => renderAcCheckReport,
+  renderAcKindDistribution: () => renderAcKindDistribution,
+  reportFromRecords: () => reportFromRecords,
   resolveFlowDir: () => resolveFlowDir,
   selectMatchedHunks: () => selectMatchedHunks,
   statusLabel: () => statusLabel,
+  stripVerifyMarker: () => stripVerifyMarker,
   summarizeVerdicts: () => summarizeVerdicts,
   validateCriterionName: () => validateCriterionName,
   writeAcCheckCache: () => writeAcCheckCache
@@ -23972,6 +23987,161 @@ async function readRequireConfirmationDefault(cwd) {
     return false;
   }
 }
+// src/flow/ac-kinds.ts
+var AC_KINDS = ["exec", "invariant", "judged", "none", "unclassified"];
+var AC_LINE = /^\s*[-*]\s*(AC\d+)\s*:\s?(.*)$/i;
+var MARKER_OPEN = "[verify:";
+function maskCodeSpans(text) {
+  return text.replace(/`[^`]*`/g, (span) => " ".repeat(span.length));
+}
+function scanMarkers(text) {
+  const masked = maskCodeSpans(text);
+  let occurrences = 0;
+  let lastStart = -1;
+  for (let at = masked.indexOf(MARKER_OPEN);at !== -1; at = masked.indexOf(MARKER_OPEN, at + MARKER_OPEN.length)) {
+    occurrences += 1;
+    lastStart = at;
+  }
+  const end = text.trimEnd().length;
+  return { occurrences, lastStart, trailing: occurrences > 0 && end > lastStart && text[end - 1] === "]", end };
+}
+function stripVerifyMarker(text) {
+  const scan = scanMarkers(text);
+  if (!scan.trailing || scan.occurrences !== 1)
+    return text;
+  return text.slice(0, scan.lastStart).trimEnd();
+}
+var KIND_WORDS = "exec, invariant, judged or none";
+function unclassified(error) {
+  return error === undefined ? { record: { kind: "unclassified" } } : { record: { kind: "unclassified" }, error };
+}
+function parseAcKindText(text) {
+  const scan = scanMarkers(text);
+  if (scan.occurrences === 0)
+    return unclassified();
+  if (scan.occurrences > 1) {
+    return unclassified("a second [verify: \u2026] marker \u2014 a criterion carries exactly one, as the last thing on its line");
+  }
+  if (!scan.trailing) {
+    return unclassified("the [verify: \u2026] marker must be the last thing on the line and close with `]`");
+  }
+  const payload = text.slice(scan.lastStart + MARKER_OPEN.length, scan.end - 1).trim();
+  if (payload.length === 0)
+    return unclassified(`an empty [verify: \u2026] marker \u2014 expected ${KIND_WORDS}`);
+  const word = /^[A-Za-z]+/.exec(payload)?.[0] ?? "";
+  const rest = payload.slice(word.length).trim();
+  switch (word) {
+    case "judged":
+      return rest.length === 0 ? { record: { kind: "judged" } } : unclassified("`judged` takes no arguments \u2014 write [verify: judged]");
+    case "exec":
+    case "invariant": {
+      if (rest.length === 0)
+        return unclassified(`\`${word}\` requires a backticked command, e.g. [verify: ${word} \`bun test path/to.test.ts\`]`);
+      const command = /^`([^`]*)`$/.exec(rest);
+      if (command === null)
+        return unclassified(`\`${word}\` requires exactly one backticked command after the kind, e.g. [verify: ${word} \`bun test path/to.test.ts\`]`);
+      const check = (command[1] ?? "").trim();
+      if (check.length === 0)
+        return unclassified(`\`${word}\` has an empty backticked command`);
+      return { record: { kind: word, check } };
+    }
+    case "none": {
+      if (rest.length === 0)
+        return unclassified("`none` requires a reason after an em dash, e.g. [verify: none \u2014 <reason>]");
+      const reason = /^\u2014\s*([\s\S]*)$/.exec(rest);
+      if (reason === null)
+        return unclassified("`none` requires its reason after an em dash (\u2014), e.g. [verify: none \u2014 <reason>]");
+      const why = (reason[1] ?? "").trim();
+      if (why.length === 0)
+        return unclassified("`none` has an empty reason after the em dash");
+      return { record: { kind: "none", reason: why } };
+    }
+    default:
+      return unclassified(`unknown verification kind "${word.length > 0 ? word : payload}" \u2014 expected ${KIND_WORDS}`);
+  }
+}
+function parseAcKinds(content) {
+  const criteria = [];
+  const errors = [];
+  for (const line of content.split(/\r?\n/)) {
+    const match = AC_LINE.exec(line);
+    if (!match?.[1])
+      continue;
+    const id = match[1].toUpperCase();
+    const rawText = (match[2] ?? "").trim();
+    const parsed = parseAcKindText(rawText);
+    if (parsed.error !== undefined)
+      errors.push({ id, message: parsed.error });
+    criteria.push({ id, text: stripVerifyMarker(rawText), rawText, record: parsed.record });
+  }
+  return { criteria, errors };
+}
+function emptyCounts() {
+  return { exec: 0, invariant: 0, judged: 0, none: 0, unclassified: 0 };
+}
+function buildAcKindReport(flowId, content) {
+  const parsed = parseAcKinds(content);
+  const criteria = {};
+  for (const criterion of parsed.criteria) {
+    if (!(criterion.id in criteria))
+      criteria[criterion.id] = criterion.record;
+  }
+  return { report: reportFromRecords(flowId, criteria), errors: parsed.errors };
+}
+function reportFromRecords(flowId, criteria) {
+  const counts = emptyCounts();
+  for (const record of Object.values(criteria))
+    counts[record.kind] += 1;
+  return {
+    flowId,
+    criteria,
+    counts,
+    runnable: counts.exec + counts.invariant,
+    total: Object.keys(criteria).length
+  };
+}
+function renderAcKindDistribution(report) {
+  const { counts } = report;
+  const percent = report.total === 0 ? 0 : Math.round(report.runnable / report.total * 100);
+  const tail = [`${counts.none} accepted as unverifiable`, `${counts.judged} judged`, ...counts.unclassified > 0 ? [`${counts.unclassified} unclassified`] : []];
+  return [
+    `acceptance kinds: exec ${counts.exec}  invariant ${counts.invariant}  judged ${counts.judged}  none ${counts.none}  unclassified ${counts.unclassified}   (${report.total} criteria)`,
+    `coverage: ${report.runnable}/${report.total} runnable (${percent}%)  \xB7  ${tail.join("  \xB7  ")}`
+  ];
+}
+function describeAcKind(record) {
+  switch (record.kind) {
+    case "exec":
+    case "invariant":
+      return `${record.kind} \`${record.check}\``;
+    case "none":
+      return `none \u2014 ${record.reason}`;
+    default:
+      return record.kind;
+  }
+}
+function readAcKindRecords(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return;
+  const out = {};
+  for (const [id, raw] of Object.entries(value)) {
+    if (typeof raw !== "object" || raw === null)
+      return;
+    const record = raw;
+    const kind = record["kind"];
+    if ((kind === "exec" || kind === "invariant") && typeof record["check"] === "string")
+      out[id] = { kind, check: record["check"] };
+    else if (kind === "judged")
+      out[id] = { kind };
+    else if (kind === "none" && typeof record["reason"] === "string")
+      out[id] = { kind, reason: record["reason"] };
+    else if (kind === "unclassified")
+      out[id] = { kind };
+    else
+      return;
+  }
+  return out;
+}
 // src/flow/check-ac.ts
 import { createHash as createHash8 } from "crypto";
 import { chmod as chmod4, mkdir as mkdir9, readFile as readFile21 } from "fs/promises";
@@ -23985,11 +24155,11 @@ function estimateTokens(text) {
 // src/flow/check-ac.ts
 init_service2();
 init_fs();
-var AC_LINE = /^\s*[-*]\s*(AC\d+)\s*:\s?(.*)$/i;
+var AC_LINE2 = /^\s*[-*]\s*(AC\d+)\s*:\s?(.*)$/i;
 function parseAcceptanceCriteria(content) {
   const out = [];
   for (const line of content.split(/\r?\n/)) {
-    const match = AC_LINE.exec(line);
+    const match = AC_LINE2.exec(line);
     if (match?.[1]) {
       out.push({ id: match[1].toUpperCase(), text: (match[2] ?? "").trim() });
     }
@@ -24036,6 +24206,9 @@ function classifyNotCheckable(criterionText) {
     reason: `not-checkable: every clause of this criterion names a condition no diff records (${labels.join(", ")}) \u2014 assigned without asking Jev.`
   };
 }
+function classifyAcCriterionNotCheckable(criterion) {
+  return classifyNotCheckable(stripVerifyMarker(criterion.text));
+}
 function extractCriterionTokens(text) {
   const tokens = new Set;
   for (const match of text.matchAll(/`([^`]+)`/g)) {
@@ -24053,7 +24226,7 @@ function extractCriterionTokens(text) {
   return [...tokens];
 }
 function computeAcFacts(criterion, diffText, changedFiles) {
-  const tokens = extractCriterionTokens(criterion.text);
+  const tokens = extractCriterionTokens(stripVerifyMarker(criterion.text));
   const tokensPresent = tokens.filter((token) => diffText.includes(token) || changedFiles.some((file) => file.includes(token)));
   const tokensAbsent = tokens.filter((token) => !tokensPresent.includes(token));
   const testFiles = changedFiles.filter((file) => /\.(test|spec)\.[a-z]+$/i.test(file));
@@ -24079,7 +24252,7 @@ var AC_CHECK_TOKEN_BUDGET = 64000;
 function questionFor(criterion) {
   return {
     type: "noul",
-    instructions: `Given the deterministic facts and the redacted diff evidence above, does this change LIKELY SATISFY this frozen ` + `acceptance criterion? Criterion ${criterion.id}: ${redactSensitiveText(criterion.text)}`
+    instructions: `Given the deterministic facts and the redacted diff evidence above, does this change LIKELY SATISFY this frozen ` + `acceptance criterion? Criterion ${criterion.id}: ${redactSensitiveText(stripVerifyMarker(criterion.text))}`
   };
 }
 var MAX_MATCHED_HUNKS_PER_ITEM = 8;
@@ -24424,6 +24597,10 @@ function renderJournal(createdAt) {
 }
 
 // src/flow/service.ts
+async function deriveAcKinds(cwd, dir, flowId) {
+  const { report } = buildAcKindReport(flowId, await readFile23(acPath(cwd, dir), "utf8"));
+  return { ...report.criteria };
+}
 function recordAttempt(task, outcome, at, detail) {
   const attempts = task.attempts ?? { count: 0, log: [] };
   attempts.count += 1;
@@ -24621,6 +24798,7 @@ function createFlowService(deps) {
           throw new Error("Cannot freeze: acceptance-criteria.md must contain at least one real `- ACn:` criterion.");
         }
         flow.acChecksum = await acChecksum(cwd, dir);
+        flow.acKinds = await deriveAcKinds(cwd, dir, flow.id);
         flow.status = "ready";
         return save(cwd, dir, flow, "frozen", `${criteria.length} criteria; checksum recorded`);
       });
@@ -24765,10 +24943,15 @@ function createFlowService(deps) {
           detail = `${normalizedCriterion}: "${previousText ?? "(new)"}" -> "${normalizedText}" (${reason.trim()})`;
         }
         flow.acChecksum = await acChecksum(cwd, dir);
+        flow.acKinds = await deriveAcKinds(cwd, dir, flow.id);
         flow.acConfirmed = {};
         return save(cwd, dir, flow, "ac-updated", detail);
       });
     },
+    async acKinds({ cwd, id }) {
+      const { dir, flow } = await load(cwd, id);
+      return buildAcKindReport(flow.id, await readFile23(acPath(cwd, dir), "utf8"));
+    },
     async acReseal({ cwd, id, reason }) {
       if (!reason?.trim()) {
         throw new Error('flow ac reseal requires --reason "<why the checksum is stale>"');
@@ -24787,6 +24970,7 @@ function createFlowService(deps) {
           throw new Error(`flow ac reseal: refusing \u2014 ${evidence.reason}. ` + "Reseal only re-seals a stale checksum over an unchanged file; it is not a way to " + 'accept an edit. If the criteria really changed, use `keryx flow ac update <id> --reason "..."`, ' + "which re-seals AND voids the prior confirmations.");
         }
         flow.acChecksum = current;
+        flow.acKinds = await deriveAcKinds(cwd, dir, flow.id);
         return save(cwd, dir, flow, "ac-resealed", reason);
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.27",
+  "version": "0.3.29",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/rules/core/model-selection.mdc

@@ -57,13 +57,14 @@ candidate set. `src/gdskills/model-tier.ts` then:
 | Tier | Resolves to |
 |---|---|
 | `standard` | the session's model, always |
-| `deep` | the highest-ranked discovered model **strictly above** the session's, else the session's |
-| `light` | the lowest-ranked discovered model **strictly below** the session's, else the session's |
+| `deep` | the best discovered model **above** the session's — a larger size class, or a NEWER generation of the session model's own family — else the session's |
+| `light` | the **next size step below** the session's (an Opus-class session takes the Sonnet class, not the Haiku class), else the session's; the smallest class only when nothing sits between |
 
 Anchoring on the session model is what makes "never a downgrade" checkable
 rather than hoped for: a tier can only move away from the session model in the
 direction its own name points, and a candidate at the session's own rank is a
-lateral move and never taken.
+lateral move and never taken. An OLDER sibling of the session's own family is
+never `light` or `deep` either.
 
 ## What the hints are, and what they are not
 
@@ -83,13 +84,24 @@ residue, and it is kept in the smallest shape that works:
 A model whose name is a codename carrying no size is unrankable by design. That
 is the honest outcome, not a gap to be patched with folklore.
 
-**Version is deliberately not ranked here.** `rankModelId` never parses a
-version number out of an id — two ids in the same size-word family but a
-different generation (an older vs. a newer numbered release of the same
-line) rank IDENTICALLY through this resolution, and a
-`standard`/`light`/`deep` dispatch never distinguishes between them. That
-stays true for `spawn_subagent` and `keryx review tier` after the decision
-below; it is a DIFFERENT consumer's rule, not this one's.
+**Version is a second axis, not a size hint (flow 358).** `rankModelId` still
+never parses a version number out of an id: the size words order size CLASSES.
+Generation is ordered separately, and only within **the same family and
+vendor** — the id with its version tokens removed (`familyKey`) must match. A
+newer release outranks an older one of its own family, so a session on the
+older one resolves `deep` to the newer sibling, and a session on the newer one
+never resolves `light` or `deep` to the older. A version number is **never**
+compared across families: a higher number on one line says nothing about a
+different line.
+
+**A larger class of an older generation is ambiguous, not "above".** When the
+only discovered models above the session are a larger size class whose version is
+older than the session's, size words alone cannot call them stronger, and
+`deep` must not move onto a model that is older-generation and — by the
+profile price — the more expensive one. Without an agent the tier keeps the
+session's model as `session-fallback`, with the reason recorded (reason id
+`kept-older-generation`, or `kept-older-generation-pricier` when the profile
+price shows it costs more). The agent fallback below is the only other way out.
 
 The routing "derived default table" (`deriveDefaultTable`,
 `src/harness/routing/derive-default-table.ts`, flow 327/PRD §6.3) is that
@@ -102,8 +114,9 @@ version ranks higher there — the family word (a size marker from this same
 `MODEL_RANK_HINTS` list) already carries the size class, so version is free
 to order generations within it. That table reuses
 `rankModelId`/`MODEL_RANK_HINTS` UNMODIFIED for the size axis and adds its
-own separate, conservative version parse on top of it — nothing above
-changes for this module's own tier resolution.
+own separate, conservative version parse on top of it. Since flow 358 the tier
+resolution reads the same version parse (`src/gdskills/model-version.ts`, shared
+so neither module imports the other).
 
 That version parse (`parseModelVersion`/`familyKey`, round 2) reads BOTH a
 dotted id (`vendor-opus-5.5`, `gemini-3.8-flash`) and a real
@@ -152,6 +165,35 @@ Do not "fix" a fallback by adding model ids to the code. Add a size word to the
 hints if one genuinely applies, or leave it: running on the session's model is a
 correct answer.
 
+## The agent fallback: comparing candidate models, nothing else
+
+When the ranking is **refused** but the provider did report other models, or a
+tier is **ambiguous** (an older-generation larger class, above), an injected
+agent may be asked to put the candidate models in order. It is a port
+(`TierRankAgent`): `src/gdskills/model-tier.ts` holds no network and no
+filesystem, the caller supplies the real one, and a test supplies a fake.
+
+Its limits are the point:
+
+- **It compares candidate models and never rates a task's own difficulty.** It is
+  shown no task, no diff and no user text — only the discovered ids and the
+  profile prices — and it is asked one question: which of these models is more
+  capable than which. The tier is still computed by `assignTier` from signals
+  the orchestrator holds.
+- It must answer JSON, `{"order": [...]}`, best first, and must place the session's
+  own model. An id that was not discovered is dropped. An agent error, a
+  timeout, a malformed answer, or one that leaves out the session's model
+  resolves to the session's model, exactly as without an agent.
+- It never places `standard` or `deep` below the session: `deep` is only ever taken
+  from above the session in its order, `standard` is never asked. A larger
+  class of an older generation that costs more than the session's model is
+  refused whatever it says.
+- The result is cached by a hash of the candidate catalogue with prices, so an
+  identical catalogue asks once.
+- It runs on the **light** tier of the session's own provider — the cheap step
+  below the session, or the session model itself when nothing sits below.
+- A resolution it produced is recorded `tier_resolution: agent-ranked`.
+
 ## Where this actually runs
 
 Two places, and they are not the same shape:
@@ -236,8 +278,9 @@ arithmetic straight back in the caller's head.
 
 ## Adaptive: `inherit: true`
 
-A model is named only when discovery assigned one **other than** the session's
-(`tier_resolution: discovered`). In every other case — no session named, ranking
+A model is named only when discovery — or, failing that, the agent fallback —
+assigned one **other than** the session's (`tier_resolution: discovered` or
+`agent-ranked`). In every other case — no session named, ranking
 refused, or the tier resolving to the session's own model — the block carries the
 tier and `inherit: true`, and the **host** resolves it against the models its own
 dispatch tool offers:
@@ -255,18 +298,19 @@ fallback. Exit status is always 0.
 ## Recording the decision
 
 The dispatch carries the tier, the ordered rule ids that produced it, which of
-the three outcomes occurred, and what was on the table when it did —
-`model.tier`, `model.tier_reasons`, `model.tier_resolution` and
+the outcomes occurred, and what was on the table when it did —
+`model.tier`, `model.tier_reasons` (the assignment rule ids, then `resolve:<reason id>` for the resolution), `model.tier_resolution` and
 `model.model_discovery` in
 `.metaproject/core/gdskills/contracts/subagent-dispatch.schema.json`.
 
-`tier_resolution` distinguishes three facts that must not be flattened:
+`tier_resolution` distinguishes four facts that must not be flattened:
 
 | Value | Means |
 |---|---|
 | `discovered` | a discovered model was assigned to this tier |
 | `session-ranked` | ranking worked and placed the tier at the session's model |
-| `session-fallback` | ranking was refused; the session's model is kept |
+| `session-fallback` | ranking was refused or was ambiguous; the session's model is kept |
+| `agent-ranked` | the agent fallback put the candidates in order and its answer was used |
 
 "Fell back to the session model" and "assigned the session model because it
 ranked there" are different facts. A run that cannot be explained afterwards is
@@ -286,6 +330,9 @@ recording them is one copy rather than four decisions.
   the resolution code.
 - Take the candidate set from runtime detection. Never from a literal list of
   what exists.
+- The agent fallback compares candidate models. Never ask any model to rate a
+  task's own difficulty, and never let the fallback place `standard` or `deep`
+  below the session's model.
 - When the candidates cannot be ranked, the block is adaptive (`inherit: true`).
   The host never goes below its session model for `standard` or `deep`, and takes
   a lighter class only for a `light` tier.

package/src/gdskills/bundled/rules/core/requirements-package-standard.mdc

@@ -62,11 +62,26 @@ document changes.
 - problem;
 - goal;
 - users;
-- requirements;
-- success criteria;
+- requirements, each carrying a verification field (see Verification Field below);
+- success criteria, split into two lists (see Success Contract below);
 - risks;
 - recommendation.
 
+### Success Contract
+
+The PRD's success criteria are two lists, never one:
+
+- **Release criteria** are checkable when the work ships: a test, a command, a
+  file, a count. Each is something a release can be blocked on.
+- **Outcome criteria** are what should be true some time after release: adoption,
+  a measured change, a behavior seen in use. Each outcome criterion either names
+  the observation that would confirm it (what is looked at, where, and when) or
+  declares `not measured — <reason>`.
+
+An outcome criterion with neither an observation nor a `not measured — <reason>`
+is not a criterion. A list whose every entry is `not measured` is acceptable: it
+is honest. A PRD with no outcome list at all is not.
+
 ## Specification Contract
 
 `specification.md` must state:
@@ -79,6 +94,21 @@ document changes.
 - integration points;
 - acceptance criteria.
 
+### Verification Field
+
+Every requirement in the PRD (each `R<n>` under Requirements) carries one verification field, in the
+same vocabulary a flow criterion's trailing marker uses:
+
+```markdown
+Verification: exec `<command>`            # a command whose exit code decides it
+Verification: invariant `<command>`       # a command that must keep passing
+Verification: judged                      # a person reads the evidence
+Verification: none — <reason>             # honestly unverifiable, with the reason
+```
+
+`exec` and `invariant` name a backticked command; `none` names its reason after
+an em dash. A requirement with no field is a defect, not a `none`.
+
 ## Verification Contract
 
 Before finishing:
@@ -88,6 +118,11 @@ Before finishing:
 - verify README links to all package files;
 - verify schemas are referenced from specification when present;
 - verify status is honest: `draft`, `spec ready`, `implemented`, or `future`;
+- verify every PRD requirement carries a `Verification:` field, and
+  fail the package when one does not, naming that requirement;
+- verify the PRD has both a release-criteria list and an outcome-criteria list,
+  and fail the package when the outcome list is missing (an outcome list whose
+  entries are all `not measured — <reason>` passes);
 - update `docs/requirements/roadmap.md` when the package represents a module or
   standard capability.
 

package/src/gdskills/bundled/skills/planning/docpack-orchestrator/SKILL.md

@@ -109,10 +109,8 @@ Add optional files only when justified:
 Write concise Markdown with explicit headings. Required contracts:
 
 - README: purpose, status, document index, scope, related modules.
-- PRD: problem, goal, users, requirements, success criteria, risks,
-  recommendation.
-- Specification: identity, structure, manifest/config, CLI/skill surface, data
-  contracts, integrations, acceptance criteria.
+- PRD: problem, goal, users, requirements (each `R<n>` carries a `Verification:` field: `exec`/`invariant` with a backticked command, `judged`, or `none — <reason>`), success criteria (a release list and an outcome list; an outcome criterion names its observation or declares `not measured — <reason>`), risks, recommendation.
+- Specification: identity, structure, manifest/config, CLI/skill surface, data contracts, integrations, acceptance criteria.
 
 When updating existing docs, preserve useful content and bump versions.
 
@@ -125,6 +123,7 @@ Run a local verification pass:
 - README links to every package file;
 - schema files are valid JSON;
 - specification references schemas when present;
+- every PRD requirement has a `Verification:` field (a package with a requirement that omits it FAILS, naming that requirement); the PRD has a release list and an outcome list (no outcome list FAILS; an outcome list whose entries are all `not measured — <reason>` passes);
 - roadmap is updated for new module/standard capabilities;
 - no implementation status is overstated.
 
@@ -154,6 +153,7 @@ Do not emit the Final Response until all of these hold:
 - Every Markdown file in the package carries a `Version`, and every file you changed has a bumped one.
 - `README.md` links to every file in the package; the specification links to each schema it defines.
 - Every `schemas/*.json` parses as valid JSON.
+- Every specification requirement carries a `Verification:` field, and the PRD carries both a release list and an outcome list; a package missing either was reported as `verification: fail`, naming the requirement.
 - `docs/requirements/roadmap.md` is updated when the package represents a new module or capability, or the report states why it does not.
 - No implementation claim appears that code does not support; anything unbuilt is marked planned or future.
 - `docpack-review` has been run in Phase 5 and reports zero blockers. Remaining warnings appear verbatim in `remaining_gaps`.

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-input.schema.json

@@ -79,7 +79,8 @@
           "enum": [
             "discovered",
             "session-ranked",
-            "session-fallback"
+            "session-fallback",
+            "agent-ranked"
           ]
         },
         "model_discovery": {

package/src/gdskills/contracts/subagent-dispatch.schema.json

@@ -83,7 +83,7 @@
       }
     },
     "model": {
-      "description": "Which model runs this dispatch. Skills declare a `tier`; at dispatch time src/gdskills/model-tier.ts DISCOVERS the models runtime provider detection reported for the active provider, ranks them by size markers in their names, and places the tier relative to the session's own model — `standard` is the session model, `deep` a discovered model ranked above it, `light` one ranked below. No table of model ids exists anywhere in the resolution. When the candidates cannot be ranked, every tier keeps the session's model. `provider`/`model` remain available for an explicit lateral selection, and an omitted block inherits the parent verbatim. Two things fill this block. The interactive `spawn_subagent` tool does it in code: it builds the tier map with `buildTierMap` from its host's detection result, hands it to `resolveChildModel`, and records the outcome on the dispatch's run trace. An orchestrator authoring a dispatch document RUNS `keryx review tier`, which takes the §4.4 signals as flags and prints exactly the fields below, ready to paste (`--json` prints this object alone). It is a command rather than a documented function call because an orchestrator is an agent following prose and cannot call a TypeScript function: told to `decideDispatchModel`, it computed the tier in its head from a table, which is the mechanical step that belongs in code. When nothing can be worked out the command emits `inherit: true` instead of `provider`/`model` — the dispatch runs on the caller's own model, never a downgrade. Neither path is enforced by a reader — nothing validates a recorded resolution against the model that actually ran — so these fields are a record, not a gate.",
+      "description": "Which model runs this dispatch. Skills declare a `tier`; at dispatch time src/gdskills/model-tier.ts DISCOVERS the models runtime provider detection reported for the active provider, ranks them by size markers in their names, and places the tier relative to the session's own model — `standard` is the session model, `deep` a discovered model above it (a larger size class, or a newer generation of the session model's own family), `light` the next size step below it. When the ranking is refused or ambiguous an injected agent may order the candidate models instead (it compares models, never rates a task); its answer is recorded as `agent-ranked`. No table of model ids exists anywhere in the resolution. When the candidates cannot be ranked, every tier keeps the session's model. `provider`/`model` remain available for an explicit lateral selection, and an omitted block inherits the parent verbatim. Two things fill this block. The interactive `spawn_subagent` tool does it in code: it builds the tier map with `buildTierMap` from its host's detection result, hands it to `resolveChildModel`, and records the outcome on the dispatch's run trace. An orchestrator authoring a dispatch document RUNS `keryx review tier`, which takes the §4.4 signals as flags and prints exactly the fields below, ready to paste (`--json` prints this object alone). It is a command rather than a documented function call because an orchestrator is an agent following prose and cannot call a TypeScript function: told to `decideDispatchModel`, it computed the tier in its head from a table, which is the mechanical step that belongs in code. When nothing can be worked out the command emits `inherit: true` instead of `provider`/`model` — the dispatch runs on the caller's own model, never a downgrade. Neither path is enforced by a reader — nothing validates a recorded resolution against the model that actually ran — so these fields are a record, not a gate.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
@@ -95,14 +95,14 @@
           "enum": ["light", "standard", "deep"]
         },
         "tier_reasons": {
-          "description": "The ordered rule ids `assignTier` applied, e.g. [\"base:standard\", \"floor:blast-radius\"]. Produced by `keryx review tier` from the signals passed as flags, never written by hand: a reason list an author composes records the story they tell about the tier rather than the rules that produced it. Recorded so a tier can be explained after the run instead of re-derived from a state nobody kept. Ids rather than prose, because they are compared across runs.",
+          "description": "The ordered rule ids `assignTier` applied, e.g. [\"base:standard\", \"floor:blast-radius\"], followed by one `resolve:<reason-id>` entry from the model resolution (e.g. `resolve:picked-above`, `resolve:kept-older-generation-pricier`, `resolve:agent-picked-below`). Produced by `keryx review tier` from the signals passed as flags, never written by hand: a reason list an author composes records the story they tell about the tier rather than the rules that produced it. Recorded so a tier can be explained after the run instead of re-derived from a state nobody kept. Ids rather than prose, because they are compared across runs.",
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
         "tier_resolution": {
-          "description": "Which of three outcomes produced the model, as `resolveTierModel` reports it on `TierResolution.source`. `discovered` — a model reported by runtime provider detection was assigned to this tier. `session-ranked` — ranking WORKED and placed the tier at the session's own model (always so for `standard`; for `light`/`deep` when nothing discovered ranks below/above the session). `session-fallback` — ranking was refused, or the ranking carried no rank for the session model, so the session's model is used because nothing could be worked out. Collapsing the last two would hide whether the environment was understood. Recorded, never read back: it explains a finished run and gates nothing.",
+          "description": "Which of four outcomes produced the model, as `resolveTierModel` reports it on `TierResolution.source`. `discovered` — a model reported by runtime provider detection was assigned to this tier. `session-ranked` — ranking WORKED and placed the tier at the session's own model (always so for `standard`; for `light`/`deep` when nothing discovered ranks below/above the session). `session-fallback` — ranking was refused or was ambiguous (a larger size class that is an older generation), or the ranking carried no rank for the session model, so the session's model is used because nothing could be worked out. `agent-ranked` — the ranking was refused or ambiguous and an injected agent, shown only the discovered ids and profile prices, put the candidate models in order and its validated answer picked the model; it compares models and never rates a task. Collapsing these would hide whether the environment was understood. Recorded, never read back: it explains a finished run and gates nothing.",
           "type": "string",
-          "enum": ["discovered", "session-ranked", "session-fallback"]
+          "enum": ["discovered", "session-ranked", "session-fallback", "agent-ranked"]
         },
         "model_discovery": {
           "description": "What was on the table when the tier was resolved: which models runtime detection reported for the active provider, how the size-marker hints ordered them, and — when ranking was refused — why. `tier_resolution` alone says a fallback happened and never says what it fell back FROM.",