mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -1,41 +1,9 @@
 /**
- * `qa` contract resolver — Epic #3214, Story #3294; environment-keyed
- * contract added by Epic #4326, Story #4327.
- *
- * The agent-driven QA harness (`/qa-run`) needs the
- * consumer's `.agentrc.json` `qa` block to know where the `.feature` root
- * lives, which deployment targets (`environments`) exist and how to sign in
- * to each, and which personas the seam accepts. The block is
- * *optional in the schema* (most repos never bind the harness, so config
- * validation must not break them — see Tech Spec #3285 § "qa contract
- * block"), which means presence is enforced at run time by this resolver
- * rather than by the AJV gate.
- *
- * This resolver is the single seam the harness calls. It fails **loudly**:
- *   - Absent block  → throw with the operator-actionable phrase
- *     "this project has not bound the QA harness". There is no silent
- *     fallback to auto-detection; the harness must not pretend a contract
- *     exists.
- *   - Malformed block → throw an error naming the offending field so the
- *     operator can fix `.agentrc.json` without spelunking the schema.
- *   - Well-formed block → return the normalized contract object with
- *     `environments` + `defaultEnvironment` and the two optional fields
- *     (`consoleAllowlist`, `designTokens`) defaulted.
- *
- * `resolveQaEnvironment(contract, target)` selects one environment per
- * harness invocation — by exact name or by raw-URL origin match against each
- * environment's `baseUrl` — and throws loudly (naming the known environments)
- * on an unknown name or unmatched URL.
- *
- * It also **resolves the selected environment's `signInSeam`** (Story #5135).
- * A `{ skill }` seam naming an id that resolves to no readable `SKILL.md`
- * under either skills root used to fail silently: the contract validated, the
- * seam was returned unread, and the dangling pointer only surfaced much later
- * when a sweep reached its sign-in step — after the harness had already
- * driven a browser. Resolution now happens here, at config-resolution time,
- * so the failure lands where the operator can fix `.agentrc.json`. A seam
- * that is absent entirely is a legitimate, declarable state (the workflows
- * drive the unauthenticated surface and record the gap), not an error.
+ * `qa` contract resolver — the single seam the QA harness calls. The block is
+ * optional in the schema (non-QA repos must validate), so presence is enforced
+ * here at run time, loudly: an absent block, a malformed field, or a dangling
+ * `signInSeam.skill` throws an operator-actionable error; there is no silent
+ * fallback.
  */
 
 import Ajv from 'ajv';
@@ -47,13 +15,8 @@ import {
 } from '../skills/walk-skill-files.js';
 
 /**
- * The harness-required fields. The AJV `QA_SCHEMA` keeps these optional so
- * the full-document validator never rejects a non-QA consumer; the harness
- * contract, however, is meaningless without all four, so the resolver
- * enforces them here. Keeping the list adjacent to the resolver (not in the
- * schema) is deliberate: the schema validates *shape* for any repo, the
- * resolver enforces *harness-binding completeness* only when the harness is
- * actually invoked.
+ * Optional in the schema (shape for any repo), required here (binding
+ * completeness only when the harness actually runs).
  */
 export const QA_REQUIRED_FIELDS = Object.freeze([
   'featureRoot',
@@ -62,16 +25,10 @@ export const QA_REQUIRED_FIELDS = Object.freeze([
   'personas',
 ]);
 
-/**
- * The environment name whose `allowWrites` defaults to `true` when the
- * consumer omits the flag. Every other environment defaults to read-only
- * (`allowWrites: false`) so an unguarded remote target cannot accept writes
- * by accident — only the conventional `local` environment is write-enabled
- * by default.
- */
+// The only environment whose `allowWrites` defaults to true; every other
+// target is read-only unless the consumer opts in.
 const WRITE_ENABLED_DEFAULT_ENVIRONMENT = 'local';
 
-/** Defaults applied to the optional fields of a well-formed contract. */
 export const QA_CONTRACT_DEFAULTS = Object.freeze({
   consoleAllowlist: Object.freeze([]),
   designTokens: null,
@@ -93,16 +50,8 @@ function getQaValidator() {
 }
 
 /**
- * Normalize the two accepted `personas` shapes to one canonical internal
- * form (Story #3306).
- *
- * The schema accepts either a plain `string[]` of persona names (the honest
- * shape for a `urlTemplate` dev-impersonation seam, where the workflow reads
- * only the persona name) or the object-map form keyed by persona name (each
- * entry carrying `credentialRef` / `signInSkill` for a `skill`/credential
- * seam). Downstream the workflow consumes only the persona *names*, so the
- * canonical internal form is an object map keyed by persona name. A name-only
- * persona maps to an empty record — it carries no fabricated auth material.
+ * Normalize `string[]` or object-map personas to an object map; a name-only
+ * persona maps to `{}` (no fabricated auth material).
  *
  * @param {string[] | Record<string, object>} personas Either accepted shape.
  * @returns {{ personas: Record<string, object>, personaNames: string[] }}
@@ -115,7 +64,6 @@ function normalizePersonas(personas) {
     }
     return { personas: map, personaNames: [...personas] };
   }
-  // Object-map form: clone each entry so callers cannot mutate the input.
   const map = {};
   for (const [name, material] of Object.entries(personas)) {
     map[name] = { ...material };
@@ -124,15 +72,10 @@ function normalizePersonas(personas) {
 }
 
 /**
- * Render an AJV error into an actionable, field-named sentence.
- *
  * @param {import('ajv').ErrorObject} err
  * @returns {string}
  */
 function describeError(err) {
-  // `instancePath` is e.g. "/featureRoot" or "/signInSeam"; strip the
-  // leading slash so the message reads `qa.featureRoot ...`. A top-level
-  // error (empty path) describes the block itself.
   const field = err.instancePath ? err.instancePath.replace(/^\//, '') : '';
   const dotted = field ? `qa.${field.replace(/\//g, '.')}` : 'qa';
   if (err.keyword === 'additionalProperties') {
@@ -143,16 +86,8 @@ function describeError(err) {
 }
 
 /**
- * Resolve, validate, and normalize the `qa` contract block.
- *
- * Accepts either the full resolved config wrapper (`{ qa, project, ... }`)
- * or the bare `qa` bag. Returns a fresh normalized object — callers must not
- * mutate the input.
- *
- * `personas` is accepted in either shape (a `string[]` of names or the
- * object-map form) and normalized to one canonical internal form: an object
- * map keyed by persona name. A `personaNames` array is also returned for the
- * common case (url-template seam) where only the names are consumed.
+ * Accepts the full config or the bare `qa` bag; returns a fresh normalized
+ * contract.
  *
  * @param {object | null | undefined} config Full resolved config or bare qa block.
  * @returns {{
@@ -174,10 +109,7 @@ export function resolveQaContract(config) {
     throw new Error(ABSENT_MESSAGE);
   }
 
-  // Distinguish "absent" from "malformed": a block that is missing *every*
-  // harness-required field is treated as absent (the operator scaffolded an
-  // empty `qa: {}` but never bound it), so it gets the loud no-fallback
-  // message rather than a field-by-field validation dump.
+  // A scaffolded `qa: {}` with no required field is "absent", not malformed.
   const presentRequired = QA_REQUIRED_FIELDS.filter(
     (key) => qa[key] !== undefined,
   );
@@ -185,15 +117,13 @@ export function resolveQaContract(config) {
     throw new Error(ABSENT_MESSAGE);
   }
 
-  // Malformed-shape check first (AJV), so a wrong-typed field is reported by
-  // name even when a required field is also missing.
+  // Shape first, so a wrong-typed field is named even when another is missing.
   const validate = getQaValidator();
   if (!validate(qa)) {
     const detail = (validate.errors || []).map(describeError).join('; ');
     throw new Error(`qa: malformed contract — ${detail}`);
   }
 
-  // Required-field completeness, naming the first missing field.
   const missing = QA_REQUIRED_FIELDS.filter((key) => qa[key] === undefined);
   if (missing.length > 0) {
     throw new Error(
@@ -205,15 +135,12 @@ export function resolveQaContract(config) {
 
   const { personas, personaNames } = normalizePersonas(qa.personas);
 
-  // Clone each environment so callers cannot mutate the resolver's input.
   const environments = {};
   for (const [name, env] of Object.entries(qa.environments)) {
     environments[name] = { ...env };
   }
 
-  // The default environment is the conventional `local` target when present,
-  // otherwise the first-declared environment. `resolveQaEnvironment(contract)`
-  // (no target) resolves to this one.
+  // `local` when declared, else the first-declared environment.
   const environmentNames = Object.keys(environments);
   const defaultEnvironment = Object.hasOwn(
     environments,
@@ -240,11 +167,6 @@ export function resolveQaContract(config) {
 }
 
 /**
- * Normalize a value to its URL origin (`protocol//host:port`), or `null` when
- * it is not a parseable absolute URL. Used to match a raw-URL `target` against
- * each environment's `baseUrl` by origin, so a target carrying a path,
- * query-string, or trailing slash still resolves to the right environment.
- *
  * @param {string} value
  * @returns {string | null}
  */
@@ -257,21 +179,11 @@ function toOrigin(value) {
 }
 
 /**
- * Normalize and verify one environment's `signInSeam`.
- *
- * An absent seam normalizes to `null` — a declarable state, not an error.
- * A `{ skill }` seam is resolved against both skills roots and throws when
- * it resolves under neither, so a dangling pointer is caught here rather
- * than mid-sweep. The resolved `SKILL.md` path is attached as
- * `skillPath` so the harness reads the file the check actually found.
- *
- * The two failures get **different** messages (Story #5285). A well-formed id
- * that resolves nowhere is a skill to author; a malformed one is an id to
- * fix, and telling the operator to author `../../secrets/SKILL.md` would be
- * advice they cannot take. A config validated against the shipped schema
- * never reaches the malformed branch — the `pattern` rejects it first — but
- * this resolver also runs over hand-assembled contracts in tests and over
- * configs loaded past a degraded validator, so the branch is real.
+ * An absent seam is a declarable `null`. A `{ skill }` seam must resolve
+ * under a skills root now, not mid-sweep after a browser was driven; the
+ * resolved path is attached as `skillPath`. A malformed id and an unresolved
+ * one get different messages because they need different fixes (the
+ * malformed branch is reachable past a degraded validator).
  *
  * @param {object | undefined} seam
  * @param {string} envName Environment name, for the error message.
@@ -309,32 +221,15 @@ function resolveSignInSeam(seam, envName, options) {
 }
 
 /**
- * Resolve a single QA environment for one harness invocation.
- *
- * `target` selects which of the contract's `environments` to run against:
- *   - **Omitted / falsy** → the contract's `defaultEnvironment`.
- *   - **Exact environment name** → that environment.
- *   - **Raw URL** → the environment whose `baseUrl` shares the same origin
- *     (`protocol//host:port`), so a target with a path or query still matches.
- *
- * Resolution is name-first: a `target` that exactly names an environment wins
- * even if it also happens to parse as a URL.
- *
- * `allowWrites` is resolved to an explicit boolean on the returned object: the
- * environment's own value when set, otherwise `true` only for the conventional
- * `local` environment and `false` for every other target — an unguarded remote
- * environment is read-only unless the consumer opts in.
- *
- * Fails **loudly**: an unknown name or an unmatched URL throws an error that
- * names the known environments so the operator can correct the invocation.
+ * Select one environment: omitted → default; exact name (wins even if it
+ * parses as a URL); else a raw URL matched by origin against each `baseUrl`.
+ * `allowWrites` resolves to an explicit boolean.
  *
  * @param {{ environments: Record<string, { baseUrl: string, signInSeam?: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
  *   A contract returned by `resolveQaContract`.
- * @param {string} [target] Environment name or raw URL. Omit for the default.
- * @param {{ repoRoot?: string }} [options] `repoRoot` roots skill-seam
- *   resolution; defaults to the project root. Injected by tests.
+ * @param {string} [target] Environment name or raw URL.
+ * @param {{ repoRoot?: string }} [options] Roots skill-seam resolution.
  * @returns {{ name: string, baseUrl: string, signInSeam: object | null, allowWrites: boolean }}
- *   `signInSeam` is `null` when the environment declares none.
  * @throws {Error} on an unknown name, an unmatched URL, or a `{ skill }` seam
  *   that resolves under no skills root.
  */
@@ -354,15 +249,11 @@ export function resolveQaEnvironment(contract, target, options = {}) {
   const known = Object.keys(environments);
   const knownList = known.map((name) => `\`${name}\``).join(', ');
 
-  // No target → the default environment.
   const name =
     target == null || target === '' ? contract.defaultEnvironment : target;
 
-  // Exact-name match wins first (a name that also parses as a URL still
-  // resolves by name).
   let resolvedName = Object.hasOwn(environments, name) ? name : null;
 
-  // Otherwise try to match the target as a raw URL against each baseUrl origin.
   if (resolvedName === null) {
     const targetOrigin = toOrigin(name);
     if (targetOrigin !== null) {

package/.agents/scripts/lib/qa/resolve-selection.js

@@ -1,41 +1,14 @@
 /**
- * resolve-selection.js — scenario-selection resolver for the agent-driven
- * QA harness (Epic #3214, Story #3296).
+ * resolve-selection.js — turns a QA harness selector into a concrete,
+ * deterministic scenario set under `featureRoot`:
  *
- * The harness is invoked with a single selector that scopes a sweep to a
- * concrete set of `.feature` files (and, for tag selectors, the specific
- * scenarios within them) under the contract's `featureRoot`. This module
- * turns one of three selector shapes into that concrete set:
+ *   - `{ kind: 'feature', id }` — one file whose stem or root-relative path
+ *     equals `id` (case-insensitive; ambiguity throws);
+ *   - `{ kind: 'tag', expression }` — scenarios satisfying a cucumber-style
+ *     `@tag` / and / or / not / parens expression;
+ *   - `{ kind: 'domain', name }` — every scenario at or below `<root>/<name>/`.
  *
- *   - **feature id** — `{ kind: 'feature', id: 'login' }` resolves to the
- *     single `.feature` file whose path stem (basename without the
- *     `.feature` extension) equals the id, or whose `featureRoot`-relative
- *     POSIX path (with or without the extension) equals the id. Matching is
- *     exact and case-insensitive; ambiguous ids (more than one match) throw.
- *
- *   - **tag expression** — `{ kind: 'tag', expression: '@smoke and not @wip' }`
- *     resolves to the scenario set whose tag list satisfies the boolean
- *     expression. The expression grammar is the cucumber-common subset:
- *     `@tag` atoms, `and` / `or` / `not` operators (case-insensitive), and
- *     parentheses. A scenario inherits no implicit tags; only the tags the
- *     scanner attached to it (feature-level + scenario-level, as collected
- *     by `parseFeatureBody`) participate.
- *
- *   - **domain** — `{ kind: 'domain', name: 'billing' }` resolves to every
- *     scenario under the `featureRoot`-relative subdirectory `name`. A
- *     domain is a first-level (or nested) directory grouping beneath the
- *     feature root; the selector matches any scenario whose file lives at
- *     or below `<featureRoot>/<name>/`.
- *
- * Determinism is load-bearing — the QA harness re-runs the same selector
- * across sweeps and must scope the identical scenario set each time. All
- * outputs are sorted by `(file, line)` so the order never depends on
- * filesystem iteration order.
- *
- * This module is pure resolution: it does no browser work, reads no config
- * beyond the `featureRoot` passed in, and never mutates state. The harness
- * workflow (Story #3297) consumes the resolved set; this layer only answers
- * "which scenarios does this selector name?".
+ * Output is sorted by `(file, line)` so re-runs scope the identical set.
  */
 
 import path from 'node:path';
@@ -43,9 +16,6 @@ import path from 'node:path';
 import { listFeatureFiles, scanBddScenarios } from '../bdd-scenario-scanner.js';
 
 /**
- * Normalise a path to POSIX separators so `featureRoot`-relative matching
- * behaves identically on Windows and POSIX hosts.
- *
  * @param {string} p
  * @returns {string}
  */
@@ -54,10 +24,6 @@ function toPosix(p) {
 }
 
 /**
- * Compute a scenario's `featureRoot`-relative POSIX path. Used by the
- * feature-id and domain matchers so selectors are written against the
- * stable, repo-relative shape rather than absolute worktree paths.
- *
  * @param {string} featureRoot - Absolute path to the feature root.
  * @param {string} file - Absolute path to a `.feature` file.
  * @returns {string} POSIX-style path relative to `featureRoot`.
@@ -67,9 +33,6 @@ function relFromRoot(featureRoot, file) {
 }
 
 /**
- * Strip the trailing `.feature` extension (case-insensitive) from a
- * relative path, leaving the path stem the feature-id selector matches on.
- *
  * @param {string} relPath
  * @returns {string}
  */
@@ -77,15 +40,7 @@ function stripFeatureExt(relPath) {
   return relPath.replace(/\.feature$/i, '');
 }
 
-// ---------------------------------------------------------------------------
-// Tag-expression evaluation
-// ---------------------------------------------------------------------------
-
 /**
- * Classify a single matched lexeme into a token. `@tag` atoms keep their
- * raw value; `(` / `)` / `and` / `or` / `not` produce structural tokens.
- * Anything else is a malformed expression and throws.
- *
  * @param {string} raw
  * @returns {{ type: string, value?: string }}
  */
@@ -106,10 +61,6 @@ function classifyToken(raw) {
 }
 
 /**
- * Tokenise a cucumber-style tag expression into a flat token stream.
- * Recognised tokens: `(`, `)`, `and`, `or`, `not`, and `@tag` atoms.
- * Whitespace separates tokens; parentheses need no surrounding space.
- *
  * @param {string} expression
  * @returns {Array<{ type: string, value?: string }>}
  */
@@ -122,7 +73,6 @@ function tokenizeTagExpression(expression) {
     match !== null;
     match = re.exec(expression)
   ) {
-    // Guard against runs of unmatched garbage between tokens.
     const between = expression.slice(lastIndex, match.index).trim();
     if (between.length > 0) {
       throw new Error(
@@ -142,15 +92,13 @@ function tokenizeTagExpression(expression) {
 }
 
 /**
- * Recursive-descent parser for the tag-expression grammar:
+ * Recursive descent:
  *
  *   expr   := term  ( 'or'  term  )*
  *   term   := factor( 'and' factor)*
  *   factor := 'not' factor | '(' expr ')' | tag
  *
- * Produces a predicate `(tagSet: Set<string>) => boolean`. Tag atoms match
- * case-insensitively against the scenario's tag set (which carries the
- * leading `@`).
+ * Tag atoms match case-insensitively (with the leading `@`).
  *
  * @param {string} expression
  * @returns {(tags: Set<string>) => boolean}
@@ -226,9 +174,6 @@ export function parseTagExpression(expression) {
 }
 
 /**
- * Build a lower-cased tag `Set` for a scanned scenario so the predicate can
- * test membership case-insensitively.
- *
  * @param {{ tags?: string[] }} scenario
  * @returns {Set<string>}
  */
@@ -236,13 +181,7 @@ function tagSetOf(scenario) {
   return new Set((scenario.tags ?? []).map((t) => t.toLowerCase()));
 }
 
-// ---------------------------------------------------------------------------
-// Public resolver
-// ---------------------------------------------------------------------------
-
 /**
- * Sort scanned scenarios deterministically by `(file, line)`.
- *
  * @param {Array<{ file: string, line: number }>} scenarios
  * @returns {Array<object>}
  */
@@ -255,21 +194,15 @@ function sortScenarios(scenarios) {
 }
 
 /**
- * Resolve a selector into a concrete scenario set under `featureRoot`.
- *
  * @param {object} args
  * @param {string} args.featureRoot - Absolute path to the contract's
- *   `.feature` root. The harness prefers the `qa.featureRoot` contract
- *   value over auto-detection; this resolver takes it as given.
- * @param {object} args.selector - One of the three selector shapes:
- *   `{ kind: 'feature', id }`, `{ kind: 'tag', expression }`, or
- *   `{ kind: 'domain', name }`.
+ *   `.feature` root.
+ * @param {object} args.selector - `{ kind: 'feature', id }`,
+ *   `{ kind: 'tag', expression }`, or `{ kind: 'domain', name }`.
  * @param {{ logger?: object }} [opts]
  * @returns {{ kind: string, featureRoot: string, files: string[], scenarios: Array<object> }}
- *   `files` is the deduped, sorted set of absolute `.feature` paths the
- *   selection touches; `scenarios` is the sorted scenario rows (for tag
- *   selection it is the satisfying subset, for feature/domain it is every
- *   scenario in the matched files).
+ *   `scenarios` is the satisfying subset for tags, every scenario in the
+ *   matched files otherwise.
  */
 export function resolveSelection(args = {}, opts = {}) {
   const { featureRoot, selector } = args;
@@ -351,8 +284,7 @@ function resolveDomain(featureRoot, selector, opts) {
       '[resolve-selection] domain selector requires a non-empty name',
     );
   }
-  // Normalise to a trailing-slash POSIX prefix so "billing" matches
-  // "billing/checkout.feature" but not "billing-archive/x.feature".
+  // Trailing slash so "billing" never matches "billing-archive/".
   const prefix = `${toPosix(name.trim()).replace(/\/+$/, '')}/`;
   const all = scanBddScenarios({ featureRoots: [featureRoot], ...opts });
   const scenarios = sortScenarios(

package/.agents/scripts/lib/reserved-test-ids.js

@@ -1,48 +1,20 @@
 /**
- * lib/reserved-test-ids.js — the framework's one declaration of which
- * Epic / Story ids are **synthetic** (Story #4892).
- *
- * The band `999000–999999` has been reserved for test fixtures since the
- * post-test temp reaper shipped, but it lived as a private regexp inside
- * `cleanup-repo-test-temp.js` (`/^epic-999\d{3}$/`) and nothing else could
- * consult it. Two independent surfaces need the same rule, and spelling it
- * twice is how they would drift:
- *
- *   1. **Write side.** A test that spawns a real CLI at the repository root
- *      inherits the real state directory, so its fixture telemetry can land
- *      in the operator's live `temp/` signals tree. The post-run guard in
- *      `check-test-temp-hygiene.js` fails the run when a stream file owned by
- *      a reserved id survives there.
- *   2. **Read side.** The retro composer renders the distinct Stories a
- *      friction bucket spans as recurrence evidence in a body that is filed
- *      as a real GitHub issue. A reserved id is synthetic by construction, so
- *      it can never be resolved to a real issue and must never be published
- *      as evidence (issue #4870 named `#999999` as a contributing Story).
- *
- * Deliberately dependency-free: the write side is a CLI guard and the read
- * side is a pure composer, so the shared rule must not drag config, fs, or
- * git resolution into either.
+ * lib/reserved-test-ids.js — the one declaration of the synthetic
+ * test-fixture id band, shared by the temp-pollution guard and the retro
+ * composer (which must never publish a synthetic id as evidence).
+ * Dependency-free on purpose.
  */
 
-/** First id in the reserved test-fixture band. */
 const RESERVED_TEST_ID_MIN = 999000;
 
-/** Last id in the reserved test-fixture band. */
 const RESERVED_TEST_ID_MAX = 999999;
 
-/**
- * Human-readable band, for guard failure messages that have to tell an
- * operator which ids they may not use for real work.
- */
+/** For guard messages naming the ids real work may not use. */
 export const RESERVED_TEST_ID_BAND = `${RESERVED_TEST_ID_MIN}–${RESERVED_TEST_ID_MAX}`;
 
 /**
- * Is `id` inside the reserved test-fixture band?
- *
- * Exact-band membership, because this is the predicate the temp reaper and
- * the pollution guard share: both classify an on-disk directory that a test
- * created, and over-reaching (treating every large id as reserved) would let
- * one of them delete or condemn a directory the band never claimed.
+ * Exact-band membership: the reaper and the guard act on on-disk dirs, and
+ * over-reaching would delete or condemn one the band never claimed.
  *
  * @param {unknown} id
  * @returns {boolean}
@@ -56,18 +28,8 @@ export function isReservedTestId(id) {
 }
 
 /**
- * May `id` be published as ticket evidence in operator-visible output?
- *
- * The floor is the reserved band, not the band itself: an id at or above
- * `RESERVED_TEST_ID_MIN` is synthetic by construction (the framework reserves
- * that space for fixtures, and no repository has minted that many issues), so
- * nothing at or beyond the floor can be resolved to a real issue. A
- * non-integer or non-positive id is not a ticket reference at all.
- *
- * This is a plausibility bound, not an existence probe: it is the strongest
- * statement a caller with no ticket-provider access can make, and it is what
- * keeps the invariant true at every call site instead of only where somebody
- * remembered to wire a probe.
+ * A plausibility bound, not an existence probe: anything at or above the
+ * band floor is synthetic, and non-positive ids are not references.
  *
  * @param {unknown} id
  * @returns {boolean}

package/.agents/scripts/lib/runtime-deps/dep-resolution.js

@@ -1,30 +1,16 @@
 /**
- * runtime-deps/dep-resolution — is a declared runtime dependency actually
- * there, is it the right major, and how do we say so.
- *
- * `.agents/` materializes into the consumer's repository root, so every
- * framework runtime dependency resolves from *their* `node_modules`. A range
- * in `.agents/runtime-deps.json` therefore documents a requirement it cannot
- * enforce, and the preflight guard needs to compare the range against what
- * actually resolved.
- *
- * Deliberately major-only, and deliberately not `semver`. The framework's
- * runtime ranges are all `^`, whose whole contract is "this major"; pulling in
- * a semver implementation to decide one comparison would add a dependency to
- * the very closure this module exists to keep honest.
+ * runtime-deps/dep-resolution — is a declared runtime dependency present and
+ * the right major. Deps resolve from the consumer's `node_modules`, so a
+ * declared range is only enforced by comparing it to what resolved.
+ * Major-only and semver-free on purpose: every range is `^`, and a semver
+ * dependency would grow the very closure this guards.
  *
  * @module lib/runtime-deps/dep-resolution
  */
 
 /**
- * Leading major number of a version or a caret/tilde range, or `null`.
- *
- * Module-local: `majorMismatch` is the only question callers have.
- *
- * Anything this cannot read as `<major>.` — `*`, a tag, a git URL, a
- * `>=x <y` span — yields `null` and is treated as "not range-checked". That
- * asymmetry is intentional: a conservative miss is a no-op, while a false
- * positive blocks a working install.
+ * Anything not `<major>.`-shaped yields `null` (not range-checked): a
+ * conservative miss is a no-op, a false positive blocks a working install.
  *
  * @param {string|null|undefined} spec
  * @returns {number|null}
@@ -36,18 +22,8 @@ function majorOf(spec) {
 }
 
 /**
- * Does `resolved` sit outside the major `range` names?
- *
- * Module-local: `checkRuntimeDeps` is the only caller, and exporting it only
- * for a test would be a production-dead export.
- *
- * `false` whenever either side is unreadable, so an unparseable range or an
- * unreadable installed version is never reported as a mismatch.
- *
- * `0.x` majors compare as written: `^0.1.0` and `0.2.1` differ in minor, not
- * major, so this does not separate them. Accepted — the `0.x` packages in the
- * closure are terminal, and the range this exists to enforce is
- * `@babel/parser`'s `^7`.
+ * `false` when either side is unreadable. `0.x` minors are not separated —
+ * accepted, since the range this enforces is `@babel/parser`'s `^7`.
  *
  * @param {string|null|undefined} range
  * @param {string|null|undefined} resolved
@@ -62,14 +38,8 @@ function majorMismatch(range, resolved) {
 }
 
 /**
- * Is a package present in the resolvable tree?
- *
- * The bare specifier is tried first, then `<name>/package.json`. The fallback
- * is not belt-and-braces: a package with no `main` and no `exports` — which
- * `typhonjs-escomplex-commons` and `babel-runtime` both are — cannot be
- * resolved by name at all, and is reached only by deep path. Probing the bare
- * name alone would report such a package missing while it sits installed, and
- * this guard exits the process on that verdict.
+ * Falls back to `<name>/package.json`: a package with no `main`/`exports`
+ * cannot be resolved by name, and reporting it missing would exit the process.
  *
  * @param {string} dep
  * @param {(specifier: string) => string} resolve
@@ -91,13 +61,8 @@ export function isResolvable(dep, resolve) {
 }
 
 /**
- * Remediation text for a resolved dependency whose major differs from the
- * range the framework declares.
- *
- * Named separately from the missing-deps message because the remedy differs:
- * the package is installed, so installing again changes nothing. What is
- * wrong is the version the consumer's own tree resolves, which only they can
- * change.
+ * Distinct from the missing-deps message: reinstalling changes nothing, only
+ * the consumer can pin a compatible major.
  *
  * @param {{name: string, required: string, resolved: string}[]} mismatched
  * @param {{ root: string }} ctx
@@ -119,11 +84,6 @@ export function formatMismatchedDepsMessage(mismatched, { root }) {
 }
 
 /**
- * Resolve each required package via the injected `resolve` seam and collect
- * the ones that fail. `resolve` is typically `require.resolve` bound to the
- * framework module location; it throws `MODULE_NOT_FOUND` when a package is
- * absent from the resolvable `node_modules`.
- *
  * @param {{ required: string[], resolve: (specifier: string) => string }} opts
  * @returns {{ ok: boolean, missing: string[] }}
  */