@joshuafolkken/kit 1.872.0

package/dist/hooks/chunk-2ANGT3XM.js

@@ -0,0 +1,375 @@
+import {
+  time_batch_guard
+} from "./chunk-IFLDYJMD.js";
+import {
+  hook_decision
+} from "./chunk-5VUUF3ZV.js";
+import {
+  cost_blocks,
+  cost_transcript,
+  time_bundle_call,
+  time_shell,
+  time_spans
+} from "./chunk-CMHANU3F.js";
+
+// scripts/delegation/investigation-reads.ts
+import path from "node:path";
+
+// scripts/delegation/delegation-policy.ts
+var DELEGATE_VERDICT = "delegate";
+var KEEP_VERDICT = "keep";
+var INVESTIGATION_FILE_THRESHOLD = 3;
+var DELEGATABLE_STEPS = [
+  {
+    name: "gate-fix",
+    does: "apply the fixes the verification gate already named \u2014 a lint rule, a type error, a spelling the dictionary rejects",
+    verifier: "`pnpm josh gate` is re-run; a wrong fix fails it again, and the failure names the file"
+  },
+  {
+    name: "epic-child",
+    // One row, two entry points: an epic's child under `epicrun` and one named issue of a
+    // `backlogrun` are the same unit — same brief, same summary, same verifier
+    // (joshuafolkken/kit#1149, folded from `queue` into `backlogrun` by joshuafolkken/kit#1984). A
+    // second row for the batch would be the clone `CLAUDE.md` prohibits.
+    does: "run one child of a batch end to end in an isolated unit \u2014 an epic's child or one named issue of a `backlogrun` alike \u2014 plan, verification gate, PR, merge \u2014 and return only its summary to the parent loop",
+    verifier: "the parent reads the child's state from GitHub with `pnpm josh issue:state`, not from the summary; a child reported done but not merged is still open, which is the failure showing rather than a run continuing, and its own gate, `/code-review` and CI ran inside the unit before `followup` would touch the PR"
+  },
+  {
+    name: "followup-filing",
+    // The late-run follow-up filing chain — issue:scout → file the Issue → epic:bundle → epic --add
+    // — is a dependency chain `batch:guard` correctly keeps one call per step, and what makes it
+    // expensive is the ~340k context it runs in at the tail of a run, not the step count
+    // (joshuafolkken/kit#1892). A fresh unit runs the same chain at a small context, and the review
+    // round cap already composed the finding text, so what the unit is handed is mechanical: run the
+    // four commands and act on their deterministic answers. This is not `batch:guard`'s business —
+    // the chain stays one call per step; delegation only moves it to a cheaper context.
+    does: "run the late-run follow-up filing chain in an isolated unit \u2014 issue:scout, file the Issue, epic:bundle, epic --add \u2014 given the finding text the parent already composed, and return the new Issue number and the epic:bundle answer",
+    verifier: "the parent reads the filed Issue from GitHub with `pnpm josh issue:state <new>`, not the unit's summary; a follow-up reported filed but not created is still absent, the way `epic-child`'s reported-done-but-not-merged child is still open. The finding text came from the parent and `issue:scout` / `epic:bundle` are deterministic, so the unit's work is the mechanical execution `issue:state` confirms"
+  },
+  {
+    name: "implementation-unit",
+    // The Step 0 change list already decided *what* to change — that design stays in the main line,
+    // which is why `design` is rejected below. What is delegated is the *writing* of one unit of that
+    // list, and only a unit whose files are disjoint from every other dispatched unit: two subagents
+    // editing one file in parallel race on it. `pnpm josh fanout` confirms that disjointness
+    // mechanically, so the split is read off the file sets rather than judged (joshuafolkken/kit#2345).
+    does: "implement one file-disjoint unit of the Step 0 change list in an isolated subagent \u2014 the files it edits shared with no other dispatched unit, confirmed by `pnpm josh fanout` \u2014 and return the edited files, never a summary standing in for the diff; the main line keeps integration and the verification gate. Units that share a file, or an Issue that will not split, stay serial",
+    verifier: "the parent runs the whole integrated change through `pnpm josh gate` and a `/code-review` subagent it would run anyway \u2014 a unit's mistake fails the same gate and review a serial edit passes through, so delegating writes nothing the backstop does not already catch, and the `pnpm josh fanout` disjointness removes the one failure parallelism adds, two units colliding on a file"
+  },
+  {
+    name: "survey",
+    does: "read across many files and report where something appears \u2014 every reference to a symbol, which documents carry a marker",
+    verifier: "the reported locations are checked directly; a fabricated or missed location does not survive one `grep` of what it claimed"
+  },
+  {
+    name: "investigation",
+    // Not `survey`: that row reports *where* something appears and is checked by one `grep`, while
+    // this one reports *how the subject works* and is checked by opening the lines it cited. The two
+    // verifiers differ, so widening `survey` would put both in one field and lose the boundary below.
+    // **No ordinal.** `${N}rd` would print `1rd` for any other threshold, past a test that only looks
+    // for the numeral, so the count is phrased as a plain "N or more".
+    does: `read the Issue's subject to find out how it currently works \u2014 once ${String(INVESTIGATION_FILE_THRESHOLD)} or more files the run will not edit have to be read \u2014 and return the conclusion plus the \`file:line\` citations that support it, never the file text, which would put the cost back where it was. A throwaway probe script is written, run and deleted inside the unit, which returns its output alone`,
+    verifier: "the parent opens the cited lines; a conclusion those lines do not support fails there, and reading a handful of cited regions costs far less than redoing the reading. The unit reports what the code does and never what to change \u2014 deciding that is `diagnosis`, which stays kept, so a unit returning a root cause would be delegating the rejected row under this name"
+  }
+];
+var REJECTED_STEPS = [
+  {
+    name: "notify-body",
+    because: "no verifier. A notification with a wrong body is sent and read as though it were right; nothing in the run disagrees with it afterwards"
+  },
+  {
+    name: "issue-comment",
+    because: "no verifier. A decision log or completion comment that says the wrong thing is the record, so there is nothing left to check it against"
+  },
+  {
+    name: "status-read",
+    because: "a misread routes the run to the wrong child, and no later step disagrees. Running the status command is already cheap; what is expensive is acting on it, which is not this step"
+  },
+  {
+    name: "diagnosis",
+    because: "a wrong root cause produces a fix that passes the gate and leaves the defect"
+  },
+  {
+    name: "design",
+    because: "the cost of a wrong design is paid by every step after it"
+  },
+  {
+    name: "split-assessment",
+    because: "a missed split widens one Issue into a batch nobody authorized"
+  },
+  {
+    name: "review",
+    because: "the review is the last thing between a defect and a merge; a cheaper one finds less"
+  }
+];
+function find_step(name) {
+  return DELEGATABLE_STEPS.find((step2) => step2.name === name.trim());
+}
+function verdict_for(name) {
+  return find_step(name) === void 0 ? KEEP_VERDICT : DELEGATE_VERDICT;
+}
+function rejection_for(name) {
+  return REJECTED_STEPS.find((step2) => step2.name === name.trim());
+}
+function reason_for(name) {
+  const step2 = find_step(name);
+  if (step2 !== void 0) return `delegatable: ${step2.verifier}`;
+  const rejected = rejection_for(name);
+  if (rejected !== void 0) return `kept deliberately: ${rejected.because}`;
+  return "kept by default: not on the delegatable list, and the list is the whole of it";
+}
+var delegation_policy = {
+  DELEGATE_VERDICT,
+  INVESTIGATION_FILE_THRESHOLD,
+  KEEP_VERDICT,
+  DELEGATABLE_STEPS,
+  REJECTED_STEPS,
+  find_step,
+  verdict_for,
+  rejection_for,
+  reason_for
+};
+
+// scripts/delegation/investigation-reads.ts
+var READ_TOOLS = /* @__PURE__ */ new Set(["Read"]);
+var DELEGATION_TOOLS = /* @__PURE__ */ new Set(["Agent", "Task"]);
+var CONTENT_READ_COMMANDS = [
+  "bat",
+  "cat",
+  "head",
+  "less",
+  "more",
+  "nl",
+  "sed",
+  "tail"
+];
+var CONTENT_READ_LABELS = new Set(
+  CONTENT_READ_COMMANDS.map((command) => time_shell.bash_label(command))
+);
+var REASON = `\u26D4 investigation: ${String(delegation_policy.INVESTIGATION_FILE_THRESHOLD)} files read and not edited since the last delegated unit, so the reading from here goes to a unit of its own. Ask \`pnpm josh delegate investigation\`, then brief a unit with what the main line has already concluded and what is left to find out; it returns the conclusion plus its \`file:line\` citations, never the file text. Keep a read in the main line only where this run will edit that file \u2014 an \`Edit\` cannot be issued against text you do not hold. This run's own instructions and the harness's own session files \u2014 a backgrounded call's output, a persisted tool result, this session's scratchpad \u2014 are never counted, so they are not what took the count here. The rule is \`.claude/skills/workflow-commands/SKILL.md\` \u2192 \xA72b, "The pre-implementation reading".`;
+var INSTRUCTION_PATHS = ["prompts", ".claude/skills"];
+var INSTRUCTION_FILES = /* @__PURE__ */ new Set(["CLAUDE.md", "AGENTS.md", "GEMINI.md"]);
+var REPOSITORY_ROOT = process.cwd();
+function resolved(target) {
+  return path.resolve(REPOSITORY_ROOT, target);
+}
+function repository_relative(absolute) {
+  return path.relative(REPOSITORY_ROOT, absolute);
+}
+function is_instruction_document(target) {
+  const relative = repository_relative(resolved(target));
+  const segments = relative.split(path.sep);
+  return INSTRUCTION_FILES.has(segments.at(-1) ?? "") || INSTRUCTION_PATHS.some((prefix) => relative.startsWith(`${prefix}${path.sep}`));
+}
+var SESSION_TEMP_SEGMENT = /^claude-\d+$/u;
+var SESSION_STATE_SEGMENTS = cost_transcript.TRANSCRIPT_ROOT.split(path.sep);
+var HARNESS_OUTPUT_DIRECTORY = "tasks";
+var HARNESS_OUTPUT_EXTENSION = ".output";
+var FILE_SEGMENT_INDEX = -1;
+var PARENT_SEGMENT_INDEX = -2;
+function has_state_root(segments, index) {
+  return SESSION_STATE_SEGMENTS.every((segment, offset) => segments[index + offset] === segment);
+}
+function is_harness_output(segments) {
+  return segments.some((segment) => SESSION_TEMP_SEGMENT.test(segment)) && segments.at(PARENT_SEGMENT_INDEX) === HARNESS_OUTPUT_DIRECTORY && (segments.at(FILE_SEGMENT_INDEX) ?? "").endsWith(HARNESS_OUTPUT_EXTENSION);
+}
+function is_outside_repository(absolute) {
+  return repository_relative(absolute).startsWith("..");
+}
+function is_session_artifact(target) {
+  const absolute = resolved(target);
+  const segments = absolute.split(path.sep);
+  if (!is_outside_repository(absolute)) return false;
+  return segments.some((_segment, index) => has_state_root(segments, index)) || is_harness_output(segments);
+}
+function is_subject_file(target) {
+  return !is_instruction_document(target) && !is_session_artifact(target);
+}
+function is_nameable_file(target) {
+  return !target.includes("*") && !target.includes("?");
+}
+function is_content_read(label) {
+  return READ_TOOLS.has(label) || CONTENT_READ_LABELS.has(label);
+}
+function subject_targets(targets) {
+  return targets.filter((target) => is_nameable_file(target) && is_subject_file(target)).map((target) => resolved(target));
+}
+function call_targets(call) {
+  return subject_targets(time_bundle_call.call_facts(call.name, call.input).targets);
+}
+function delegation_instant(span) {
+  return span === void 0 ? hook_decision.NEVER_MS : span.ended_ms;
+}
+function is_failed_outcome(span) {
+  return span.outcome === time_spans.FAILED_OUTCOME;
+}
+function edited_files(spans) {
+  const written = spans.filter((span) => !is_failed_outcome(span)).flatMap((span) => subject_targets(span.writes));
+  return new Set(written);
+}
+function add_all(pending, targets, at_ms) {
+  for (const target of targets) if (!pending.has(target)) pending.set(target, at_ms);
+}
+function apply_span(pending, span, edited) {
+  if (DELEGATION_TOOLS.has(span.label)) {
+    pending.clear();
+    return;
+  }
+  if (!is_content_read(span.label) || is_failed_outcome(span)) return;
+  const fresh = subject_targets(span.targets).filter((target) => !edited.has(target));
+  add_all(pending, fresh, span.ended_ms);
+}
+function last_delegation_ms(spans) {
+  return delegation_instant(spans.findLast((span) => DELEGATION_TOOLS.has(span.label)));
+}
+function pending_after(pending, since_ms) {
+  return [...pending.values()].filter((at_ms) => at_ms > since_ms).length;
+}
+function tally_of(text, since_ms = hook_decision.NEVER_MS) {
+  const { spans, started_ms } = time_spans.parse_timeline(text);
+  const edited = edited_files(spans);
+  const pending = /* @__PURE__ */ new Map();
+  for (const span of spans) apply_span(pending, span, edited);
+  return {
+    pending: [...pending.keys()],
+    pending_since: pending_after(pending, since_ms),
+    reset_ms: last_delegation_ms(spans),
+    window_start_ms: started_ms,
+    edited
+  };
+}
+function projected_count(pending, call, edited = /* @__PURE__ */ new Set()) {
+  return (/* @__PURE__ */ new Set([...pending, ...call_targets(call).filter((target) => !edited.has(target))])).size;
+}
+function is_at_threshold(pending_count) {
+  return pending_count + 1 >= delegation_policy.INVESTIGATION_FILE_THRESHOLD;
+}
+function has_cleared_the_disarm(tally, refused_at_ms) {
+  return tally.reset_ms > refused_at_ms || refused_at_ms < tally.window_start_ms;
+}
+function is_rearmed(tally, refused_at_ms) {
+  if (refused_at_ms === hook_decision.NEVER_MS || has_cleared_the_disarm(tally, refused_at_ms)) {
+    return true;
+  }
+  return is_at_threshold(tally.pending_since);
+}
+function is_unit_transcript(transcript) {
+  return transcript.split(path.sep).includes(cost_transcript.UNIT_DIRECTORY);
+}
+function is_unit_run(run) {
+  return run !== void 0 && is_unit_transcript(run.transcript);
+}
+function is_refusable_command(call) {
+  const label = time_shell.bash_label(time_shell.bash_command(call.input));
+  return CONTENT_READ_LABELS.has(label) && time_batch_guard.is_read_only_call(call);
+}
+function is_refusable_call(call) {
+  if (call_targets(call).length === 0) return false;
+  if (READ_TOOLS.has(call.name)) return true;
+  return call.name === cost_blocks.BASH_TOOL && is_refusable_command(call);
+}
+function should_block(text, call, refused_at_ms, run) {
+  if (!is_refusable_call(call) || is_unit_run(run)) return false;
+  const tally = tally_of(text, refused_at_ms);
+  if (!is_at_threshold(tally.pending.length)) return false;
+  return projected_count(tally.pending, call, tally.edited) > tally.pending.length && is_rearmed(tally, refused_at_ms);
+}
+var EDIT_TARGET_CLASS = "edit targets";
+var UNDER_THRESHOLD_CLASS = "under the threshold";
+var REFUSED_CLASS = "refused";
+var LET_THROUGH_CLASS = "let through";
+var READ_CLASSES = [
+  EDIT_TARGET_CLASS,
+  UNDER_THRESHOLD_CLASS,
+  REFUSED_CLASS,
+  LET_THROUGH_CLASS
+];
+var NEVER_REFUSED_LABELS = /* @__PURE__ */ new Set([time_shell.bash_label("sed")]);
+function tally_now(replay) {
+  return {
+    pending: [...replay.pending.keys()],
+    pending_since: pending_after(replay.pending, replay.refused_at_ms),
+    reset_ms: replay.reset_ms,
+    window_start_ms: replay.window_start_ms,
+    edited: replay.edited
+  };
+}
+function reaches_threshold(replay, targets) {
+  const added = targets.filter((target) => !replay.pending.has(target));
+  return added.length > 0 && is_at_threshold(replay.pending.size);
+}
+function would_refuse(replay, span) {
+  if (NEVER_REFUSED_LABELS.has(span.label)) return false;
+  return is_rearmed(tally_now(replay), replay.refused_at_ms);
+}
+function class_of(replay, span, edited) {
+  const fresh = subject_targets(span.targets).filter((target) => !edited.has(target));
+  if (fresh.length === 0) return EDIT_TARGET_CLASS;
+  if (!reaches_threshold(replay, fresh)) return UNDER_THRESHOLD_CLASS;
+  return would_refuse(replay, span) ? REFUSED_CLASS : LET_THROUGH_CLASS;
+}
+function read_class(replay, span, edited) {
+  if (!is_content_read(span.label)) return void 0;
+  if (subject_targets(span.targets).length === 0) return void 0;
+  return class_of(replay, span, edited);
+}
+function step(replay, span, edited) {
+  if (DELEGATION_TOOLS.has(span.label)) {
+    replay.reset_ms = span.ended_ms;
+    apply_span(replay.pending, span, edited);
+    return void 0;
+  }
+  const found = read_class(replay, span, edited);
+  if (found === REFUSED_CLASS) replay.refused_at_ms = span.ended_ms;
+  apply_span(replay.pending, span, edited);
+  return found;
+}
+var FIRST_SPAN = 0;
+function fresh_replay(spans, edited) {
+  return {
+    pending: /* @__PURE__ */ new Map(),
+    reset_ms: hook_decision.NEVER_MS,
+    window_start_ms: spans[FIRST_SPAN]?.ended_ms ?? hook_decision.NEVER_MS,
+    refused_at_ms: hook_decision.NEVER_MS,
+    edited
+  };
+}
+function classified_reads(spans) {
+  const edited = edited_files(spans);
+  const replay = fresh_replay(spans, edited);
+  const reads = [];
+  for (const [index, span] of spans.entries()) {
+    const found = step(replay, span, edited);
+    if (found !== void 0) reads.push({ found, index });
+  }
+  return reads;
+}
+var investigation_reads = {
+  CONTENT_READ_COMMANDS,
+  EDIT_TARGET_CLASS,
+  LET_THROUGH_CLASS,
+  READ_CLASSES,
+  REFUSED_CLASS,
+  UNDER_THRESHOLD_CLASS,
+  classified_reads,
+  subject_targets,
+  DELEGATION_TOOLS,
+  READ_TOOLS,
+  REASON,
+  is_at_threshold,
+  is_content_read,
+  is_instruction_document,
+  is_rearmed,
+  is_refusable_call,
+  is_session_artifact,
+  is_subject_file,
+  projected_count,
+  repository_relative,
+  resolved,
+  should_block,
+  tally_of
+};
+
+export {
+  investigation_reads
+};

package/dist/hooks/chunk-2EI5GBSW.js

@@ -0,0 +1,42 @@
+import {
+  investigation_reads
+} from "./chunk-4A7UVP2P.js";
+import {
+  lane_guard_policy
+} from "./chunk-NFQSUDBN.js";
+import {
+  hook_decision
+} from "./chunk-33YRTKM7.js";
+
+// scripts/delegation/investigation-guard.ts
+import { text } from "node:stream/consumers";
+import { fileURLToPath } from "node:url";
+var SWITCH_ENV_KEY = "JOSH_INVESTIGATION_GUARD";
+function should_block(tail, call, refused_at_ms, run) {
+  if (lane_guard_policy.is_suppressed_here("investigation")) return false;
+  return investigation_reads.should_block(tail, call, refused_at_ms, run);
+}
+var GUARD = hook_decision.create_transcript_guard({
+  prefix: "josh-investigation-guard-",
+  switch_key: SWITCH_ENV_KEY,
+  is_candidate: investigation_reads.is_refusable_call,
+  should_block,
+  reason: investigation_reads.REASON
+});
+var investigation_refusal = GUARD.refusal;
+var { is_enabled, refusal_path } = GUARD;
+var { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision;
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (process.stdin.isTTY) hook_decision.report_no_payload("investigation:guard");
+  else hook_decision.write_decision(await text(process.stdin), investigation_refusal);
+}
+
+export {
+  SWITCH_ENV_KEY,
+  investigation_refusal,
+  is_enabled,
+  refusal_path,
+  deny_envelope,
+  load_environment_file,
+  DISABLED_VALUES
+};