@dzhechkov/harness-core 0.8.27 → 0.8.29

package/src/guard.ts

@@ -21,6 +21,7 @@ import {
   type VolumeShadowInput,
   type VolumeShadowResult,
 } from './guard-volume.js';
+import { findReleaseLine } from './release-line.js';
 
 export type GuardSeverity = 'hard' | 'soft';
 export type GuardOp = 'publish' | 'teach' | 'consolidate' | 'reindex';
@@ -79,6 +80,21 @@ export interface GuardResult {
 /** Facts the CLI injects; each rule reads only the fields it needs. Missing evidence ⇒ that rule is skipped. */
 export interface GuardFacts {
   readonly op: GuardOp;
+  /** Signature evidence gathered by the CLI. The pure evaluator never reads manifests or keys. */
+  readonly signedPacks?: readonly {
+    readonly name: string;
+    readonly dir: string;
+    readonly changed: boolean;
+    readonly ok: boolean | null;
+    readonly failures: readonly string[];
+    readonly note?: string;
+  }[];
+  /** Release-line evidence gathered by the CLI; absence means the rule was not established. */
+  readonly releaseLines?: {
+    readonly readmes: readonly { readonly path: string; readonly text: string | null }[];
+    readonly coreVersion: string | null;
+    readonly cliVersion: string | null;
+  };
   /** Publish-only raw volume facts. Absence preserves the legacy result shape. */
   readonly volume?: VolumeShadowInput;
   /** for no-workspace-star: each publishable package's deps map. */
@@ -165,7 +181,7 @@ export interface GuardFacts {
   /** for skills-registrable: per skill pack, dirs that would ship un-registrable (no depth-1 SKILL.md). */
   readonly skillPacks?: readonly { readonly name: string; readonly nonRegistrable: readonly string[] }[];
   /** for readme-first: per publishable package, is a version bump staged without a README change? */
-  readonly readmeFirst?: readonly { readonly name: string; readonly versionBumped: boolean; readonly readmeChanged: boolean }[];
+  readonly readmeFirst?: readonly { readonly name: string; readonly versionBumped: boolean; readonly readmeChanged: boolean; readonly versionUnknown?: boolean }[];
   /**
    * for review-round: per publishable package, does this change bump a version AND touch SOURCE, and
    * did it bring a GRADED QE report with it? `undefined` (the whole fact absent) means the tree could
@@ -347,6 +363,99 @@ function unquoteYaml(s: string): string {
   return t;
 }
 
+function inspectReleaseLines(
+  evidence: NonNullable<GuardFacts['releaseLines']>,
+  severity: GuardSeverity,
+): {
+  readonly violations: Violation[];
+  readonly observations: GuardObservation[];
+} {
+  const expected = evidence.coreVersion !== null && evidence.cliVersion !== null
+    ? { core: evidence.coreVersion, cli: evidence.cliVersion }
+    : null;
+  const violations: Violation[] = [];
+  const observations: GuardObservation[] = [];
+
+  for (const readme of evidence.readmes) {
+    if (readme.text === null) {
+      observations.push({
+        schemaVersion: 'volume-shadow/v1', rule: 'release-line-in-sync' as never,
+        metric: 'release-line-version-sync', scope: readme.path, status: 'unknown', value: null,
+        unit: 'artifact_set', signal: false, operands: {}, method: 'release-line-regex/v1',
+        detail: 'файл не прочитан',
+      });
+      continue;
+    }
+    const found = findReleaseLine(readme.text);
+    if (found === null) {
+      observations.push({
+        schemaVersion: 'volume-shadow/v1', rule: 'release-line-in-sync' as never,
+        metric: 'release-line-version-sync', scope: readme.path, status: 'unknown', value: null,
+        unit: 'artifact_set', signal: false, operands: {}, method: 'release-line-regex/v1',
+        detail: 'строка релиза не найдена',
+      });
+      continue;
+    }
+    if (expected === null) {
+      const missing = [
+        ...(evidence.coreVersion === null ? ['harness-core package.json version'] : []),
+        ...(evidence.cliVersion === null ? ['harness-cli package.json version'] : []),
+      ];
+      observations.push({
+        schemaVersion: 'volume-shadow/v1', rule: 'release-line-in-sync' as never,
+        metric: 'release-line-version-sync', scope: readme.path, status: 'unknown', value: [found.core, found.cli],
+        unit: 'artifact_set', signal: false, operands: { actual: [found.core, found.cli] },
+        method: 'release-line-regex/v1', detail: `${missing.join(' и ')} не прочитана или не имеет форму N.N.N`,
+      });
+      continue;
+    }
+    const mismatch = found.core !== expected.core || found.cli !== expected.cli;
+    const detail = mismatch
+      ? `${readme.path}: строка релиза говорит core v${found.core}/cli v${found.cli}, package.json — v${expected.core}/v${expected.cli}`
+      : `${readme.path}: строка релиза совпадает с package.json (${expected.core}/${expected.cli})`;
+    observations.push({
+      schemaVersion: 'volume-shadow/v1', rule: 'release-line-in-sync' as never,
+      metric: 'release-line-version-sync', scope: readme.path,
+      status: mismatch ? 'outside-reference' : 'within-reference', value: [found.core, found.cli],
+      unit: 'artifact_set', signal: mismatch,
+      operands: { actual: [found.core, found.cli], expected: [expected.core, expected.cli] },
+      method: 'release-line-regex/v1', detail,
+    });
+    if (mismatch) violations.push({ rule: 'release-line-in-sync', severity, detail });
+  }
+  return { violations, observations };
+}
+
+function inspectSignatureFresh(
+  evidence: NonNullable<GuardFacts['signedPacks']>,
+  severity: GuardSeverity,
+): {
+  readonly violations: Violation[];
+  readonly observations: GuardObservation[];
+} {
+  const violations: Violation[] = [];
+  const observations: GuardObservation[] = [];
+  for (const pack of evidence) {
+    if (!pack.changed) continue;
+    if (pack.ok === false) {
+      const firstFailure = pack.failures[0] ?? 'verification failed without a named reason';
+      violations.push({
+        rule: 'signature-fresh',
+        severity,
+        detail: `${pack.name}: files changed but the signed manifest is stale (${firstFailure}) — re-sign: dz sign --pack ${pack.dir} --key <key>`,
+      });
+    } else if (pack.ok === true) {
+      observations.push({
+        schemaVersion: 'volume-shadow/v1', rule: 'signature-fresh' as never,
+        metric: 'signed-manifest-freshness', scope: pack.name, status: 'within-reference', value: 1,
+        unit: 'artifact_set', signal: false, operands: { changed: 1, verified: 1 },
+        method: 'verify-manifest/v1', detail: `${pack.name}: ${pack.note ?? 'changed files still match its signed manifest'}`,
+      });
+    }
+  }
+  return { violations, observations };
+}
+
 /** The built-in rule set (works with no config). Ops are the mutating operations each rule guards. */
 export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'no-workspace-star', severity: 'hard', ops: ['publish'], description: 'a published package.json must carry no workspace:* dep (npm ships it verbatim → the install breaks)' },
@@ -356,6 +465,8 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'backlog-covers-features', severity: 'soft', ops: ['publish', 'consolidate'], description: 'каталог фичи, заведённый после базовой даты, назван записью бэклога — либо несёт именованную оговорку с причиной' },
   { id: 'no-secrets', severity: 'hard', ops: ['teach', 'publish'], description: 'no private key or API token in lesson text or a published file' },
   { id: 'readme-consistency', severity: 'soft', ops: ['publish'], description: 'README counts agree (CJM header vs All Commands, etc.)' },
+  { id: 'release-line-in-sync', severity: 'soft', ops: ['publish'], description: 'root and harness-cli README release lines agree with the harness-core and harness-cli package versions' },
+  { id: 'signature-fresh', severity: 'soft', ops: ['publish'], description: 'a pack whose files changed in this diff still verifies against its signed .dz-manifest.json — a stale signature is named before publish, not at the gate' },
   { id: 'skills-registrable', severity: 'soft', ops: ['publish'], description: 'every skill directory in a skill pack has a depth-1 SKILL.md (a buried or missing one ships un-registrable — the health-advisor 1.2.0 class)' },
   { id: 'readme-first', severity: 'soft', ops: ['publish'], description: 'a package with a staged version bump must update its own README.md in the same change (README-first)' },
   { id: 'routing-store-stale', severity: 'soft', ops: ['publish'], description: 'harvested routing telemetry has been applied to the auto-cost outcome store' },
@@ -921,6 +1032,8 @@ const HAS_INPUT: Partial<Record<string, (f: GuardFacts) => boolean>> = {
   // Дерево без плагин-манифестов правилу нечего сказать: «прошло» тут значило бы «не смотрели».
   'plugin-manifest-audit': (f) => Array.isArray(f.pluginManifests) && f.pluginManifests.length > 0,
   'no-secrets': (f) => Array.isArray(f.secretTargets) && f.secretTargets.length > 0,
+  'release-line-in-sync': (f) => typeof f.releaseLines === 'object' && f.releaseLines !== null,
+  'signature-fresh': (f) => Array.isArray(f.signedPacks),
 };
 
 /**
@@ -1065,6 +1178,29 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
       continue;
     }
     checked.push(r.id);
+    if (r.id === 'readme-first') {
+      for (const p of facts.readmeFirst ?? []) {
+        if (p?.versionUnknown !== true) continue;
+        observations.push({
+          schemaVersion: 'volume-shadow/v1', rule: 'readme-first' as never,
+          metric: 'package-version-changed-from-head', scope: p.name, status: 'unknown', value: null,
+          unit: 'artifact_set', signal: false, operands: {}, method: 'git-show-head-package-version/v1',
+          detail: `${p.name}: package version could not be compared with HEAD; readme-first stayed advisory and emitted no violation`,
+        });
+      }
+    }
+    if (r.id === 'release-line-in-sync') {
+      const inspection = inspectReleaseLines(facts.releaseLines!, r.severity);
+      observations.push(...inspection.observations);
+      violations.push(...inspection.violations);
+      continue;
+    }
+    if (r.id === 'signature-fresh') {
+      const inspection = inspectSignatureFresh(facts.signedPacks!, r.severity);
+      observations.push(...inspection.observations);
+      violations.push(...inspection.violations);
+      continue;
+    }
     if ((VOLUME_SHADOW_RULE_IDS as readonly string[]).includes(r.id)) {
       const emission = volume();
       observations.push(...emission.observations.filter((item) => item.rule === r.id));

package/src/index.ts

@@ -10,6 +10,8 @@ import { createRequire } from 'node:module';
 export const HARNESS_CORE_VERSION: string =
   (createRequire(import.meta.url)('../package.json') as { version: string }).version;
 
+export { REPOSITORY_ORIGIN } from './repository-origin.js';
+
 export * from './skills.js';
 export * from './apply.js';
 export {
@@ -123,6 +125,8 @@ export { planLedgerBackfill, LEDGER_FILL_SOURCE, AMBIGUOUS, resolveLedgerRunId }
 // project-skills root resolution (field report doc-25b): the ONE builder behind both the Step-0
 // probe and the PS_GUIDANCE paragraph, so the two can never look at different roots again.
 export { projectSkillsOneRoot, projectSkillsProbeCommand } from './project-skills-root.js';
+export { isRepoBoundary } from './repo-boundary.js';
+export type { RepoBoundaryIo } from './repo-boundary.js';
 export type { LedgerBackfillPlan, LedgerBackfillRow, RunCostFacts } from './ledger-backfill.js';
 export type { SweepResult, DriftedSkill, SyncResult, SyncCanonicalOptions } from './skill-drift.js';
 export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
@@ -660,7 +664,8 @@ export type {
   ChainDefectAges,
   ChainedJournal,
 } from './event-chain.js';
-export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion } from './publish.js';
+export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, rewriteWorkspaceSpecs, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion } from './publish.js';
+export { RELEASE_LINE_RE, findReleaseLine, rewriteReleaseLine } from './release-line.js';
 export * from './course-staleness.js';
 export { fetchAllDownloads } from './downloads.js';
 export type { PackageDownloads, DownloadsReport } from './downloads.js';

package/src/publish.ts

@@ -16,6 +16,7 @@ import { execSync } from 'node:child_process';
 type ExecSyncOptionsWithStringEncoding = NonNullable<Parameters<typeof execSync>[1]> & { encoding: 'utf-8' };
 
 import { claimCheck } from './claim-check.js';
+import { rewriteReleaseLine } from './release-line.js';
 
 export type ProbeOutcome = {
   readonly attempt: number;
@@ -26,6 +27,10 @@ export type ProbeOutcome = {
   readonly ms: number;
 };
 
+// MEASURED 2026-09-10: registry answered E404 for ~3 min (19 probes); earlier the same day > 5 min.
+export const REGISTRY_PROBE_BUDGET = 90;
+export const REGISTRY_PROBE_INTERVAL_MS = 10_000;
+
 /** Result for a single package publish attempt. */
 export interface PublishResult {
   readonly name: string;
@@ -63,6 +68,10 @@ export interface PublishReport {
   readonly skipped: number;
   readonly errors: number;
   readonly dryRun: boolean;
+  /** Repo-relative README paths whose first joint core/CLI release line was rewritten. */
+  readonly releaseLineSynced: readonly string[];
+  /** Post-publication sync failures are warnings: registry-confirmed packages cannot be unpublished. */
+  readonly warnings?: readonly string[] | undefined;
 }
 
 /** Is `p` inside `dir`? Used to refuse a signing key that lives in the repository working tree. */
@@ -126,6 +135,32 @@ function maxPublished(name: string, localVersion: string, exec: PublishExec = ex
 // the publish itself succeeds, and every consumer `npm install` then fails with ETARGET. Staged is
 // not shipped; this preflight makes the difference a refusal instead of a broken release.
 
+/**
+ * Mirror pnpm's package-time expansion of the three shorthand workspace dependency specs.
+ * Pure by construction: callers provide both the source bytes and the sibling version table.
+ */
+export function rewriteWorkspaceSpecs(
+  pkgJsonText: string,
+  siblingVersions: ReadonlyMap<string, string>,
+): string {
+  const pkg = JSON.parse(pkgJsonText) as Record<string, unknown>;
+  const fields = ['dependencies', 'peerDependencies', 'optionalDependencies', 'devDependencies'] as const;
+  for (const field of fields) {
+    const candidate = pkg[field];
+    if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) continue;
+    const table = candidate as Record<string, unknown>;
+    for (const [dep, spec] of Object.entries(table)) {
+      if (typeof spec !== 'string') continue;
+      const match = /^workspace:([*^~])$/.exec(spec);
+      const version = siblingVersions.get(dep);
+      if (match === null || version === undefined) continue;
+      const marker = match[1]!;
+      table[dep] = marker === '*' ? version : `${marker}${version}`;
+    }
+  }
+  return JSON.stringify(pkg, null, 2) + '\n';
+}
+
 /**
  * Pure half: which `workspace:`-declared deps of a package would pack to a floor that is neither
  * being published in this batch nor already on the registry?
@@ -840,7 +875,7 @@ export function publishPackages(
 
       let registryProbes = 0;
       let confirmed = false;
-      while (registryProbes < 30) {
+      while (registryProbes < REGISTRY_PROBE_BUDGET) {
         registryProbes++;
         const probed = probe(pkg.name, newVersion);
         const outcome: Omit<ProbeOutcome, 'attempt'> = typeof probed === 'boolean'
@@ -851,14 +886,15 @@ export function publishPackages(
           confirmed = true;
           break;
         }
-        if (registryProbes < 30) sleep(10_000);
+        if (registryProbes < REGISTRY_PROBE_BUDGET) sleep(REGISTRY_PROBE_INTERVAL_MS);
       }
       if (!confirmed) {
         const last = probeLog[probeLog.length - 1]!;
         const output = last.stderr || last.stdout;
         const firstLine = output.split(/\r?\n/, 1)[0]?.trim() || '(empty)';
         throw new Error(
-          `registry did not confirm ${pkg.name}@${newVersion} after ${registryProbes} probes; ` +
+          `registry did not confirm ${pkg.name}@${newVersion} after ${registryProbes} probes ` +
+          `(${Math.round(registryProbes * REGISTRY_PROBE_INTERVAL_MS / 60_000)} min); ` +
           `last probe: code ${String(last.code)}, ${last.ms}ms, ${firstLine}`,
         );
       }
@@ -887,11 +923,64 @@ export function publishPackages(
     }
   }
 
+  const releaseLineSynced: string[] = [];
+  const warnings: string[] = [];
+  const releasePackageNames = new Set(['@dzhechkov/harness-core', '@dzhechkov/harness-cli']);
+  const releasePackagePublished = results.some(
+    (result) => result.status === 'published' && releasePackageNames.has(result.name),
+  );
+  if (releasePackagePublished && opts.dryRun !== true && opts.bumpOnly !== true) {
+    const currentVersion = (name: string): string | null => {
+      const landed = results.find((result) => result.name === name && result.status === 'published');
+      if (landed !== undefined) return landed.newVersion;
+      const pkg = packages.find((candidate) => candidate.name === name);
+      if (pkg === undefined) return null;
+      try {
+        const parsed = JSON.parse(readFileSync(pathJoin(pkg.dir, 'package.json'), 'utf8')) as { version?: unknown };
+        return typeof parsed.version === 'string' ? parsed.version : null;
+      } catch {
+        return null;
+      }
+    };
+    const coreVersion = currentVersion('@dzhechkov/harness-core');
+    const cliVersion = currentVersion('@dzhechkov/harness-cli');
+    if (coreVersion === null || cliVersion === null) {
+      warnings.push('release-line sync skipped: could not read both harness-core and harness-cli package versions');
+    } else {
+      const readmes = [
+        { path: 'README.md', absolute: pathJoin(monorepoRoot, 'README.md') },
+        {
+          path: 'packages/@dzhechkov/harness-cli/README.md',
+          absolute: pathJoin(monorepoRoot, 'packages', '@dzhechkov', 'harness-cli', 'README.md'),
+        },
+      ] as const;
+      for (const readme of readmes) {
+        try {
+          const original = readFileSync(readme.absolute, 'utf8');
+          const updated = rewriteReleaseLine(original, coreVersion, cliVersion);
+          if (updated === null) {
+            warnings.push(`release-line sync skipped ${readme.path}: release line not found`);
+            continue;
+          }
+          if (updated === original) continue;
+          const tmp = readme.absolute + '.sync-tmp';
+          writeFileSync(tmp, updated);
+          renameSync(tmp, readme.absolute);
+          releaseLineSynced.push(readme.path);
+        } catch (error) {
+          warnings.push(`release-line sync failed ${readme.path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    }
+  }
+
   return {
     packages: results,
     published: results.filter((r) => r.status === 'published').length,
     skipped: results.filter((r) => r.status === 'skipped').length,
     errors: results.filter((r) => r.status === 'error').length,
     dryRun: opts.dryRun === true,
+    releaseLineSynced,
+    ...(warnings.length > 0 ? { warnings } : {}),
   };
 }

package/src/release-line.ts

@@ -0,0 +1,31 @@
+export const RELEASE_LINE_RE = /`harness-core v(\d+\.\d+\.\d+)` · `harness-cli v(\d+\.\d+\.\d+)`/;
+
+export interface ReleaseLineMatch {
+  readonly index: number;
+  readonly line: string;
+  readonly core: string;
+  readonly cli: string;
+}
+
+export function findReleaseLine(text: string): ReleaseLineMatch | null {
+  const lines = text.split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index]!;
+    const match = RELEASE_LINE_RE.exec(line);
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      return { index, line, core: match[1], cli: match[2] };
+    }
+  }
+  return null;
+}
+
+export function rewriteReleaseLine(text: string, core: string, cli: string): string | null {
+  const found = findReleaseLine(text);
+  if (found === null) return null;
+  const lines = text.split('\n');
+  lines[found.index] = found.line.replace(
+    RELEASE_LINE_RE,
+    `\`harness-core v${core}\` · \`harness-cli v${cli}\``,
+  );
+  return lines.join('\n');
+}

package/src/repo-boundary.ts

@@ -0,0 +1,25 @@
+/** Filesystem facts required to recognise a real Git repository boundary. */
+export interface RepoBoundaryIo {
+  exists(p: string): boolean;
+  isDirectory(p: string): boolean;
+  readText(p: string): string | null;
+}
+
+/**
+ * A Git repository boundary is either a `.git` directory containing `HEAD`, or a worktree-style
+ * `.git` file whose first bytes are the `gitdir:` redirect. An empty or unrelated `.git` entry is
+ * not a boundary.
+ */
+export function isRepoBoundary(
+  dir: string,
+  io: RepoBoundaryIo,
+  join: (...p: string[]) => string,
+): boolean {
+  const git = join(dir, '.git');
+  if (!io.exists(git)) return false;
+  if (io.isDirectory(git)) {
+    const head = join(git, 'HEAD');
+    return io.exists(head) && !io.isDirectory(head);
+  }
+  return io.readText(git)?.startsWith('gitdir:') === true;
+}

package/src/repository-origin.ts

@@ -0,0 +1 @@
+export const REPOSITORY_ORIGIN = 'git+https://github.com/djd1m/dz-harness-hub.git';