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

package/bin/generate-schema.ts

@@ -0,0 +1,67 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import * as TJS from "typescript-json-schema";
+
+/**
+ * why: `PartialPolicy`, not `Policy` — a human-written config is always partial, and `Policy`'s every
+ * field being non-optional would mark a minimal config invalid in every editor.
+ */
+const ROOT_TYPE = "PartialPolicy";
+const SOURCE_FILE = "src/core/policy/policy.types.ts";
+
+function compilerOptionsFrom(root: string): Record<string, unknown> {
+  const raw = JSON.parse(readFileSync(join(root, "tsconfig.json"), "utf8")) as {
+    compilerOptions: Record<string, unknown>;
+  };
+  return raw.compilerOptions;
+}
+
+/**
+ * invariant: `noExtraProps` is what makes an unknown key (the `format` class of bug) a schema
+ * violation instead of something the schema silently accepts.
+ */
+export function generateConfigSchema(rawRoot: string): Record<string, unknown> {
+  // why: TypeScript prints an import() type query against its own canonicalised path — a `.` segment
+  // or backslashes in the caller's spelling would silently defeat redactBuildPath's string match below.
+  const root = resolve(rawRoot);
+  const program = TJS.getProgramFromFiles([join(root, SOURCE_FILE)], compilerOptionsFrom(root), root);
+  const schema = TJS.generateSchema(program, ROOT_TYPE, {
+    required: true,
+    noExtraProps: true,
+    strictNullChecks: true,
+  });
+  if (schema === null) {
+    throw new Error(`typescript-json-schema produced no schema for ${ROOT_TYPE} in ${SOURCE_FILE}`);
+  }
+  const properties = (schema as { properties?: Record<string, unknown> }).properties ?? {};
+  const withSchemaProp = {
+    ...schema,
+    properties: {
+      // why: a JSON Schema meta-key, not a PartialPolicy field — typescript-json-schema never emits
+      // it, and `noExtraProps` would otherwise make every real config with a `$schema` line invalid.
+      $schema: { type: "string" },
+      ...properties,
+    },
+  };
+  return redactBuildPath(withSchemaProp, root);
+}
+
+/**
+ * hazard: a field typed `Partial<Policy["grind"]>` (an indexed-access type, not its own named alias)
+ * has no clean name to give its `$ref`, so the generator falls back to printing the full structural
+ * type — including an `import("<absolute path>")` type query for every cross-file reference inside
+ * it. That absolute path is the machine that ran the build, encoded twice: once raw in `$ref` targets
+ * that are also definition keys, once URI-percent-encoded in the `$ref` string itself. Published
+ * as-is, it would leak the CI runner's (or a contributor's) filesystem layout into a public schema.
+ */
+// why: TypeScript always prints module specifiers with forward slashes, regardless of host OS — on
+// Windows `root` itself is backslash-separated, so the raw string alone never matches what got printed.
+function redactBuildPath(schema: Record<string, unknown>, root: string): Record<string, unknown> {
+  const posixRoot = root.replace(/\\/g, "/");
+  const candidates = [root, posixRoot, encodeURIComponent(root), encodeURIComponent(posixRoot)];
+  let serialized = JSON.stringify(schema);
+  for (const candidate of candidates) {
+    serialized = serialized.split(candidate).join(".");
+  }
+  return JSON.parse(serialized) as Record<string, unknown>;
+}

package/bin/tlc-build.mjs

@@ -16,7 +16,7 @@
  * entrypoint, and the missing bundle only surfaces when a hook fires on somebody's machine.
  */
 import { spawnSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -115,3 +115,28 @@ for (const entry of readdirSync(dist, { withFileTypes: true })) {
 }
 
 console.log(`tlc-build: ok (${bundles} bundles)`);
+
+// why: dynamic, and a missing module degrades rather than fails — typescript-json-schema is a
+// devDependency, absent from a plain install, and the dist rebuild above is this script's real
+// recovery contract (bin/tlc-exec.mjs's "dist missing, run tlc-build.mjs" message). Never committed
+// (.gitignore) either way, so nothing here needs the freshness gate `dist/` no longer has.
+let generateConfigSchema;
+try {
+  ({ generateConfigSchema } = await import("./generate-schema.ts"));
+} catch (error) {
+  if (error?.code !== "ERR_MODULE_NOT_FOUND") {
+    throw error;
+  }
+  console.log("tlc-build: schema.json skipped — typescript-json-schema is not installed here");
+}
+
+if (generateConfigSchema) {
+  try {
+    const schema = generateConfigSchema(root);
+    writeFileSync(join(root, "schema.json"), `${JSON.stringify(schema, null, 2)}\n`);
+    console.log("tlc-build: schema.json ok");
+  } catch (error) {
+    console.error(`tlc-build: schema.json generation failed — ${error instanceof Error ? error.message : error}`);
+    process.exit(1);
+  }
+}

package/bin/tlc-cli.ts

@@ -20,6 +20,7 @@ import {
   flagsDir,
   isOnPath,
   launcherBinDir,
+  loopsDir,
   machineHome,
   projectConfigPath,
   projectStateDir,
@@ -193,6 +194,32 @@ export function setPaused(root: string, on: boolean): string {
   return "gates ACTIVE again";
 }
 
+/**
+ * why: the operator's escape hatch for a stuck gate — `blockers` and `previous_gaps` are project-wide,
+ * so a grind-cap or stagnation signal from one session can block every later subagent until either a
+ * clean stop clears it or this runs. Denied from inside a session by `policy-surface-write`.
+ */
+export async function resetStuckState(root: string): Promise<string> {
+  const cleared = await coreFacade.handoff.clearStuckSignals(root);
+  const dir = loopsDir(root);
+  let loopFiles = 0;
+  if (existsSync(dir)) {
+    loopFiles = readdirSync(dir).length;
+    rmSync(dir, { recursive: true, force: true });
+  }
+  if (cleared.length === 0 && loopFiles === 0) {
+    return "nothing stuck — no blockers and no grind-loop state to clear";
+  }
+  const parts: string[] = [];
+  if (cleared.length > 0) {
+    parts.push(`cleared blockers for: ${cleared.join(", ")}`);
+  }
+  if (loopFiles > 0) {
+    parts.push(`reset ${loopFiles} grind-loop counter(s)`);
+  }
+  return parts.join("; ");
+}
+
 // hazard: this used to map `focus` onto a second spelling before writing, so the word the operator typed and the
 // word the config field stored were different — and a config written from the documented word then matched no
 // branch at all. One word per posture, and nothing translates.
@@ -263,14 +290,9 @@ export function handoffScreen(report: HandoffReport): Screen {
         rows.push({ label, value: String(value), level });
       }
     }
-    for (const [label, list] of [
-      ["in progress", slice.in_progress],
-      ["pending", slice.pending],
-      ["gaps", slice.previous_gaps?.map((gap) => gap.summary)],
-    ] as const) {
-      if (list && list.length > 0) {
-        rows.push({ label, value: list.slice(0, 6).join(" | ") });
-      }
+    const gaps = slice.previous_gaps?.map((gap) => gap.summary);
+    if (gaps && gaps.length > 0) {
+      rows.push({ label: "gaps", value: gaps.slice(0, 6).join(" | ") });
     }
     sections.push({ title: `${name} (updated ${slice.updated_at})`, rows });
   }
@@ -863,6 +885,7 @@ TOPICS
 
 CONTROL
   tlc harness grind [on|off]   tlc harness pause | resume   tlc harness mode solo|paired|focus
+  tlc harness reset                clear a stuck blocker/grind-loop signal from the handoff
   tlc harness gate test-command <cmd> [args...]   tlc harness gate lint-command <cmd> [args...]
   tlc harness attest              tamper-evident record of what each session ran under
   tlc harness policy              show a policy that changed out of band; accept <path> to clear it
@@ -1128,6 +1151,7 @@ export type Action =
   | { kind: "grind"; on: boolean }
   | { kind: "pause" }
   | { kind: "resume" }
+  | { kind: "reset" }
   | { kind: "mode"; value: string }
   | { kind: "gate"; field: GateField; argv: string[] }
   | { kind: "attest" }
@@ -1193,6 +1217,8 @@ export function route(args: string[]): Action {
     case "resume":
     case "r":
       return { kind: "resume" };
+    case "reset":
+      return { kind: "reset" };
     case "mode":
     case "m": {
       const modeArg = args[1];
@@ -1612,13 +1638,13 @@ function runInstall(toolArgs: string[], root: string): never {
   process.exit(r.status ?? 1);
 }
 
-function main(argv: string[]): void {
+async function main(argv: string[]): Promise<void> {
   const root = resolveProjectRoot();
   const group = (argv[0] ?? "").toLowerCase();
   if (group !== "harness") {
     console.error(`unknown: ${argv[0] ?? ""}`);
     console.error(
-      "usage: tlc harness <status|doctor|help|grind|pause|resume|mode|obs|prices|lessons|init|update|test|build>",
+      "usage: tlc harness <status|doctor|help|grind|pause|resume|reset|mode|obs|prices|lessons|init|update|test|build>",
     );
     process.exit(1);
   }
@@ -1744,6 +1770,9 @@ function main(argv: string[]): void {
     case "resume":
       console.log(setPaused(root, false));
       break;
+    case "reset":
+      console.log(await resetStuckState(root));
+      break;
     case "mode":
       try {
         console.log(setMode(root, action.value));
@@ -1794,5 +1823,8 @@ function main(argv: string[]): void {
 }
 
 if (import.meta.main) {
-  main(process.argv.slice(2));
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
 }

package/config.example.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://unpkg.com/@tech-leads-club/harness-toolkit@0.5/schema.json",
   "version": 1,
   "mode": "solo",
   "subagents": {