@dzhechkov/harness-core 0.8.45 → 0.8.47

package/src/index.ts

@@ -19,6 +19,8 @@ export { REPOSITORY_ORIGIN } from './repository-origin.js';
 export { noSearchableTermsReason } from '@dzhechkov/memory';
 
 export * from './skills.js';
+export { buildStageUsageReport } from './stage-usage.js';
+export { deriveStageUsageReport, renderStageUsageReport } from './cost-ledger.js';
 export * from './apply.js';
 export {
   buildPublicSnapshot,
@@ -175,6 +177,8 @@ export {
   parseBridgeOutput,
   buildBridgeFailureRecord,
   renderBridgeReport,
+  resolveBridgeRoundIdentity,
+  selectQeBridgeRoundSignoff,
 } from './qe-bridge.js';
 export type { BridgeFamily, BridgeFailureReason, BridgeFinding, BridgeSignoff, BridgeParse, BridgeParseOk, BridgeParseFail, BridgeChannels, BridgeAudit, ClaudeResultExtraction, NamedExtract, BridgePromptInput } from './qe-bridge.js';
 export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, RecallPatternsOptions, RecordLessonFormsResult, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.js';
@@ -325,8 +329,8 @@ export type {
   StoreGuardPrunePlan,
   StoreGuardPruneDeps,
 } from './store-guard-prune.js';
-export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStateDir, featureAdrStatePath, writeFeatureAdrStateDetailed, renderFeatureAdrPhaseLine } from './statusline.js';
-export type { StatuslineData, StatuslineStoreHealth, FeatureAdrState, WriteFeatureAdrStateInput, WriteFeatureAdrStateResult } from './statusline.js';
+export { statuslineData, readFeatureAdrObservation, readFeatureAdrState, writeFeatureAdrState, featureAdrStateDir, featureAdrStatePath, writeFeatureAdrStateDetailed, renderFeatureAdrPhaseLine } from './statusline.js';
+export type { StatuslineData, StatuslineStoreHealth, FeatureAdrObservation, FeatureAdrSelector, FeatureAdrState, WriteFeatureAdrStateInput, WriteFeatureAdrStateResult } from './statusline.js';
 export {
   ETA_MAX_STAGE_MS,
   estimateEta,
@@ -782,7 +786,7 @@ export type {
 } from './event-chain.js';
 export { packArtifact, readWorkspaceVersions, UnknownWorkspaceSpecError } from './pack-artifact.js';
 export type { PackArtifactResult, ExecLike } from './pack-artifact.js';
-export { decideProvenance, environmentCanMintProvenance, publishArgv, matchesPublishFilter, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, rewriteWorkspaceSpecs, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion, planReadmeVersionSync } from './publish.js';
+export { decideProvenance, environmentCanMintProvenance, publishArgv, matchesPublishFilter, validatePublishFilters, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, rewriteWorkspaceSpecs, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion, planReadmeVersionSync } from './publish.js';
 export type { ReadmeVersionSyncPlan, ReadmeSyncRewrite } from './publish.js';
 export { RELEASE_LINE_RE, parseReleaseLine, findReleaseLine, rewriteReleaseLine, shortPackageName } from './release-line.js';
 export type { ReleaseLineToken, ReleaseLineParse, ReleaseLineMatch } from './release-line.js';
@@ -958,6 +962,8 @@ export {
   PLAN_GATE_SCRIPT,
   planCompletenessGateCmd,
   parsePlanGateVerdict,
+  // landed-barrier-anchored-line: the design/plan/plan-repair landing-barrier reply parser.
+  parseLandedProbe,
   // p16-non-js-portability: the gate-script search chain's operator note (ADR-002/AM-7) and the
   // dzBin absolutization (ADR-003). Named for the same reason as the three above.
   refusalNoteFor,
@@ -1036,6 +1042,7 @@ export type {
   ParsedBaselineCapture,
   ParsedLandingSignal,
   PlanGateVerdict,
+  LandedProbeVerdict,
   PlanSnapshot,
   PlanGateCmdOpts,
   CodexReviewCommandInput,
@@ -1156,6 +1163,8 @@ export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';
 export * from './guard-volume.js';
+// npm-homepage-guard (backlog e5d0d383): pure facts + fs reader for the `npm-homepage` guard rule.
+export * from './npm-homepage.js';
 // Root AGENTS.md policy projection: pure anchor extraction/render/hash drift +
 // the shared-emitter I/O entry point exported from operations.
 export * from './agents-policy.js';
@@ -1368,6 +1377,10 @@ export { parseQeBridgeStdoutCost } from './review-cost.js';
 export type { QeBridgeCost, QeBridgeCostTokens } from './review-cost.js';
 export { parseCodexTokens, classifyRoundExecOutcome, buildRoundExecRow } from './round-exec.js';
 export type { RoundExecOutcome, RoundExecLedgerRow } from './round-exec.js';
+// round-exec-claim-takeover FR-1: the pure verdict `dz round exec` consults before refusing a
+// standing exec claim (held / stale-dead / unknown); the pid probe itself stays in run-registry.
+export { decideExecClaimTakeover } from './round-exec-claim.js';
+export type { ExecClaimVerdict, ExecClaimTakeoverInput } from './round-exec-claim.js';
 export * from './run-cleanup.js';
 
 export * from './cross-family-control.js';
@@ -1380,3 +1393,6 @@ export { decideTestReceipt, renderTestReceiptVerdict } from './test-receipt.js';
 export type { TestReceipt, TestReceiptVerdict, TestReceiptScopeState } from './test-receipt.js';
 export { decideBackupFreshness, renderBackupFreshness } from './backup-freshness.js';
 export type { BackupFreshnessVerdict } from './backup-freshness.js';
+
+export { planReleasePackageAudit, judgeReleasePackageAudit, judgeReleaseCohortAudit } from './release-package-audit.js';
+export type { ReleasePackageAuditPlan, ReleasePackageAuditResult, ReleaseWorkspaceAuditReport } from './release-package-audit.js';

package/src/loop-plan.ts

@@ -1489,6 +1489,10 @@ export function toTraceProjection(plan: LoopPlan): TraceProjection {
 /** One dispatching step as the scheduler needs it — everything it must know to build a prompt,
  * pick a model, spend budget, retry, and verify a deliverable landed. */
 export interface RunStepSpec {
+  role?: string | null;
+  tier?: string | null;
+  mode?: string | null;
+  estimate?: unknown;
   stepId: string;
   kind: 'agent' | 'gate';
   phase: string;
@@ -1574,6 +1578,10 @@ export function toRunProjection(plan: LoopPlan): RunProjection {
       stepId: s.stepId,
       kind: s.kind === 'gate' ? 'gate' : 'agent',
       phase: s.phase,
+      role: typeof s['x-role'] === 'string' ? s['x-role'] : null,
+      tier: typeof s['x-tier'] === 'string' ? s['x-tier'] : null,
+      mode: typeof s['x-mode'] === 'string' ? s['x-mode'] : null,
+      estimate: s['x-estimate'] ?? null,
       prompt: typeof s.prompt === 'string' ? s.prompt : null,
       model: typeof s.model === 'string' && s.model !== '' ? s.model : null,
       deliverable: s.deliverable ?? 'return-value',

package/src/mutation-gate.ts

@@ -121,6 +121,51 @@ export interface InjectVitestWorkerCeilingResult {
   /** segments where `vitest run` was found only by the LOOSE token-pair fallback (command position
    * unrecognised) — the CLI reports these so an odd wrapper shape is visible, not silent. */
   readonly looseSegments: number;
+  /**
+   * vitest-ceiling-injection-hardening FR-1: set when the command cannot be split with confidence —
+   * an UNTERMINATED quote leaves both the segment boundaries and the argument ends to guesswork (a
+   * swallowed `&&` would move a boundary). The command is then returned byte-identical, all counts
+   * are 0, and the reason is named here — never a best-effort injection. Absent on the normal path.
+   */
+  readonly notEstablished?: VitestInjectionNotEstablished;
+}
+
+/** vitest-ceiling-injection-hardening FR-1: why the injection was not attempted. */
+export interface VitestInjectionNotEstablished {
+  readonly reason: 'unterminated-single-quote' | 'unterminated-double-quote' | 'unsupported-shell-construct';
+  /**
+   * set only for `unsupported-shell-construct` (astra r1, MAJOR 1): the construct the scanner does NOT
+   * model — reading the quotes inside it as ordinary quotes gave valid commands a false
+   * `unterminated-*` reason. Deliberately a refusal, not a parser: heuristic shell parsing does not converge.
+   */
+  readonly construct?: UnsupportedShellConstruct;
+  /** human-readable, names the quote kind / construct and the raw offset where it starts. */
+  readonly message: string;
+}
+
+/** shell constructs `splitUnquotedSegments` detects and REFUSES rather than models. */
+export type UnsupportedShellConstruct =
+  | 'comment' // unquoted `#` at a word start
+  | 'heredoc' // unquoted `<<` (also `<<<`)
+  | 'command-substitution' // `$(` unquoted or inside double quotes
+  | 'backtick-substitution' // a backtick unquoted or inside double quotes
+  | 'parameter-expansion' // `${` unquoted or inside double quotes
+  | 'ansi-c-quoting'; // unquoted `$'`
+
+/**
+ * vitest-ceiling-injection-hardening FR-2: the backslash policy. The gate spawns the command with
+ * `shell: true` (`/bin/sh` on POSIX, `cmd.exe` on win32), and the two disagree on `\`: `/bin/sh`
+ * treats it as an escape (so `C:\proj\vitest` unquoted really becomes `C:projvitest` and is not
+ * vitest), `cmd.exe` does not. `win32` here means ONLY: backslash is a literal path character.
+ * cmd.exe quoting (`^` escapes, no single-quote quoting) is NOT modelled — quotes, operators and the
+ * unsupported-construct refusals stay POSIX-shaped on both (astra r1, MAJOR 2). Core never reads
+ * `process.platform` (core-boundary rule A), so the caller passes it; the default is `posix`.
+ */
+export type VitestInjectionPlatform = 'posix' | 'win32';
+
+export interface InjectVitestWorkerCeilingOptions {
+  /** default `'posix'` — HEAD behaviour. `'win32'`: backslash is a literal path character (never an escape, no line continuation); cmd.exe quoting (`^` escapes, no single-quote quoting) is NOT modelled. */
+  readonly platform?: VitestInjectionPlatform;
 }
 
 interface RawSegment {
@@ -129,17 +174,54 @@ interface RawSegment {
   readonly terminator: string;
 }
 
+interface SplitResult {
+  readonly segments: RawSegment[];
+  /** the quote left open at the end of the command, with the raw offset that opened it; null when all closed. */
+  readonly unterminated: { readonly quote: "'" | '"'; readonly offset: number } | null;
+  /** the first construct the scanner does not model, with its raw offset; null when none. Checked before `unterminated`. */
+  readonly unsupported: { readonly construct: UnsupportedShellConstruct; readonly offset: number } | null;
+}
+
+/** `$(` / `${` / backtick — active both unquoted and inside double quotes. */
+function substitutionAt(cmd: string, i: number): UnsupportedShellConstruct | null {
+  const ch = cmd[i];
+  if (ch === '`') return 'backtick-substitution';
+  if (ch === '$' && cmd[i + 1] === '(') return 'command-substitution';
+  if (ch === '$' && cmd[i + 1] === '{') return 'parameter-expansion';
+  return null;
+}
+
 /**
  * Split on unquoted `&&`/`||`/`;`/`|`, preserving each segment's own text (incl. surrounding
  * whitespace). POSIX-escape aware (fix-round 1, F1): outside quotes `\` makes the next character
  * literal (so it can neither open a quote nor start an operator); inside double quotes `\"` and `\\`
  * are recognised escapes that do NOT close the string; inside single quotes nothing is escaped.
+ * With `backslashEscapes` false (win32, vitest-ceiling-injection-hardening FR-2) backslash is a
+ * literal path character everywhere; cmd.exe quoting (`^` escapes, no single-quote quoting) is NOT
+ * modelled. A quote still open at the end is REPORTED, never guessed past (FR-1); a construct the
+ * scanner does not model (comment, heredoc, `$(`, backtick, `${`, `$'`) is REFUSED before that (astra r1).
  */
-function splitUnquotedSegments(cmd: string): RawSegment[] {
+function splitUnquotedSegments(cmd: string, backslashEscapes: boolean): SplitResult {
   const segments: RawSegment[] = [];
   let segStart = 0;
   let inSingle = false;
   let inDouble = false;
+  let quoteOpenedAt = -1;
+  // astra r2: raw indices of characters made literal by an unquoted POSIX `\` — an escaped space
+  // continues the word, so a `#` after it is NOT at a word start (`issue\ #123` is one word).
+  const escapedAt = new Set<number>();
+  /** true when position `at` starts a shell word: string start, or an UNESCAPED whitespace/operator
+   * before it; a `\<newline>` continuation is removed by the shell, so look past it. */
+  const atWordStart = (at: number): boolean => {
+    let prev = at - 1;
+    for (;;) {
+      if (prev < 0) return true;
+      if (escapedAt.has(prev) && cmd[prev] === '\n') { prev -= 2; continue; } // `\<LF>` continuation
+      if (escapedAt.has(prev) && cmd[prev] === '\r' && cmd[prev + 1] === '\n') { prev -= 2; continue; }
+      break;
+    }
+    return !escapedAt.has(prev) && /[\s;&|()<>]/u.test(cmd[prev]!);
+  };
   let i = 0;
   while (i < cmd.length) {
     const ch = cmd[i];
@@ -150,32 +232,47 @@ function splitUnquotedSegments(cmd: string): RawSegment[] {
     }
     if (inDouble) {
       if (ch === '"') { inDouble = false; i += 1; continue; }
-      if (ch === '\\') {
+      if (ch === '\\' && backslashEscapes) {
         const next = cmd[i + 1];
-        // at least \" and \\ (F1's floor) — an escaped quote must not close the double-quoted span.
-        if (next === '"' || next === '\\') { i += 2; continue; }
+        // at least \" and \\ (F1's floor) — an escaped quote must not close the double-quoted span;
+        // \$ and \` are POSIX double-quote escapes too — an escaped `$(` is not a substitution.
+        if (next === '"' || next === '\\' || next === '$' || next === '`') { i += 2; continue; }
         i += 1;
         continue;
       }
+      const inner = substitutionAt(cmd, i);
+      if (inner !== null) return { segments, unterminated: null, unsupported: { construct: inner, offset: i } };
       i += 1;
       continue;
     }
+    if (ch === '\\' && backslashEscapes) {
+      // Outside any quote, POSIX makes the character AFTER `\` literal — skip both so it can never
+      // be mis-read as a quote-open, a construct or an operator boundary.
+      if (cmd[i + 1] !== undefined) escapedAt.add(i + 1);
+      if (cmd[i + 1] === '\r' && cmd[i + 2] === '\n') escapedAt.add(i + 2); // `\<CR><LF>` continuation
+      i += cmd[i + 1] === '\r' && cmd[i + 2] === '\n' ? 3 : cmd[i + 1] !== undefined ? 2 : 1;
+      continue;
+    }
+    // astra r1, MAJOR 1: constructs the scanner does NOT model are refused BEFORE quote tracking can
+    // misread the quotes inside them (a comment's apostrophe, a heredoc body, a nested substitution).
+    const construct: UnsupportedShellConstruct | null = substitutionAt(cmd, i)
+      ?? (ch === '$' && cmd[i + 1] === "'" ? 'ansi-c-quoting'
+        : ch === '<' && cmd[i + 1] === '<' ? 'heredoc'
+        : ch === '#' && atWordStart(i) ? 'comment'
+        : null);
+    if (construct !== null) return { segments, unterminated: null, unsupported: { construct, offset: i } };
     if (ch === "'") {
       inSingle = true;
+      quoteOpenedAt = i;
       i += 1;
       continue;
     }
     if (ch === '"') {
       inDouble = true;
+      quoteOpenedAt = i;
       i += 1;
       continue;
     }
-    if (ch === '\\') {
-      // Outside any quote, POSIX makes the character AFTER `\` literal — skip both so it can never
-      // be mis-read as a quote-open or an operator boundary.
-      i += cmd[i + 1] !== undefined ? 2 : 1;
-      continue;
-    }
     const terminatorMatch = /^(&&|\|\||;|\|)/.exec(cmd.slice(i));
     if (terminatorMatch) {
       segments.push({ text: cmd.slice(segStart, i), terminator: terminatorMatch[0] });
@@ -186,7 +283,10 @@ function splitUnquotedSegments(cmd: string): RawSegment[] {
     i += 1;
   }
   segments.push({ text: cmd.slice(segStart), terminator: '' });
-  return segments;
+  const unterminated = inSingle ? { quote: "'" as const, offset: quoteOpenedAt }
+    : inDouble ? { quote: '"' as const, offset: quoteOpenedAt }
+    : null;
+  return { segments, unterminated, unsupported: null };
 }
 
 interface SegmentToken {
@@ -208,7 +308,7 @@ function isWhitespaceChar(ch: string | undefined): boolean {
  * `<char>` outside any quote, single-quoted content kept verbatim) while `token.end` keeps the RAW
  * source offset so `injectIntoSegment` can still splice into the ORIGINAL text unchanged elsewhere.
  */
-function tokenizeSegment(text: string): SegmentToken[] {
+function tokenizeSegment(text: string, backslashEscapes: boolean): SegmentToken[] {
   const tokens: SegmentToken[] = [];
   let i = 0;
   while (i < text.length) {
@@ -229,7 +329,7 @@ function tokenizeSegment(text: string): SegmentToken[] {
       }
       if (inDouble) {
         if (ch === '"') { inDouble = false; i += 1; continue; }
-        if (ch === '\\') {
+        if (ch === '\\' && backslashEscapes) {
           const next = text[i + 1];
           if (next === '"' || next === '\\') { value += next; i += 2; continue; }
           // not one of the two claimed double-quote escapes: the backslash is literal (F1's floor).
@@ -243,7 +343,7 @@ function tokenizeSegment(text: string): SegmentToken[] {
       }
       if (ch === "'") { inSingle = true; i += 1; continue; }
       if (ch === '"') { inDouble = true; i += 1; continue; }
-      if (ch === '\\') {
+      if (ch === '\\' && backslashEscapes) {
         const next = text[i + 1];
         // POSIX line continuation (lead delta after Codex r2, MEDIUM): `\<newline>` (and `\<CR><LF>`)
         // is REMOVED by the shell, never a literal — a token must not swallow a newline as its value.
@@ -357,8 +457,8 @@ function findVitestRunLooseIndex(tokens: readonly SegmentToken[]): number | null
   return null;
 }
 
-function injectIntoSegment(text: string, maxWorkers: number): { readonly text: string; readonly isVitest: boolean; readonly injected: boolean; readonly loose: boolean } {
-  const tokens = tokenizeSegment(text);
+function injectIntoSegment(text: string, maxWorkers: number, backslashEscapes: boolean): { readonly text: string; readonly isVitest: boolean; readonly injected: boolean; readonly loose: boolean } {
+  const tokens = tokenizeSegment(text, backslashEscapes);
   const strictIdx = findVitestRunCommandIndex(tokens);
   const looseIdx = strictIdx === null ? findVitestRunLooseIndex(tokens) : null;
   const runTokenIdx = strictIdx ?? looseIdx;
@@ -373,13 +473,47 @@ function injectIntoSegment(text: string, maxWorkers: number): { readonly text: s
   return { text: injectedText, isVitest: true, injected: true, loose };
 }
 
-export function injectVitestWorkerCeiling(testCmd: string, maxWorkers: number): InjectVitestWorkerCeilingResult {
-  const segments = splitUnquotedSegments(testCmd);
+export function injectVitestWorkerCeiling(
+  testCmd: string,
+  maxWorkers: number,
+  options: InjectVitestWorkerCeilingOptions = {},
+): InjectVitestWorkerCeilingResult {
+  const backslashEscapes = options.platform !== 'win32';
+  const split = splitUnquotedSegments(testCmd, backslashEscapes);
+  if (split.unsupported !== null) {
+    const { construct, offset } = split.unsupported;
+    return {
+      cmd: testCmd,
+      vitestSegments: 0,
+      injected: 0,
+      looseSegments: 0,
+      notEstablished: {
+        reason: 'unsupported-shell-construct',
+        construct,
+        message: `unsupported shell construct '${construct}' at offset ${offset} — the scanner does not model it, so segment boundaries cannot be established; the command is left unchanged and --maxWorkers is NOT injected`,
+      },
+    };
+  }
+  if (split.unterminated !== null) {
+    const { quote, offset } = split.unterminated;
+    const kind = quote === '"' ? 'double' : 'single';
+    return {
+      cmd: testCmd,
+      vitestSegments: 0,
+      injected: 0,
+      looseSegments: 0,
+      notEstablished: {
+        reason: quote === '"' ? 'unterminated-double-quote' : 'unterminated-single-quote',
+        message: `unterminated ${kind} quote opened at offset ${offset} — segment boundaries cannot be established; the command is left unchanged and --maxWorkers is NOT injected`,
+      },
+    };
+  }
+  const segments = split.segments;
   let vitestSegments = 0;
   let injected = 0;
   let looseSegments = 0;
   const rebuilt = segments.map((segment) => {
-    const result = injectIntoSegment(segment.text, maxWorkers);
+    const result = injectIntoSegment(segment.text, maxWorkers, backslashEscapes);
     if (result.isVitest) vitestSegments += 1;
     if (result.injected) injected += 1;
     if (result.loose) looseSegments += 1;

package/src/npm-homepage.ts

@@ -0,0 +1,142 @@
+/**
+ * npm-homepage — the facts behind the `dz guard` rule of the same name (backlog e5d0d383).
+ *
+ * Owner rule 2026-09-28 (`.claude/rules/npm-homepage.md`): every `packages/@dzhechkov/*` package, public or
+ * private, carries `homepage` = exactly `https://aicoding.space`. The GitHub links are NOT replaced — npm has
+ * one `homepage` field, so the site lives there and GitHub stays in `repository` (url + directory) and in
+ * `bugs.url`, and the package README carries both links. The rule therefore checks all of them: dropping the
+ * GitHub ones while "fixing" homepage is the exact regression the owner's clarification forbids.
+ *
+ * Every accepted value is an EXACT string from a closed list — no URL parsing, no normalisation (fix round 1,
+ * review r1 finding 1: a substring test accepted `https://evil.example/github.com/djd1m/dz-harness`). The lead
+ * measured all 57 manifests: each carries exactly the one value listed below.
+ *
+ * Two halves, so the evaluator is testable without a filesystem:
+ *   - `npmHomepageFacts(records, discovery)` (here) is PURE: records in, per-package problem lists out;
+ *   - `readNpmHomepageRecords(dir)` lives in harness-cli (`cli.ts`): it lists package directories (hidden ones
+ *     included), parses `package.json`, reads `README.md`, and returns every entry it could NOT decide as a
+ *     named discovery failure — a permission error is a failure, never "absent". It is NOT here because
+ *     harness-core's IO ratchet (test/core-boundary.test.ts) forbids a new file importing node:fs —
+ *     MEASURED 2026-09-28: 66 > pinned 65 when it lived here.
+ */
+
+/** The owner's site. Compared by strict equality: a trailing slash, a path or an anchor is a violation. */
+export const NPM_HOMEPAGE_URL = 'https://aicoding.space';
+/** Accepted `repository.url` values — a closed list, compared by strict equality. One entry today. */
+export const NPM_REPOSITORY_URLS: readonly string[] = ['git+https://github.com/djd1m/dz-harness.git'];
+/** The one accepted `bugs.url`. */
+export const NPM_BUGS_URL = 'https://github.com/djd1m/dz-harness/issues';
+const README_SITE = NPM_HOMEPAGE_URL;
+const README_SOURCE = 'https://github.com/djd1m/dz-harness';
+const PACKAGES_PREFIX = 'packages/@dzhechkov/';
+
+/** One package directory as the reader found it. */
+export interface NpmHomepageRecord {
+  /** The directory name under `packages/@dzhechkov/` — the expected tail of `repository.directory`. */
+  readonly dir: string;
+  readonly json?: unknown;
+  readonly parseError?: string;
+  /** README.md text; `null` = the file does not exist; absent = not read (treated as missing). */
+  readonly readme?: string | null;
+  /** README.md exists but could not be read. */
+  readonly readmeError?: string;
+}
+
+/** An entry the reader could not decide (stat/read/existence failed for a reason other than "absent"). */
+export interface NpmHomepageDiscoveryFailure {
+  readonly path: string;
+  readonly reason: string;
+}
+
+/** What the reader saw besides the records. `unreadableRoot` set ⇒ the rule is NOT ESTABLISHED. */
+export interface NpmHomepageDiscovery {
+  readonly failures?: readonly NpmHomepageDiscoveryFailure[];
+  readonly unreadableRoot?: string;
+}
+
+/** The fact the guard rule reads: one entry per package; an empty `problems` list means compliant. */
+export interface NpmHomepageFact {
+  readonly dir: string;
+  /** `name` from package.json when it is a string, else `packages/@dzhechkov/<dir>`. */
+  readonly name: string;
+  readonly problems: readonly string[];
+}
+
+/** The whole evidence set for the rule. */
+export interface NpmHomepageFactSet {
+  readonly packages: readonly NpmHomepageFact[];
+  readonly discoveryFailures: readonly NpmHomepageDiscoveryFailure[];
+  readonly unreadableRoot?: string;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+// Fix round 2 (review r2 finding 2): the two links must be WHOLE URLs outside code. A URL ends at end of line,
+// whitespace, `)`, `]`, `>`, `,`, a quote, or a `.` followed by whitespace/end — so
+// `https://aicoding.space.evil.example` and `https://aicoding.space/x` do not count. The source link may continue
+// with `/` (a legitimate subpath such as `/tree/main/packages/…`), but not with `-imposter`.
+const URL_END = String.raw`(?=$|[\s)\]>,"']|\.(?:\s|$))`;
+const SITE_RE = new RegExp(`https://aicoding\\.space${URL_END}`);
+const SOURCE_RE = new RegExp(`https://github\\.com/djd1m/dz-harness(?=/|${URL_END.slice(3)}`);
+const FENCE_RE = /^\s{0,3}(```|~~~)/;
+
+/** One README line, outside fenced code and outside inline-code spans, carrying BOTH whole links (any order). */
+function readmeProblem(rec: NpmHomepageRecord): string | undefined {
+  if (rec.readmeError !== undefined) return `README.md could not be read (${rec.readmeError})`;
+  if (typeof rec.readme !== 'string') return 'README.md is missing — it must carry a line with both the site and the GitHub link';
+  let inFence = false;
+  let ok = false;
+  for (const line of rec.readme.split(/\r?\n/)) {
+    if (FENCE_RE.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const prose = line.replace(/`[^`]*`/g, ' ');
+    if (SITE_RE.test(prose) && SOURCE_RE.test(prose)) { ok = true; break; }
+  }
+  return ok ? undefined : `README.md has no line (outside code) carrying both ${README_SITE} and ${README_SOURCE} as whole links`;
+}
+
+/** Pure: evaluate each record against the field and README requirements. Private packages are NOT exempt. */
+export function npmHomepageFacts(records: readonly NpmHomepageRecord[], discovery: NpmHomepageDiscovery = {}): NpmHomepageFactSet {
+  const out: NpmHomepageFact[] = [];
+  for (const rec of Array.isArray(records) ? records : []) {
+    const dir = typeof rec?.dir === 'string' ? rec.dir : '(unknown dir)';
+    const fallbackName = `${PACKAGES_PREFIX}${dir}`;
+    const readme = rec && typeof rec === 'object' ? readmeProblem(rec) : 'record is not an object';
+    if (rec?.parseError !== undefined) {
+      out.push({ dir, name: fallbackName, problems: [`package.json does not parse (${rec.parseError})`, ...(readme ? [readme] : [])] });
+      continue;
+    }
+    const j = rec?.json;
+    if (!isObject(j)) {
+      out.push({ dir, name: fallbackName, problems: ['package.json is not a JSON object', ...(readme ? [readme] : [])] });
+      continue;
+    }
+    const name = typeof j['name'] === 'string' && j['name'] !== '' ? j['name'] : fallbackName;
+    const problems: string[] = [];
+    if (j['homepage'] !== NPM_HOMEPAGE_URL) {
+      problems.push(`homepage = ${JSON.stringify(j['homepage'])}, must be exactly "${NPM_HOMEPAGE_URL}"`);
+    }
+    const repo = j['repository'];
+    const repoUrl = isObject(repo) ? repo['url'] : undefined;
+    if (typeof repoUrl !== 'string' || !NPM_REPOSITORY_URLS.includes(repoUrl)) {
+      problems.push(`repository.url = ${JSON.stringify(repoUrl)}, must be exactly one of ${JSON.stringify(NPM_REPOSITORY_URLS)}`);
+    }
+    const repoDir = isObject(repo) ? repo['directory'] : undefined;
+    if (repoDir !== `${PACKAGES_PREFIX}${dir}`) {
+      problems.push(`repository.directory = ${JSON.stringify(repoDir)}, must be "${PACKAGES_PREFIX}${dir}"`);
+    }
+    const bugs = j['bugs'];
+    const bugsUrl = isObject(bugs) ? bugs['url'] : undefined;
+    if (bugsUrl !== NPM_BUGS_URL) {
+      problems.push(`bugs.url = ${JSON.stringify(bugsUrl)}, must be "${NPM_BUGS_URL}"`);
+    }
+    if (readme !== undefined) problems.push(readme);
+    out.push({ dir, name, problems });
+  }
+  const failures = Array.isArray(discovery?.failures) ? [...discovery.failures] : [];
+  return {
+    packages: out,
+    discoveryFailures: failures,
+    ...(typeof discovery?.unreadableRoot === 'string' ? { unreadableRoot: discovery.unreadableRoot } : {}),
+  };
+}