@tech-leads-club/harness-toolkit 0.5.0 → 0.6.0

package/src/core/policy/policy.loader.ts

@@ -11,7 +11,11 @@ function readJsonFile<T>(path: string): T | null {
     return null;
   }
   try {
-    return JSON.parse(readFileSync(path, "utf8")) as T;
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    // why: a JSON Schema meta-key, not a Policy field — deepMerge's `...patch` spread would otherwise
+    // carry it straight into the merged runtime Policy object.
+    delete parsed.$schema;
+    return parsed as T;
   } catch {
     return null;
   }

package/src/core/policy/policy.shadow.ts

@@ -13,10 +13,35 @@
 /** A leaf the project config names, and the value it would have had without naming it. */
 export type ShadowedKey = { path: string; value: unknown };
 
+/** A leaf the project config names that `resolved` (the shipped `Policy` shape) has no counterpart for. */
+export type UnknownKey = { path: string; value: unknown };
+
+/** A leaf present in both, whose runtime shape disagrees with the default's. */
+export type TypeMismatch = { path: string; expected: string; actual: string };
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/**
+ * why: `typeof null` is `"object"`, indistinguishable from a real object without this. A field whose
+ * default is `null` (`evidenceDir`, `lintCommand`, `minEffort`, ...) is a `T | null` union in `Policy`
+ * — comparing `typeof` directly against that default would flag every valid non-null override as a
+ * mismatch, which is why the mismatch check below exempts `below === null` entirely.
+ */
+function typeLabel(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  if (isPlainObject(value)) {
+    return "object";
+  }
+  return typeof value;
+}
+
 /**
  * why a JSON comparison rather than a deep walk of its own: the values are config leaves — scalars and small
  * arrays — and `codePaths: ["src"]` has to compare equal to `codePaths: ["src"]`. A second structural comparator
@@ -36,13 +61,22 @@ function sameValue(a: unknown, b: unknown): boolean {
  * `resolved` is the policy as it would be with the project config absent: the shipped defaults merged with this
  * machine's tier.
  */
+type WalkResult = {
+  shadowed: ShadowedKey[];
+  kept: Record<string, unknown>;
+  unknown: UnknownKey[];
+  mismatched: TypeMismatch[];
+};
+
 function walk(
   project: Record<string, unknown>,
   resolved: Record<string, unknown>,
   prefix: string,
-): { shadowed: ShadowedKey[]; kept: Record<string, unknown> } {
+): WalkResult {
   const shadowed: ShadowedKey[] = [];
   const kept: Record<string, unknown> = {};
+  const unknown: UnknownKey[] = [];
+  const mismatched: TypeMismatch[] = [];
   for (const [key, value] of Object.entries(project)) {
     // why kept and never reported: `version` marks the config's shape rather than a setting, so naming it is
     // required rather than redundant.
@@ -52,9 +86,17 @@ function walk(
     }
     const path = prefix === "" ? key : `${prefix}.${key}`;
     const below = resolved[key];
+    // why: `projectName` is exempt — a real, optional `Policy` field `DEFAULTS` never sets, so it is
+    // legitimately absent from `resolved`'s own keys. Kept separate from the branches below: a key
+    // absent from `resolved` still needs `shadowed`/`kept` judged as before; this only adds to `unknown`.
+    if (!(key in resolved) && !(prefix === "" && key === "projectName")) {
+      unknown.push({ path, value });
+    }
     if (isPlainObject(value) && isPlainObject(below)) {
       const inner = walk(value, below, path);
       shadowed.push(...inner.shadowed);
+      unknown.push(...inner.unknown);
+      mismatched.push(...inner.mismatched);
       // why empty blocks go: `{ shipGate: {} }` decides nothing, and leaving it behind would make a pruned config
       // read as though it had opinions.
       if (Object.keys(inner.kept).length > 0) {
@@ -62,13 +104,18 @@ function walk(
       }
       continue;
     }
+    // why: `below === null` is exempt — see `typeLabel`'s doc, a `T | null` default cannot be told
+    // apart from a real mismatch by `typeof` alone, and a false positive here is worse than a miss.
+    if (below !== null && below !== undefined && typeLabel(value) !== typeLabel(below)) {
+      mismatched.push({ path, expected: typeLabel(below), actual: typeLabel(value) });
+    }
     if (sameValue(value, below)) {
       shadowed.push({ path, value });
     } else {
       kept[key] = value;
     }
   }
-  return { shadowed, kept };
+  return { shadowed, kept, unknown, mismatched };
 }
 
 /** What `doctor` reports: every leaf whose value the tiers below already resolve to. */
@@ -79,6 +126,25 @@ export function shadowedKeys(
   return walk(project, resolved, "").shadowed;
 }
 
+/**
+ * What `doctor` reports: every leaf `resolved` (the shipped `Policy` shape) has no counterpart for —
+ * the `format` bug's exact shape, a key that does nothing because nothing reads it.
+ */
+export function unknownKeys(
+  project: Record<string, unknown>,
+  resolved: Record<string, unknown>,
+): UnknownKey[] {
+  return walk(project, resolved, "").unknown;
+}
+
+/** What `doctor` reports: every leaf present in both, whose runtime shape disagrees with the default's. */
+export function typeMismatches(
+  project: Record<string, unknown>,
+  resolved: Record<string, unknown>,
+): TypeMismatch[] {
+  return walk(project, resolved, "").mismatched;
+}
+
 /**
  * What `init` writes: the same config with every restatement removed.
  *

package/src/entrypoints/stop.ts

@@ -470,6 +470,15 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   const changedFiles = await listChangedRepoFiles(root, turnBase);
   const codeTargets = filterCodeTargets(changedFiles, policy.codePaths);
   const testTargets = filterTestTargets(changedFiles);
+  // why: the comment rail scopes by the syntax catalog (40+ languages), not `codeTargets`'s nine-extension
+  // regex — a Terraform/SQL-heavy project changed no file that regex would keep, so the rail never ran.
+  // Scoped to `codePaths` here, not inside `filterCommentTargets`, to avoid an import cycle through `policy.loader.ts`.
+  const commentScope = changedFiles.filter((file) =>
+    coreFacade.policy.isUnderCodePaths(file, policy.codePaths),
+  );
+  // why: `unknown_extensions` reports over `commentScope` (broader), not this — a language gap is still named
+  // even after this excludes it from the scan.
+  const commentTargets = coreFacade.commentPolicy.filterCommentTargets(commentScope);
   // why: read from the snapshot taken before this handler patches anything, so a credit written by the previous
   // stop is still visible when the gate it belongs to runs below.
   const pendingCredit = handoff.pending_lesson_credit;
@@ -619,12 +628,12 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   // rate cannot — was the rule ever needed — by running the checker while the prose is absent. A measurement that
   // can change what it measures is not a measurement ([/decisions/ad-027.md](/decisions/ad-027.md)).
   if (
-    codeTargets.length > 0 &&
+    commentTargets.length > 0 &&
     coreFacade.observe.shouldObserve(policy.observe, "comments", policy.comments.enabled)
   ) {
     const hits = await coreFacade.commentPolicy.scanAddedComments(
       root,
-      codeTargets,
+      commentTargets,
       policy.comments.mode,
       turnBase,
     );
@@ -641,15 +650,17 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
         rule: "comments",
         // why: a language the catalog does not carry produces no findings, which reads identically to "the
         // property held". Naming the extensions is the difference between a clean reading and a blind spot.
-        unknown_extensions: coreFacade.commentPolicy.unknownExtensions(codeTargets).join(",") || "none",
+        // Scoped to `commentScope`, not `commentTargets` — the target set is already syntax-known by
+        // construction, so it could never report the gap it exists to name.
+        unknown_extensions: coreFacade.commentPolicy.unknownExtensions(commentScope).join(",") || "none",
       },
     });
   }
 
-  if (policy.comments.enabled && policy.comments.onViolation === "followup" && codeTargets.length > 0) {
+  if (policy.comments.enabled && policy.comments.onViolation === "followup" && commentTargets.length > 0) {
     const hits = await coreFacade.commentPolicy.scanAddedComments(
       root,
-      codeTargets,
+      commentTargets,
       policy.comments.mode,
       turnBase,
     );

package/tools/doctor.ts

@@ -578,6 +578,53 @@ export function checkShadowedPolicy(root: string): Check[] {
   ];
 }
 
+/**
+ * invariant: a malformed config is reported distinctly from an absent one. `readProjectPolicyRaw` used to
+ * collapse both to `null` — the silent half of the bug this closes, since a trailing comma degrades the
+ * whole project tier to defaults with nothing telling the operator why.
+ */
+export function checkConfigKeys(root: string): Check[] {
+  const status = coreFacade.capability.readProjectPolicyStatus(root);
+  if (status.status === "absent") {
+    return [];
+  }
+  if (status.status === "malformed") {
+    return [
+      {
+        level: "warn",
+        name: "project policy parses",
+        detail: `${projectConfigPath(root)} failed to parse: ${status.error}. Until fixed, this tier silently falls back to defaults.`,
+      },
+    ];
+  }
+  // why: DEFAULTS, not resolvedWithoutProjectTier() — the machine tier is operator content, not the shape
+  // the harness reads. An unknown key present in both tiers used to recurse into it instead of naming it,
+  // because resolvedWithoutProjectTier() carries the machine tier's own keys, unknown or not, straight through.
+  const resolved = coreFacade.policy.DEFAULTS as unknown as Record<string, unknown>;
+  const unknown = coreFacade.policy.unknownKeys(status.value, resolved);
+  const mismatched = coreFacade.policy.typeMismatches(status.value, resolved);
+  const checks: Check[] = [];
+  if (unknown.length > 0) {
+    const shown = unknown.slice(0, 6).map((key) => key.path);
+    const rest = unknown.length - shown.length;
+    checks.push({
+      level: "warn",
+      name: "project policy has an unknown key",
+      detail: `${plural(unknown.length, "key")} in this project's config ${unknown.length === 1 ? "matches" : "match"} nothing the harness reads: ${shown.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}. Delete ${unknown.length === 1 ? "it" : "them"}, or check for a typo.`,
+    });
+  }
+  if (mismatched.length > 0) {
+    const shown = mismatched.slice(0, 6).map((m) => `${m.path} (expected ${m.expected}, got ${m.actual})`);
+    const rest = mismatched.length - shown.length;
+    checks.push({
+      level: "warn",
+      name: "project policy has a type mismatch",
+      detail: `${plural(mismatched.length, "key")} in this project's config ${mismatched.length === 1 ? "does" : "do"} not match the type the harness expects: ${shown.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}.`,
+    });
+  }
+  return checks;
+}
+
 export function checkLessonBudget(root: string): Check[] {
   const policy = coreFacade.policy.loadPolicy(root);
   const config = policy.intelligence.lessons;
@@ -751,6 +798,7 @@ export function checkProjectPolicy(root: string): Check[] {
     ...checkLessonHealth(root),
     ...checkLessonBudget(root),
     ...checkShadowedPolicy(root),
+    ...checkConfigKeys(root),
     ...checkSubagentAllowlist(root),
     ...checkPolicyDivergence(root),
     ...checkGateScope(root),

package/tools/init-project.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
+import { NPM_PACKAGE, runtimeVersion } from "../bin/tlc-cli.ts";
 import { applyCursorWiring, renderCursorHooksDocument } from "../bin/write-user-hooks.mjs";
 import type { WiringEntry } from "../src/contracts/index.ts";
 import { coreFacade } from "../src/core/index.ts";
@@ -234,6 +235,20 @@ export function configLine(outcome: ApplyOutcome): string {
     : `wrote ${outcome.configPath}`;
 }
 
+/**
+ * why: major.minor, not bare major — this package is pre-1.0, where a 0.x minor bump can also break,
+ * so pinning only the major would silently serve a schema from the wrong minor. An unreadable
+ * `package.json` falls back to unpkg's latest resolution rather than a version string that goes stale.
+ */
+function schemaUrl(): string {
+  const version = runtimeVersion(runtimeHome());
+  if (version === null) {
+    return `https://unpkg.com/${NPM_PACKAGE}/schema.json`;
+  }
+  const [major, minor] = version.split(".");
+  return `https://unpkg.com/${NPM_PACKAGE}@${major}.${minor}/schema.json`;
+}
+
 export function applyPlan(
   root: string,
   flags: InitFlags,
@@ -254,7 +269,10 @@ export function applyPlan(
   const kept = existsSync(configPath) && !flags.stdinJson;
   if (!kept) {
     mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(configPath, `${JSON.stringify(policy, null, 2)}\n`);
+    writeFileSync(
+      configPath,
+      `${JSON.stringify({ $schema: schemaUrl(), ...(policy as Record<string, unknown>) }, null, 2)}\n`,
+    );
   }
 
   const launcher = launcherPath();