@tech-leads-club/harness-toolkit 0.5.1 → 0.7.0

package/src/core/handoff/handoff.service.ts

@@ -25,6 +25,36 @@ export function readHandoff(root: string, provider: string): ResolvedHandoff {
   return { ...file.shared, ...slice };
 }
 
+const CLEARED_SLICE: Partial<HandoffProviderSlice> = {
+  blockers: undefined,
+  previous_gaps: undefined,
+  last_failure_category: undefined,
+  next_action: undefined,
+};
+
+function hasStuckSignal(slice: HandoffProviderSlice): boolean {
+  return (Object.keys(CLEARED_SLICE) as (keyof HandoffProviderSlice)[]).some(
+    (field) => slice[field] !== undefined,
+  );
+}
+
+/**
+ * why: an operator's escape hatch. These are the exact fields `subagent-stop.ts` reads as "unfinished
+ * work" — clearing anything wider would erase state no gate is stuck on.
+ */
+export async function clearStuckSignals(root: string): Promise<string[]> {
+  const file = readHandoffFile(root);
+  const cleared: string[] = [];
+  for (const [provider, slice] of Object.entries(file.by_provider)) {
+    if (!hasStuckSignal(slice)) {
+      continue;
+    }
+    await patchHandoff(root, provider, { slice: CLEARED_SLICE });
+    cleared.push(provider);
+  }
+  return cleared;
+}
+
 export function readForeignSlices(root: string, provider: string): ForeignSlice[] {
   const file = readHandoffFile(root);
   const foreign: ForeignSlice[] = [];

package/src/core/handoff/handoff.types.ts

@@ -18,8 +18,6 @@ export type HandoffProviderSlice = {
   session_key?: string;
   session_narrative?: string;
   completed?: string[];
-  in_progress?: string[];
-  pending?: string[];
   last_ship_claim_at?: string;
   last_ship_claim_snippet?: string;
   last_ship_claim_kind?: "structured";

package/src/core/lesson/lesson.types.ts

@@ -89,4 +89,9 @@ export type PendingLessonCredit = {
   gate: string;
   ids: string[];
   at: string;
+  // why: the handoff is per-project, not per-session, so without this a lesson injected for session A's
+  // failing gate gets credited by whichever session B next happens to pass the same gate — helped/neutral
+  // it never earned. Optional so an on-disk record from before this field existed still credits once,
+  // the same legacy fallback AD-038 used for pre-existing lesson records.
+  sessionKey?: string;
 };

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/core/turn/turn.failure-signals.ts

@@ -104,10 +104,12 @@ export function formatCarriedGaps(gaps: readonly GateGap[], limit = CARRIED_GAP_
   return lines.join("\n");
 }
 
+// why: `current` goes first — it is this turn's fresh result, `prior` is carried history. Iterating
+// prior-first let a saturated 12-item carry silently drop every fresh gap this turn found.
 export function mergeGaps(prior: GateGap[] | undefined, current: GateGap[], max = 12): GateGap[] {
   const seen = new Set<string>();
   const out: GateGap[] = [];
-  for (const gap of [...(prior ?? []), ...current]) {
+  for (const gap of [...current, ...(prior ?? [])]) {
     const key = `${gap.gate}|${gap.summary}`;
     if (seen.has(key)) {
       continue;

package/src/entrypoints/stop.ts

@@ -151,20 +151,26 @@ export function stopLockWaitMs(env: NodeJS.ProcessEnv = process.env): number {
  * invariant: consumed exactly once. The pending credit is cleared whether or not any lesson matched, so a single
  * injection cannot be graded twice by two later runs of the same gate.
  *
- * hazard: the gate name is compared. Without it, lessons injected for `lint` would be credited by whichever gate
- * ran next, which is `test` in this handler and would read as help the lesson never gave.
+ * hazard: the gate name is compared, and the session that earned the credit is compared — without either,
+ * lessons injected for `lint` would be credited by whichever gate ran next, or by whichever session next
+ * happened to run this gate on the same per-project handoff `blockers` lives on, crediting help a session
+ * that never saw the lesson did not give ([/decisions/ad-107.md](/decisions/ad-107.md) is the same family).
  */
 async function creditPendingLessons(args: {
   root: string;
   provider: string;
   pending: PendingLessonCredit | undefined;
   gate: string;
+  sessionKey: string;
   passed: boolean;
 }): Promise<void> {
   const { pending } = args;
   if (!pending || pending.gate !== args.gate || pending.ids.length === 0) {
     return;
   }
+  if (pending.sessionKey !== undefined && pending.sessionKey !== args.sessionKey) {
+    return;
+  }
   await coreFacade.lesson.creditLessons(args.root, pending.ids, args.passed ? "helped" : "neutral");
   await coreFacade.handoff.patchHandoff(args.root, args.provider, {
     slice: { pending_lesson_credit: undefined },
@@ -231,6 +237,7 @@ async function runLockedGate(args: {
     provider: args.provider,
     pending: args.pendingCredit,
     gate: args.gate,
+    sessionKey: args.sessionKey,
     passed: artifact.passed,
   });
   return { kind: "ran", artifact, reused: cached !== null };
@@ -334,6 +341,7 @@ async function failGate(args: {
           gate: args.gate,
           ids: selected.usedIds,
           at: new Date().toISOString(),
+          sessionKey: args.sessionKey,
         },
       },
     });
@@ -470,16 +478,14 @@ 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 by `codeTargets`'s nine-extension
-  // regex shared with grind and duplication — a Terraform- or SQL-heavy project changed no file `codeTargets`
-  // would ever keep, and the rail never ran regardless of `comments.mode`. Scoped to `codePaths` here rather
-  // than inside `filterCommentTargets` itself, which would need `policy.loader.ts` and create an import cycle
-  // through `duplication.service.ts` (see the invariant on `filterCommentTargets`).
+  // 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`, not this — a language the catalog does not know is
-  // still named even though it was just excluded from the scan.
+  // 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.
@@ -506,11 +512,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   }
 
   const intel = policy.intelligence;
-  const unfinishedWork =
-    Boolean(handoff.blockers) ||
-    Boolean(handoff.previous_gaps?.length) ||
-    Boolean(handoff.pending?.length) ||
-    Boolean(handoff.in_progress?.length);
+  const unfinishedWork = Boolean(handoff.blockers) || Boolean(handoff.previous_gaps?.length);
   if (
     intel.idleTurnGate &&
     coreFacade.turn.endedWithoutActing({

package/src/entrypoints/subagent-stop.ts

@@ -4,8 +4,8 @@ import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
 import { observeForRules } from "./support.ts";
 
-// why: no legacy predecessor covers subagent.stop verification — this reuses the same unfinished-work
-// signal (blockers/pending/in_progress/previous_gaps) already carried on the handoff slice.
+// why: no legacy predecessor covers subagent.stop verification — this reuses the blockers/previous_gaps
+// signal already carried on the handoff slice.
 export const subagentStopHandler: Handler = async (
   event: HarnessEvent,
   ctx: HandlerContext,
@@ -15,11 +15,13 @@ export const subagentStopHandler: Handler = async (
   await observeForRules(event, ctx);
 
   const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
+  // why: `blockers` is per-project, and every Task subagent shares the parent's session_id
+  // (anthropics/claude-code#7881), so this cannot tell its own subagent apart from another. A "budget"
+  // category means the session's turn budget ran out, not that the tree is broken — unlike a gate
+  // failure, it is not valid evidence here ([/decisions/ad-073.md](/decisions/ad-073.md)).
+  const isBudgetBlocker = handoff.last_failure_category === "budget";
   const unfinishedWork =
-    Boolean(handoff.blockers) ||
-    Boolean(handoff.previous_gaps?.length) ||
-    Boolean(handoff.pending?.length) ||
-    Boolean(handoff.in_progress?.length);
+    (Boolean(handoff.blockers) && !isBudgetBlocker) || Boolean(handoff.previous_gaps?.length);
 
   if (!unfinishedWork) {
     return { kind: "abstain" };

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();