@dzhechkov/harness-core 0.3.144 → 0.3.145

package/src/guard.ts

@@ -11,6 +11,8 @@
 // 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';
+
 export type GuardSeverity = 'hard' | 'soft';
 export type GuardOp = 'publish' | 'teach' | 'consolidate' | 'reindex';
 export type GuardVerdict = 'pass' | 'warn' | 'block';
@@ -23,6 +25,13 @@ export interface GuardRule {
   readonly description: string;
   /** false ⇒ the rule is disabled (config override). */
   readonly enabled?: boolean;
+  /**
+   * A PROMOTED rule (`dz guard promote`) carries a template + params instead of a built-in checker.
+   * This is the ONLY way a rule id the engine does not know may enter the rule set — and such a rule
+   * is forced SOFT unconditionally (see {@link resolveRules}).
+   */
+  readonly template?: RuleTemplate;
+  readonly params?: TemplateParams;
 }
 
 export interface Violation {
@@ -61,6 +70,16 @@ export interface GuardFacts {
    * importer. `parsed:false` (or the fact absent) ⇒ the rule reports nothing — fail-open by construction,
    * because a lockfile we could not read is not evidence of a defect.
    */
+  /**
+   * for TEMPLATE rules (promoted by `dz guard promote`): the change under evaluation — the file list
+   * of the working-tree diff, plus the text of those files when a `format-match` rule needs it.
+   * ABSENT ⇒ every template rule reports NOTHING (fail-open on missing evidence, the same contract
+   * `lockfile-in-sync` follows).
+   */
+  readonly change?: {
+    readonly files: readonly string[];
+    readonly contents?: Readonly<Record<string, string>>;
+  };
   readonly lockfile?: {
     readonly parsed: boolean;
     readonly importers?: readonly {
@@ -308,13 +327,63 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
  */
 export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync'];
 
-/** Merge a user config over the defaults: override severity, disable (enabled:false), never add an un-checked rule. */
+/**
+ * A well-formed PROMOTED rule: an id the engine does not know, made enforceable by a template +
+ * params from the fixed `dz guard promote` vocabulary. Anything half-formed is NOT one, so a
+ * hand-edited config cannot smuggle an id past the un-enforceable-rule fail-safe by sprinkling a
+ * `template` key on it.
+ */
+export function isTemplateRule(r: Partial<GuardRule> | null | undefined): r is GuardRule & { template: RuleTemplate; params: TemplateParams } {
+  return !!r && typeof r === 'object' && validTemplateParams(r.template, r.params);
+}
+
+/**
+ * The template checker: ONE predicate (`templateFires`) shared with the promoter's historical
+ * replay, so the rule the promoter promised and the rule the guard enforces can never diverge.
+ * Fail-open on missing evidence (no `change` fact ⇒ nothing reported) and on `undecidable`
+ * (a `format-match` whose file contents were not gathered is not a clean change, it is no evidence).
+ */
+function templateChecker(rule: GuardRule & { template: RuleTemplate; params: TemplateParams }): (f: GuardFacts, sev: GuardSeverity) => Violation[] {
+  return (f) => {
+    const ch = f.change;
+    if (!ch || typeof ch !== 'object' || !Array.isArray(ch.files)) return [];
+    const change: ChangeSet = { id: 'working-tree', ts: '', files: ch.files, ...(ch.contents !== undefined ? { contents: ch.contents } : {}) };
+    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)` }];
+  };
+}
+
+/**
+ * Merge a user config over the defaults: override severity, disable (enabled:false), never add an
+ * un-checked rule — EXCEPT a well-formed template rule (a `dz guard promote` promotion), which is
+ * enforceable by construction and is forced SOFT.
+ */
 export function resolveRules(userRules?: readonly Partial<GuardRule>[]): GuardRule[] {
   const byId = new Map<string, GuardRule>(DEFAULT_RULES.map((r) => [r.id, r]));
   for (const u of Array.isArray(userRules) ? userRules : []) {
     if (!u || typeof u.id !== 'string') continue;
     const base = byId.get(u.id);
-    if (!base) continue; // a config rule with no built-in checker is ignored (fail-safe: no un-enforceable rules)
+    if (!base) {
+      // A PROMOTED rule may introduce a new id — but only fully formed, and only SOFT. A promoted
+      // rule is derived by a text heuristic from an agent-written lesson: strictly weaker provenance
+      // than `lockfile-in-sync`'s tolerant parser, which is already SOFT-only. "I might be wrong"
+      // plus "block the publish" is the wrong pair (ADR-004).
+      if (isTemplateRule(u)) {
+        const ops = Array.isArray(u.ops) && u.ops.every((o) => ['publish', 'teach', 'consolidate', 'reindex'].includes(o as string)) && u.ops.length > 0 ? (u.ops as readonly GuardOp[]) : (['publish'] as const);
+        byId.set(u.id, {
+          id: u.id,
+          severity: 'soft',
+          ops,
+          description: typeof u.description === 'string' ? u.description : `promoted rule (${u.template})`,
+          ...(typeof u.enabled === 'boolean' ? { enabled: u.enabled } : {}),
+          template: u.template,
+          params: u.params,
+        });
+      }
+      continue; // a config rule with no built-in checker is ignored (fail-safe: no un-enforceable rules)
+    }
     // A SOFT-ONLY rule keeps its severity even when the config asks for hard (see SOFT_ONLY_RULES).
     const severity = u.severity === 'hard' || u.severity === 'soft' ? u.severity : undefined;
     const allowedSeverity = severity !== undefined && !(severity === 'hard' && SOFT_ONLY_RULES.includes(u.id)) ? severity : undefined;
@@ -343,7 +412,11 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
   const checked: string[] = [];
   for (const r of active) {
     checked.push(r.id);
-    const checker = CHECKERS[r.id];
+    // 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 —
+    // the exact false-green shape this feature exists to remove (ADR-004).
+    const checker = CHECKERS[r.id] ?? (isTemplateRule(r) ? templateChecker(r) : undefined);
     if (!checker) {
       // A rule the caller asked for that has no checker CANNOT silently pass while reporting as checked —
       // that is the smuggled-rule hole. Fail closed: unenforceable ⇒ a HARD violation.

package/src/index.ts

@@ -316,6 +316,10 @@ export * from './routing-outcomes.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';
+// Lesson → guard-rule PROMOTION (feature guard-promotion, scout idea #1) — the cost-of-detection
+// ladder's elevator: moves a lesson from layer 5 (agent memory) to layer 1 (a deterministic rule),
+// but only after TWO consecutive shadow wins replayed over REAL commits. Never synthesises rule code.
+export * from './guard-promotion.js';
 export * from './delivery-check.js';
 
 // Skill-registration gate (feature skills-verify, ADR-001) — static layout scan + the deterministic