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

package/schema.json

@@ -0,0 +1,545 @@
+{
+  "additionalProperties": false,
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "type": "number"
+    },
+    "mode": {
+      "enum": [
+        "focus",
+        "paired",
+        "solo"
+      ],
+      "type": "string"
+    },
+    "projectName": {
+      "type": "string"
+    },
+    "codePaths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "grind": {
+      "$ref": "#/definitions/Partial%3C%7Benabled%3Aboolean%3BmaxLoops%3Anumber%3BlintCommand%3Astring%5B%5D%7Cnull%3BtestCommand%3Astring%5B%5D%7Cnull%3BappendFiles%3Aimport(%22.%2Fsrc%2Fcore%2Fgate%2Fgate.types%22%2C%7Bwith%3A%7B%22resolution-mode%22%3A%22import%22%7D%7D).AppendFilesMode%3B%7D%3E"
+    },
+    "shipGate": {
+      "$ref": "#/definitions/Partial%3C%7Benabled%3Aboolean%3BruntimePathPrefixes%3Astring%5B%5D%3BruntimePathExcludes%3Astring%5B%5D%3BevidenceDir%3Astring%7Cnull%3BevidenceMaxAgeHours%3Anumber%3BemptyDiffAntiShip%3Aboolean%3BclaimWindowMinutes%3Anumber%3B%7D%3E"
+    },
+    "subagents": {
+      "$ref": "#/definitions/Partial%3C%7BenforceAllowlist%3Aboolean%3BrequireModel%3Aboolean%3BallowedModels%3Aimport(%22.%2Fsrc%2Fcore%2Fpolicy%2Fpolicy.types%22%2C%7Bwith%3A%7B%22resolution-mode%22%3A%22import%22%7D%7D).ProviderScoped%3Cstring%3E%3BblockedPatterns%3Aimport(%22.%2Fsrc%2Fcore%2Fpolicy%2Fpolicy.types%22%2C%7Bwith%3A%7B%22resolution-mode%22%3A%22import%22%7D%7D).ProviderScoped%3Cstring%3E%3BminEffort%3A%22low%22%7C%22medium%22%7C%22high%22%7C%22xhigh%22%7C%22max%22%7Cnull%3BblockParentFast%3Aboolean%3BblockMode%3A%22deny%22%7C%22ask%22%3BreadOnlyTypes%3Astring%5B%5D%3B%7D%3E"
+    },
+    "docs": {
+      "$ref": "#/definitions/Partial%3C%7Bcommand%3Astring%5B%5D%7Cnull%3Bseverity%3A%22deny%22%7C%22warn%22%3B%7D%3E"
+    },
+    "observe": {
+      "description": "why: observation runs a rail's checker while the rail is not enforcing, so the harness can tell \"the model\nalready does this\" from \"the rule works\". Opt-in and default empty: it costs a diff scan per turn and answers a\nquestion only an operator who is asking it needs answered.",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "rails": {
+          "description": "Rails to observe by name. An unknown name is inert rather than an error — a rail may not exist yet.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "enabled",
+        "rails"
+      ]
+    },
+    "comments": {
+      "$ref": "#/definitions/Partial%3C%7Benabled%3Aboolean%3BonViolation%3A%22followup%22%7C%22off%22%3Bmode%3Aimport(%22.%2Fsrc%2Fcore%2Fpolicy%2Fpolicy.types%22%2C%7Bwith%3A%7B%22resolution-mode%22%3A%22import%22%7D%7D).CommentMode%3B%7D%3E"
+    },
+    "supplyChain": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "enabled"
+      ]
+    },
+    "duplication": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "minRun": {
+          "description": "why: the window is the only knob, because it is the only one calibration moved. Six is where matches stopped being punctuation.",
+          "type": "number"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "enabled",
+        "minRun"
+      ]
+    },
+    "obs": {
+      "$ref": "#/definitions/Partial%3C%7BglobalSpool%3Aboolean%3BincludePayloads%3Aboolean%3BmaxAttrChars%3Anumber%3BsessionCostAlertUsd%3Anumber%7Cnull%3BretentionDays%3Anumber%3B%7D%3E"
+    },
+    "untrustedContent": {
+      "$ref": "#/definitions/Partial%3C%7Benabled%3Aboolean%3Bmode%3Aimport(%22.%2Fsrc%2Fcore%2Funtrusted%2Funtrusted.types%22%2C%7Bwith%3A%7B%22resolution-mode%22%3A%22import%22%7D%7D).UntrustedMode%3BextraTools%3Astring%5B%5D%3BextraCommandPatterns%3Astring%5B%5D%3B%7D%3E"
+    },
+    "planGate": {
+      "$ref": "#/definitions/Partial%3C%7Benabled%3Aboolean%3BwindowMinutes%3Anumber%3B%7D%3E"
+    },
+    "rules": {
+      "$ref": "#/definitions/Partial%3C%7Benabled%3Aboolean%3B%7D%3E"
+    },
+    "shell": {
+      "$ref": "#/definitions/Partial%3C%7BcatastrophicAsk%3Aboolean%3BstallDetection%3Aboolean%3BstallRepeatThreshold%3Anumber%3B%7D%3E"
+    },
+    "intelligence": {
+      "additionalProperties": false,
+      "type": "object",
+      "properties": {
+        "gapFeedback": {
+          "type": "boolean"
+        },
+        "failureClassification": {
+          "type": "boolean"
+        },
+        "progressiveHandoff": {
+          "type": "boolean"
+        },
+        "progressiveContext": {
+          "type": "boolean"
+        },
+        "autopilot": {
+          "type": "boolean"
+        },
+        "idleTurnGate": {
+          "type": "boolean"
+        },
+        "budgetContinue": {
+          "type": "boolean"
+        },
+        "budgetContinueAfterLoops": {
+          "type": "number"
+        },
+        "lessons": {
+          "$ref": "#/definitions/Partial%3Cimport(%22.%2Fsrc%2Fcore%2Fpolicy%2Fpolicy.types%22%2C%7Bwith%3A%7B%22resolution-mode%22%3A%22import%22%7D%7D).LessonsPolicyConfig%3E"
+        }
+      }
+    },
+    "mcpPrime": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "bootstrapExtra": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "definitions": {
+    "AppendFilesMode": {
+      "enum": [
+        "always",
+        "auto",
+        "never"
+      ],
+      "type": "string"
+    },
+    "import(\"./src/core/policy/policy.types\",{with:{\"resolution-mode\":\"import\"}}).ProviderScoped<string>": {
+      "anyOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "$ref": "#/definitions/Record%3Cstring%2Cstring%5B%5D%3E"
+        }
+      ]
+    },
+    "Record<string,string[]>": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "CommentMode": {
+      "description": "`declared` requires a reason marker, `strict` accepts no added comment at all, and `resolvable` is `declared`\nplus the question neither can ask: does the comment mean anything to a reader who was not in the session that\nwrote it ([/decisions/ad-070.md](/decisions/ad-070.md))?",
+      "enum": [
+        "declared",
+        "resolvable",
+        "strict"
+      ],
+      "type": "string"
+    },
+    "UntrustedMode": {
+      "description": "`frame` states once per turn that outside content is data. `enforce` adds the question framing cannot ask —\ndid this command come from that content — and answers it verbatim\n([/decisions/ad-077.md](/decisions/ad-077.md)).",
+      "enum": [
+        "enforce",
+        "frame"
+      ],
+      "type": "string"
+    },
+    "LessonsSyncMode": {
+      "description": "How the durable provider view is decided. `auto` asks the host: a provider that does not deliver context from\nits session-start hook has no other route, so the view is written there and not where the hook works\n([/decisions/ad-050.md](/decisions/ad-050.md)).",
+      "enum": [
+        "always",
+        "auto",
+        "never"
+      ],
+      "type": "string"
+    },
+    "Partial<{enabled:boolean;maxLoops:number;lintCommand:string[]|null;testCommand:string[]|null;appendFiles:import(\"./src/core/gate/gate.types\",{with:{\"resolution-mode\":\"import\"}}).AppendFilesMode;}>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "maxLoops": {
+          "type": "number"
+        },
+        "lintCommand": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "testCommand": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "appendFiles": {
+          "enum": [
+            "always",
+            "auto",
+            "never"
+          ],
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{enabled:boolean;runtimePathPrefixes:string[];runtimePathExcludes:string[];evidenceDir:string|null;evidenceMaxAgeHours:number;emptyDiffAntiShip:boolean;claimWindowMinutes:number;}>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "runtimePathPrefixes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "runtimePathExcludes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "evidenceDir": {
+          "type": [
+            "null",
+            "string"
+          ]
+        },
+        "evidenceMaxAgeHours": {
+          "type": "number"
+        },
+        "emptyDiffAntiShip": {
+          "type": "boolean"
+        },
+        "claimWindowMinutes": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{enforceAllowlist:boolean;requireModel:boolean;allowedModels:import(\"./src/core/policy/policy.types\",{with:{\"resolution-mode\":\"import\"}}).ProviderScoped<string>;blockedPatterns:import(\"./src/core/policy/policy.types\",{with:{\"resolution-mode\":\"import\"}}).ProviderScoped<string>;minEffort:\"low\"|\"medium\"|\"high\"|\"xhigh\"|\"max\"|null;blockParentFast:boolean;blockMode:\"deny\"|\"ask\";readOnlyTypes:string[];}>": {
+      "type": "object",
+      "properties": {
+        "enforceAllowlist": {
+          "type": "boolean"
+        },
+        "requireModel": {
+          "type": "boolean"
+        },
+        "allowedModels": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "$ref": "#/definitions/Record%3Cstring%2Cstring%5B%5D%3E"
+            }
+          ]
+        },
+        "blockedPatterns": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "$ref": "#/definitions/Record%3Cstring%2Cstring%5B%5D%3E"
+            }
+          ]
+        },
+        "minEffort": {
+          "anyOf": [
+            {
+              "enum": [
+                "high",
+                "low",
+                "max",
+                "medium",
+                "xhigh"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "blockParentFast": {
+          "type": "boolean"
+        },
+        "blockMode": {
+          "enum": [
+            "ask",
+            "deny"
+          ],
+          "type": "string"
+        },
+        "readOnlyTypes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{command:string[]|null;severity:\"deny\"|\"warn\";}>": {
+      "type": "object",
+      "properties": {
+        "command": {
+          "description": "Null means the gate does not exist for this project.",
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "severity": {
+          "enum": [
+            "deny",
+            "warn"
+          ],
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{enabled:boolean;onViolation:\"followup\"|\"off\";mode:import(\"./src/core/policy/policy.types\",{with:{\"resolution-mode\":\"import\"}}).CommentMode;}>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "onViolation": {
+          "enum": [
+            "followup",
+            "off"
+          ],
+          "type": "string"
+        },
+        "mode": {
+          "description": "`declared` requires a reason marker, `strict` accepts no added comment at all, and `resolvable` is `declared`\nplus the question neither can ask: does the comment mean anything to a reader who was not in the session that\nwrote it ([/decisions/ad-070.md](/decisions/ad-070.md))?",
+          "enum": [
+            "declared",
+            "resolvable",
+            "strict"
+          ],
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{globalSpool:boolean;includePayloads:boolean;maxAttrChars:number;sessionCostAlertUsd:number|null;retentionDays:number;}>": {
+      "type": "object",
+      "properties": {
+        "globalSpool": {
+          "type": "boolean"
+        },
+        "includePayloads": {
+          "type": "boolean"
+        },
+        "maxAttrChars": {
+          "type": "number"
+        },
+        "sessionCostAlertUsd": {
+          "type": [
+            "null",
+            "number"
+          ]
+        },
+        "retentionDays": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{enabled:boolean;mode:import(\"./src/core/untrusted/untrusted.types\",{with:{\"resolution-mode\":\"import\"}}).UntrustedMode;extraTools:string[];extraCommandPatterns:string[];}>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "mode": {
+          "description": "`frame` states once per turn that outside content is data. `enforce` adds the question framing cannot ask —\ndid this command come from that content ([/decisions/ad-077.md](/decisions/ad-077.md))?",
+          "enum": [
+            "enforce",
+            "frame"
+          ],
+          "type": "string"
+        },
+        "extraTools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "extraCommandPatterns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{enabled:boolean;windowMinutes:number;}>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "windowMinutes": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{enabled:boolean;}>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<{catastrophicAsk:boolean;stallDetection:boolean;stallRepeatThreshold:number;}>": {
+      "type": "object",
+      "properties": {
+        "catastrophicAsk": {
+          "type": "boolean"
+        },
+        "stallDetection": {
+          "type": "boolean"
+        },
+        "stallRepeatThreshold": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Partial<import(\"./src/core/policy/policy.types\",{with:{\"resolution-mode\":\"import\"}}).LessonsPolicyConfig>": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "maxInjectSession": {
+          "type": "number"
+        },
+        "maxInjectRetry": {
+          "type": "number"
+        },
+        "maxCharsSession": {
+          "type": "number"
+        },
+        "maxCharsRetry": {
+          "type": "number"
+        },
+        "promoteHitCount": {
+          "type": "number"
+        },
+        "decayLambda": {
+          "type": "number"
+        },
+        "projectBoost": {
+          "type": "number"
+        },
+        "syncRulesFile": {
+          "description": "How the durable provider view is decided. `auto` asks the host: a provider that does not deliver context from\nits session-start hook has no other route, so the view is written there and not where the hook works\n([/decisions/ad-050.md](/decisions/ad-050.md)).",
+          "enum": [
+            "always",
+            "auto",
+            "never"
+          ],
+          "type": "string"
+        },
+        "gardenOnSessionEnd": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/src/core/capability/capability.store.ts

@@ -27,8 +27,34 @@ export function loadCatalog(home = runtimeHome()): CapabilityCatalog | null {
   return raw;
 }
 
+export type ConfigReadStatus =
+  | { status: "absent" }
+  | { status: "parsed"; value: Record<string, unknown> }
+  | { status: "malformed"; error: string };
+
+/**
+ * why: `readJson` already reads this file but collapses "absent" and "malformed" to the same `null`
+ * — the exact silent-corruption gap `doctor` needs to close, so this is a second, tagged reader.
+ */
+export function readProjectPolicyStatus(projectDir: string): ConfigReadStatus {
+  const path = projectConfigPath(projectDir);
+  if (!existsSync(path)) {
+    return { status: "absent" };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    // why: a JSON Schema meta-key, not a Policy field — see the identical strip in policy.loader.ts,
+    // this is the second, independent read of the same file.
+    delete parsed.$schema;
+    return { status: "parsed", value: parsed };
+  } catch (error) {
+    return { status: "malformed", error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 export function readProjectPolicyRaw(projectDir: string): Record<string, unknown> | null {
-  return readJson<Record<string, unknown>>(projectConfigPath(projectDir));
+  const result = readProjectPolicyStatus(projectDir);
+  return result.status === "parsed" ? result.value : null;
 }
 
 function runtimeSeenPath(projectDir: string): string {

package/src/core/comment-policy/comment-policy.service.ts

@@ -61,6 +61,15 @@ export function isCommentLine(text: string, file = ""): boolean {
   return matchesSyntax(text, syntax) && !TOOL_DIRECTIVE.test(text);
 }
 
+/**
+ * invariant: no `codePaths` param. Taking one needs `policy.loader.ts` → `policy.defaults.ts` →
+ * `duplication.service.ts`, which imports this module back for `matchesSyntax` — an import cycle. The
+ * caller scopes by `codePaths` first; this filters what's left by syntax alone.
+ */
+export function filterCommentTargets(relativePaths: string[]): string[] {
+  return relativePaths.filter((path) => syntaxFor(path) !== null);
+}
+
 export function declaresReason(text: string): boolean {
   return DECLARED_REASON.test(text);
 }

package/src/core/comment-policy/comment-syntax.catalog.ts

@@ -155,14 +155,19 @@ export const COMMENT_SYNTAX: readonly CommentSyntaxEntry[] = [
     extensions: [".sql"],
     line: ["--"],
     block: [["/*", "*/"]],
-    middle: ["*"],
+    // hazard: `middle: ["*"]` matched any line starting with a bare `*`, comment or not. In C-family languages
+    // that is safe — a line rarely opens with `*` outside a block continuation — but `SELECT *` does exactly
+    // that, so a multi-line query flagged its own projection as an undeclared comment.
+    middle: [],
   },
   {
     id: "css",
     extensions: [".css", ".scss", ".sass", ".less"],
     line: ["//"],
     block: [["/*", "*/"]],
-    middle: ["*"],
+    // hazard: same defect as sql above — the universal selector `*` and a bare `*,` in a reset both start with
+    // `*`, so `middle: ["*"]` flagged ordinary CSS as an undeclared comment.
+    middle: [],
   },
   {
     id: "yaml",

package/src/core/comment-policy/comment-syntax.store.ts

@@ -49,10 +49,19 @@ export function syntaxFor(file: string): CommentSyntax | null {
   return lookupSyntax(file);
 }
 
+// why: an image, a font, a lockfile or a test snapshot was never a candidate for a catalog entry — it carries
+// no comment syntax to add. Reporting it as a coverage gap turns the signal an operator can act on into noise
+// they learn to ignore.
+const NOT_A_LANGUAGE =
+  /\.(png|jpe?g|gif|ico|bmp|webp|svg|woff2?|ttf|eot|otf|pdf|zip|gz|tgz|tar|lockb|snap)$/i;
+
 /** why: the operator needs the coverage gap named. A language nobody listed is a rail that silently passes. */
 export function unknownExtensions(files: readonly string[]): string[] {
   const unknown = new Set<string>();
   for (const file of files) {
+    if (NOT_A_LANGUAGE.test(file)) {
+      continue;
+    }
     if (lookupSyntax(file) === null) {
       const name = file.toLowerCase().replace(/\\/g, "/").split("/").pop() ?? file;
       const dot = name.lastIndexOf(".");

package/src/core/core.facade.ts

@@ -16,6 +16,7 @@ import {
 import {
   loadCatalog,
   readProjectPolicyRaw,
+  readProjectPolicyStatus,
   readRuntimeSeen,
   writeRuntimeSeen,
 } from "./capability/capability.store.ts";
@@ -23,6 +24,7 @@ import { ENABLE_HINT } from "./capability/capability.types.ts";
 import {
   commentViolationMessage,
   declaresReason,
+  filterCommentTargets,
   findAddedComments,
   isCommentLine,
   scanAddedComments,
@@ -132,7 +134,7 @@ import {
 import { operatorBootstrapLines } from "./policy/policy.operator.ts";
 import { isOperatorMode, OPERATOR_MODES } from "./policy/policy.posture.ts";
 import { activeRails } from "./policy/policy.rails.ts";
-import { pruneShadowed, shadowedKeys } from "./policy/policy.shadow.ts";
+import { pruneShadowed, shadowedKeys, typeMismatches, unknownKeys } from "./policy/policy.shadow.ts";
 import { forProvider } from "./policy/policy.types.ts";
 import { checkCollision, heartbeat, register, release, sweepStale } from "./presence/presence.service.ts";
 import { freshness, freshnessMessage, mayReplace, shouldRefetch } from "./pricing/pricing.freshness.ts";
@@ -263,6 +265,7 @@ export const coreFacade = {
     ENABLE_HINT,
     loadCatalog,
     readProjectPolicyRaw,
+    readProjectPolicyStatus,
     readRuntimeSeen,
     writeRuntimeSeen,
     isAvailableNotEnabled,
@@ -415,6 +418,8 @@ export const coreFacade = {
     resolvedWithoutProjectTier,
     shadowedKeys,
     pruneShadowed,
+    unknownKeys,
+    typeMismatches,
     resolveProjectPosture,
     resolveProjectSyncMode,
     OPERATOR_MODES,
@@ -448,6 +453,7 @@ export const coreFacade = {
     isCommentLine,
     declaresReason,
     commentViolationMessage,
+    filterCommentTargets,
     unknownExtensions,
     KNOWN_EXTENSION_COUNT,
   },