@dzhechkov/harness-core 0.8.5 → 0.8.10

package/src/guard.ts

@@ -11,8 +11,16 @@
 // PURE: `evaluateGuard` operates over INJECTED FACTS (package.json deps, a drift result, lesson text, README
 // counts, store size) that the CLI gathers. No filesystem here → deterministic + unit-testable without a repo.
 
-import { type RuleTemplate, type TemplateParams, type ChangeSet, templateFires, validTemplateParams } from './guard-promotion.js';
+import { lessonRuleContentAnchor, type RuleTemplate, type TemplateParams, type ChangeSet, templateFires, validTemplateParams } from './guard-promotion.js';
 import { STUB_MARKERS, STUB_PHRASES, checkNoStubs, type StubWaiver } from './no-stubs.js';
+import {
+  VOLUME_SHADOW_RULE_IDS,
+  evaluateVolumeShadow,
+  unknownVolumeShadow,
+  type GuardObservation,
+  type VolumeShadowInput,
+  type VolumeShadowResult,
+} from './guard-volume.js';
 
 export type GuardSeverity = 'hard' | 'soft';
 export type GuardOp = 'publish' | 'teach' | 'consolidate' | 'reindex';
@@ -39,6 +47,8 @@ export interface Violation {
   readonly rule: string;
   readonly severity: GuardSeverity;
   readonly detail: string;
+  /** Present for promoted-template firings; ids alone do not prove equal effective rule content. */
+  readonly contentAnchor?: string;
 }
 
 export interface GuardResult {
@@ -54,11 +64,15 @@ export interface GuardResult {
    * argument; a note is the cheap fix. Present only when non-empty.
    */
   readonly notes?: readonly string[];
+  /** Versioned shadow measurements. They are evidence only and never enter the verdict reducer. */
+  readonly observations?: readonly GuardObservation[];
 }
 
 /** Facts the CLI injects; each rule reads only the fields it needs. Missing evidence ⇒ that rule is skipped. */
 export interface GuardFacts {
   readonly op: GuardOp;
+  /** Publish-only raw volume facts. Absence preserves the legacy result shape. */
+  readonly volume?: VolumeShadowInput;
   /** for no-workspace-star: each publishable package's deps map. */
   readonly packages?: readonly { readonly name: string; readonly deps: Readonly<Record<string, string>> }[];
   /** for no-skill-drift: the names that byte-drift between copies (from sweepSkillDrift). */
@@ -69,6 +83,29 @@ export interface GuardFacts {
   readonly counts?: readonly { readonly label: string; readonly a: number; readonly b: number }[];
   /** for store-bloat-cap: current learned-store size vs its cap. */
   readonly store?: { readonly count: number; readonly cap: number };
+  /** Advisory freshness evidence for the auto-cost outcome store. Missing evidence fails open. */
+  readonly routingFreshness?: { readonly unfedRunIds: readonly string[] };
+  /**
+   * for marketplace-parity: the CLI's read-only regeneration result. The whole field being absent
+   * means evidence could not be gathered, so this advisory rule reports nothing.
+   */
+  readonly marketplaceParity?: {
+    /** false ⇒ this repository has no .claude-plugin/ showcase and is out of scope. */
+    readonly applicable: boolean;
+    /** true ⇒ exactly one of plugin.json / marketplace.json is present. */
+    readonly onlyOnePresent?: boolean;
+    /** true ⇒ registry-derived composition differs from a fresh regeneration. */
+    readonly diverged?: boolean;
+    /** Operator-owned published version, carried only to render the exact repair command. */
+    readonly publishedVersion?: string;
+    /** Existing published manifests that could not be read or parsed. */
+    readonly manifestFailures?: readonly {
+      readonly file: 'plugin.json' | 'marketplace.json';
+      readonly error: string;
+    }[];
+    /** true ⇒ regeneration was attempted but could not complete. */
+    readonly regenerateFailed?: boolean;
+  };
   /** 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? */
@@ -262,6 +299,12 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'readme-consistency', severity: 'soft', ops: ['publish'], description: 'README counts agree (CJM header vs All Commands, etc.)' },
   { 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' },
+  { id: 'marketplace-parity', severity: 'soft', ops: ['publish'], description: 'the published .claude-plugin/ showcase composition matches a fresh regeneration from the live registry (version excluded — an operator field)' },
+  { id: 'template-context-token-weight', severity: 'soft', ops: ['publish'], description: 'observe the UTF-8-byte estimated token weight of each selected template context corpus; measured starting points are advisory only' },
+  { id: 'template-context-largest-file-share', severity: 'soft', ops: ['publish'], description: 'observe the largest template file share on the same estimated-token basis as its corpus total; advisory only' },
+  { id: 'feature-artifact-diff-ratio', severity: 'soft', ops: ['publish'], description: 'observe feature artifact bytes against attributable unified-diff bytes, explicitly a proxy; advisory only' },
+  { id: 'feature-tier-artifact-set', severity: 'soft', ops: ['publish'], description: 'observe artifacts due for the recorded feature tier, active steps, consumers, and lifecycle; advisory only' },
   { id: 'agents-md-policy-sync', severity: 'soft', ops: ['publish'], description: 'proves the AGENTS.md copy is in SYNC with its source — not that the runtime read or obeyed it; heal drift with dz agents-sync' },
   { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
@@ -360,6 +403,59 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
     }
     return out;
   },
+  'routing-store-stale': (f, _sev) => {
+    const ids = f.routingFreshness?.unfedRunIds;
+    if (!Array.isArray(ids) || ids.length === 0) return [];
+    const valid = [...new Set(ids.filter((id): id is string => typeof id === 'string' && id !== ''))].sort();
+    if (valid.length === 0) return [];
+    return [{
+      rule: 'routing-store-stale',
+      severity: 'soft',
+      detail: `${valid.length} harvested run(s) are not reflected in the auto-cost store: ${valid.slice(0, 5).join(', ')}${valid.length > 5 ? '…' : ''} — run dz routing recommend --apply`,
+    }];
+  },
+  'marketplace-parity': (f, _sev) => {
+    const fact = f.marketplaceParity;
+    if (fact === undefined || fact.applicable !== true) return [];
+    const hasPublishedVersion = typeof fact.publishedVersion === 'string' && fact.publishedVersion !== '';
+    const fix = `dz plugin --version ${hasPublishedVersion ? fact.publishedVersion : 'X.Y.Z'}`;
+    const fixHint = hasPublishedVersion ? '' : ' (substitute the published version for X.Y.Z)';
+    const manifestFailures = Array.isArray(fact.manifestFailures)
+      ? fact.manifestFailures.filter((failure) => failure
+        && (failure.file === 'plugin.json' || failure.file === 'marketplace.json')
+        && typeof failure.error === 'string'
+        && failure.error !== '')
+      : [];
+    if (manifestFailures.length > 0) {
+      return manifestFailures.map((failure) => ({
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: `.claude-plugin/${failure.file} exists but could not be read or parsed: ${failure.error} — run \`${fix}\`${fixHint} and commit the result`,
+      }));
+    }
+    if (fact.onlyOnePresent === true) {
+      return [{
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: `.claude-plugin/ has only one of plugin.json / marketplace.json — a broken half-showcase; run \`${fix}\`${fixHint} and commit the result`,
+      }];
+    }
+    if (fact.regenerateFailed === true) {
+      return [{
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: 'could not verify .claude-plugin/ composition because fresh regeneration failed',
+      }];
+    }
+    if (fact.diverged === true) {
+      return [{
+        rule: 'marketplace-parity',
+        severity: 'soft',
+        detail: `.claude-plugin/ composition does not match a fresh regeneration from the live registry — run \`${fix}\`${fixHint} and commit the result`,
+      }];
+    }
+    return [];
+  },
   'review-round': (f, sev) => {
     // The publish gate had eleven rules and not one asked whether anyone but the author had read the
     // code. MEASURED cost (health-advisor slice H): five rounds graded F, thirteen packages published
@@ -508,7 +604,13 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
  * may not understand a file, and "I might be wrong" plus "block the publish" is the wrong pair. Disabling
  * such a rule stays allowed — only the promotion is refused.
  */
-export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync', 'agents-md-policy-sync'];
+export const SOFT_ONLY_RULES: readonly string[] = [
+  'lockfile-in-sync',
+  'agents-md-policy-sync',
+  'routing-store-stale',
+  'marketplace-parity',
+  ...VOLUME_SHADOW_RULE_IDS,
+];
 
 /**
  * A well-formed PROMOTED rule: an id the engine does not know, made enforceable by a template +
@@ -534,7 +636,12 @@ function templateChecker(rule: GuardRule & { template: RuleTemplate; params: Tem
     const r = templateFires(rule.template, rule.params, change);
     if (Object.hasOwn(r, 'undecidable') || !(r as { fired?: boolean }).fired) return [];
     // A promoted rule is ALWAYS soft, whatever severity reaches this point (belt to resolveRules' braces).
-    return [{ rule: rule.id, severity: 'soft', detail: `${(r as { detail?: string }).detail ?? 'template rule fired'} (promoted rule — advisory)` }];
+    return [{
+      rule: rule.id,
+      severity: 'soft',
+      detail: `${(r as { detail?: string }).detail ?? 'template rule fired'} (promoted rule — advisory)`,
+      contentAnchor: lessonRuleContentAnchor(rule.template, rule.params),
+    }];
   };
 }
 
@@ -593,8 +700,32 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
   );
   const violations: Violation[] = [];
   const checked: string[] = [];
+  const observations: GuardObservation[] = [];
+  let volumeResult: VolumeShadowResult | undefined;
+  let volumeEvaluated = false;
+  const volume = (): VolumeShadowResult => {
+    if (volumeEvaluated) return volumeResult ?? { observations: [], signals: [], notes: [] };
+    volumeEvaluated = true;
+    try {
+      volumeResult = evaluateVolumeShadow(facts.volume);
+    } catch (error) {
+      volumeResult = unknownVolumeShadow(
+        'volume-evaluator-failure',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return volumeResult;
+  };
   for (const r of active) {
     checked.push(r.id);
+    if ((VOLUME_SHADOW_RULE_IDS as readonly string[]).includes(r.id)) {
+      const emission = volume();
+      observations.push(...emission.observations.filter((item) => item.rule === r.id));
+      violations.push(...emission.signals
+        .filter((signal) => signal.rule === r.id)
+        .map((signal) => ({ rule: signal.rule, severity: 'soft' as const, detail: signal.detail })));
+      continue;
+    }
     // A promoted (template) rule has no built-in checker by design — it is enforceable through the
     // shared `templateFires` predicate instead. Without this branch a promoted rule written into
     // `.dz/guard.json` would be INERT: present in the config, listed as checked, enforcing nothing —
@@ -642,7 +773,17 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
       notes.push('agents-md-policy-sync: this repository carries a dz:policies fence but its canonical policy sources are unreadable — the advisory rule could not compare, and that gap is on the record, not a silent pass');
     }
   }
-  return { op, verdict, violations, checked, ...(notes.length > 0 ? { notes } : {}) };
+  for (const item of observations) {
+    if (item.status === 'unknown') notes.push(`${item.rule} ${item.scope}: ${item.detail}`);
+  }
+  return {
+    op,
+    verdict,
+    violations,
+    checked,
+    ...(notes.length > 0 ? { notes } : {}),
+    ...(observations.length > 0 ? { observations } : {}),
+  };
 }
 
 /** An append-only audit record. `ts` is injected by the caller (no wall-clock here → deterministic tests). */
@@ -653,6 +794,8 @@ export interface GuardAuditRecord {
   readonly violations: readonly Violation[];
   /** informational notes (FN-7 — e.g. the no-stubs skipped-files note); on the record, never a verdict input. */
   readonly notes?: readonly string[];
+  /** Shadow measurements copied without recomputation from the evaluated result. */
+  readonly observations?: readonly GuardObservation[];
   /** set when the operator overrode a block with `--force <reason>` — the override is logged, never silent. */
   readonly override?: { readonly forced: true; readonly reason: string };
 }
@@ -665,6 +808,7 @@ export function auditRecord(result: GuardResult, ts: string, override?: { reason
     verdict: result.verdict,
     violations: result.violations,
     ...(Array.isArray(result.notes) && result.notes.length > 0 ? { notes: result.notes } : {}),
+    ...(Array.isArray(result.observations) && result.observations.length > 0 ? { observations: result.observations } : {}),
     ...(override && typeof override.reason === 'string' ? { override: { forced: true, reason: override.reason } } : {}),
   };
 }

package/src/index.ts

@@ -15,6 +15,11 @@ export * from './apply.js';
 export { bundleSkills } from './bundle.js';
 export type { BundleOptions, BundleResult, BundledSkill } from './bundle.js';
 export * from './targets.js';
+export * from './target-integrations.js';
+export * from './integration-evidence.js';
+export * from './integration-apply.js';
+export * from './integrations-verify.js';
+export { redactProbeText, PROBE_REDACTION_MARKER } from './integration-probe-worker.js';
 // Target-parity model (feature target-parity-matrix, ADR-001) — the computed feature×target map.
 export {
   RUNTIME_CAPABILITIES,
@@ -94,7 +99,8 @@ export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, dis
 export * from './package-skill-layouts.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
-export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
+export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, recordLessonForms, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
+export { normalizeLessonForms, validateClassTemplate, lessonPairIdOf, mergeLessonFormHits, mergeLessonMatchedForms } from './lesson-generalization.js';
 export { withStoreLock, withStoreLockSync, storeLockPath, StoreLockTimeoutError, StoreLockCompromisedError, STALE_LOCK_MS, LOCK_TIMEOUT_MS } from './store-lock.js';
 export type { StoreLockOptions } from './store-lock.js';
 export { withNamedLockSync, namedLockPath, isSafeLockName, NamedLockNameError, NamedLockTimeoutError, NamedLockCompromisedError } from './named-lock.js';
@@ -121,7 +127,8 @@ export {
   renderBridgeReport,
 } 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, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.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';
+export type { LessonForm, LessonMatchedForm, LessonFormsInput, LessonFormRankedHit, MergedLessonFormHit } from './lesson-generalization.js';
 export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend, applyLearningSignals, applyLearningSignalsWithDelta, applyLearningSignalsWithTerms } from './learning-backend.js';
 export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode, RerankTerm } from './learning-backend.js';
 // lesson-bandit-rerank (I-8): the ACL's public surface only. The vendored engine class is
@@ -186,6 +193,15 @@ export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf,
   agentdbStorePath, agentdbMcpStorePath, agentdbStoreSeparationProblem } from './setup.js';
 export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStateDir, featureAdrStatePath } from './statusline.js';
 export type { StatuslineData, FeatureAdrState, WriteFeatureAdrStateInput } from './statusline.js';
+export {
+  ETA_MAX_STAGE_MS,
+  estimateEta,
+  extractStageSamples,
+  formatEta,
+  parseCheckpointLines,
+  segmentRun,
+} from './eta.js';
+export type { CheckpointObservation, EtaEstimate, EtaInput, IncompleteCoverageSample, RunSegment, StageDurationSample, StageSample } from './eta.js';
 export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows, bumpAgentdbUses, clearAgentdbQuarantine, deleteAgentdbByDzIds, readAgentdbRowsByTaskType, DZ_OWNED_TASK_TYPES } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';
 export { DEFAULT_EMBED_MODEL, LEGACY_EMBED_MODEL, DEFAULT_EMBED_DIM, KNOWN_EMBED_DIMS, resolveEmbedModel, readEmbedManifest, writeEmbedManifest, embedManifestPath, legacyEmbedManifest } from './embedding-config.js';
@@ -250,6 +266,50 @@ export { hookDecision, isFenced, isNewLine, ESCAPE_TEACHING } from './claim-chec
 export type { HookDecision, HookDecisionOpts } from './claim-check-hook-policy.js';
 export { step8ClaimGate } from './feature-adr-claim-gate.js';
 export type { Step8ClaimCounts, Step8ClaimGate } from './feature-adr-claim-gate.js';
+export {
+  DEFAULT_CODE_LANDING_CEILING_MS,
+  CODE_LANDING_CEILING_ENV,
+  decideCodeLandingLiveness,
+  extractCodexCompanionJobId,
+  parseCodeLandingLivenessSignal,
+} from './feature-adr-landing.js';
+export type {
+  CodeLandingLivenessVerdict,
+  CodeLandingLivenessReason,
+  CodeLandingLivenessInput,
+  CodeLandingLivenessDecision,
+  CodeLandingLivenessProbe,
+} from './feature-adr-landing.js';
+export {
+  buildDecisionContext,
+  normalizeDecisionRecall,
+  parseDecisionRecallFrame,
+  parseDecisionRecallApplicationProbe,
+  mergeDecisionRecallEvents,
+  reduceDecisionRecallMetrics,
+  summarizeDecisionRecallReceipts,
+  decisionRecallEnterCmd,
+  decisionRecallRunCmd,
+  decisionRecallAppendCmd,
+  decisionRecallApplicationProbeCmd,
+} from './feature-adr-decision-recall.js';
+export type {
+  DecisionRecallKind,
+  DecisionRecallStage,
+  DecisionRecallOutcomeName,
+  DecisionRecallContext,
+  DecisionRecallFrame,
+  DecisionRecallSelection,
+  DecisionRecallOutcome,
+  DecisionRecallEvent,
+  DecisionRecallDisposition,
+  DecisionRecallApplicationProbe,
+  MergedDecisionRecallAttempt,
+  MergedDecisionRecallDecision,
+  MergedDecisionRecallEvents,
+  DecisionRecallRatio,
+  DecisionRecallMetrics,
+} from './feature-adr-decision-recall.js';
 export {
   CHECKPOINT_STAGES,
   STAGE_ARTIFACTS,
@@ -283,7 +343,7 @@ export {
   codeCheckpointPersistAllowed,
   codeStageResultShapeValid,
 } from './feature-adr-checkpoints.js';
-export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairTruncation,
+export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairBudget, TrainingPairTruncation,
   CheckpointWriteVerdict,
 } from './feature-adr-checkpoints.js';
 
@@ -627,6 +687,7 @@ export {
   resolveCoderSpec,
   coderIsCodex,
   resolveQeSpec,
+  resolveQeSpecForCoder,
   crossFamilyQe,
   decideModeBScope,
   partitionReviewFindings,
@@ -825,6 +886,7 @@ export * from './model-recommender.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';
+export * from './guard-volume.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';