@loopover/miner 0.1.0

package/lib/coding-task-spec.d.ts

@@ -0,0 +1,44 @@
+import type { AcceptanceCriteria, FeasibilityGateResult, FeasibilityVerdict, IssueRecord, PullRequestRecord } from "@loopover/engine";
+
+export type CodingTaskIssue = { number: number; title: string; body?: string | null | undefined; labels?: string[] | undefined };
+
+export type CodingTaskClaimLedger = {
+  listClaims(filter: { repoFullName: string; status: string }): Array<{ issueNumber: number }>;
+};
+
+export type CodingTaskContext = { issues: IssueRecord[]; pullRequests: PullRequestRecord[] };
+
+export function buildCodingTaskFeasibility(
+  repoFullName: string,
+  issue: CodingTaskIssue,
+  context: CodingTaskContext,
+  claimLedger: CodingTaskClaimLedger,
+): FeasibilityGateResult;
+
+export function buildCodingTaskAcceptanceCriteria(issue: CodingTaskIssue, feasibility: FeasibilityGateResult): AcceptanceCriteria;
+
+export function writeAcceptanceCriteriaFile(workingDirectory: string, acceptanceCriteria: AcceptanceCriteria): { written: boolean; path: string | null };
+
+export type CodingTaskSpecInput = {
+  repoFullName: string;
+  issue: CodingTaskIssue;
+  context: CodingTaskContext;
+  claimLedger: CodingTaskClaimLedger;
+  workingDirectory: string;
+};
+
+export type CodingTaskSpecResult =
+  | { ready: false; verdict: FeasibilityVerdict; feasibility: FeasibilityGateResult }
+  | {
+      ready: true;
+      verdict: FeasibilityVerdict;
+      feasibility: FeasibilityGateResult;
+      acceptanceCriteriaPath: string;
+      instructions: string;
+      title: string;
+      body: string | undefined;
+      labels: string[] | undefined;
+      linkedIssues: number[];
+    };
+
+export function buildCodingTaskSpec(input: CodingTaskSpecInput): CodingTaskSpecResult;

package/lib/coding-task-spec.js

@@ -0,0 +1,183 @@
+import { closeSync, constants as fsConstants, openSync, realpathSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import {
+  ACCEPTANCE_CRITERIA_FILENAME,
+  buildAcceptanceCriteria,
+  buildCollisionReport,
+  buildFeasibilityVerdict,
+  buildPromptPacket,
+  feasibilityInputFromPreStartCheck,
+  serializeAcceptanceCriteria,
+  shouldWriteAcceptanceCriteria,
+} from "@loopover/engine";
+
+// Coding-task-spec builder (#5132, Wave 3.5 follow-up). The second gap discovered alongside #5132's CLI
+// wiring: `IterateLoopInput.title`/`instructions`/`acceptanceCriteriaPath` had no builder anywhere in this
+// package. `packages/gittensory-engine/src/miner/acceptance-criteria.ts` already composes a PromptPacket +
+// FeasibilityGateResult into an immutable AcceptanceCriteria document (and deliberately does NOT write it --
+// "actually writing it into the attempt's worktree is the worktree primitive's job", per its own header) --
+// this module is that caller: derives the four inputs from a real target issue + the already-fetched
+// SelfReviewContext (#5145), then writes the file for real.
+//
+// issueStatus is intentionally left undefined when computing feasibility: buildIssueQualityReport (the only
+// thing that could supply it) lives only in root src/signals/engine.ts and has never been extracted into
+// @loopover/engine (same gap #5145's own header documents for `issueQuality`). This is not a
+// fabrication -- feasibilityInputFromPreStartCheck's OWN documented default for a missing
+// issueQualityStatus/lifecycle is "ready", the same honest-default precedent already established.
+
+function buildTaskBrief(issue) {
+  const body = (issue.body ?? "").trim();
+  return body ? `${issue.title}\n\n${body}` : issue.title;
+}
+
+function buildConstraints(issue) {
+  if (!Array.isArray(issue.labels) || issue.labels.length === 0) return "";
+  return `Labels on this issue: ${issue.labels.join(", ")}.`;
+}
+
+function buildFeasibilityNotes(feasibility) {
+  return [feasibility.summary, ...feasibility.avoidReasons, ...feasibility.raiseReasons].join("\n");
+}
+
+// Only ever resolves to "claimed"/"unclaimed": the claim ledger's own ClaimStatus vocabulary
+// ("active"|"released"|"expired") has no "solved" concept for FeasibilityClaimStatus's "solved" value to
+// map from -- that would need real evidence a PR already resolved the issue (e.g. a merged, linked PR),
+// which this function doesn't have access to. Not fabricated; genuinely undetectable from claim data alone.
+function resolveClaimStatus(claimLedger, repoFullName, issueNumber) {
+  const claims = claimLedger.listClaims({ repoFullName, status: "active" });
+  return claims.some((claim) => claim.issueNumber === issueNumber) ? "claimed" : "unclaimed";
+}
+
+// The target issue's own raw cluster risk from buildCollisionReport (newly exported from
+// @loopover/engine's public barrel) -- "none" when the issue isn't part of any cluster at all.
+// DELIBERATELY does NOT apply #5145's ">= 2 pull_request items" threshold: that gate exists specifically to
+// stop inDuplicateCluster (self-review, "does MY OWN just-created submission look redundant") from firing on
+// the ordinary case of one existing PR already legitimately closing the issue. Feasibility asks a different
+// question -- "should I even START working on this issue" -- where an issue already having ANY open PR
+// against it (buildCollisionReport's pairwise "shared linked issue" rule, which fires at "high" for exactly
+// one PR) is a meaningful, real caution signal, not a false positive to filter out.
+function resolveDuplicateClusterRisk(repoFullName, issues, pullRequests, issueNumber) {
+  const report = buildCollisionReport(repoFullName, issues, pullRequests);
+  const cluster = report.clusters.find((entry) => entry.items.some((item) => item.type === "issue" && item.number === issueNumber));
+  return cluster ? cluster.risk : "none";
+}
+
+/**
+ * Compute the feasibility verdict for one target issue, from real signals: whether the issue is present in
+ * the fetched context, its real claim status (the claim ledger), and its real duplicate-cluster risk
+ * (buildCollisionReport over the fetched issues/pullRequests). issueStatus is left to its documented
+ * "ready" default -- see this file's header for why that's honest, not fabricated.
+ *
+ * @param {string} repoFullName
+ * @param {{ number: number }} issue
+ * @param {{ issues: Array<{ number: number }>, pullRequests: unknown[] }} context
+ * @param {{ listClaims: (filter: { repoFullName: string, status: string }) => Array<{ issueNumber: number }> }} claimLedger
+ * @returns {import("@loopover/engine").FeasibilityGateResult}
+ */
+export function buildCodingTaskFeasibility(repoFullName, issue, context, claimLedger) {
+  const found = context.issues.some((candidate) => candidate.number === issue.number);
+  const claimStatus = resolveClaimStatus(claimLedger, repoFullName, issue.number);
+  const duplicateClusterRisk = resolveDuplicateClusterRisk(repoFullName, context.issues, context.pullRequests, issue.number);
+  const feasibilityInput = feasibilityInputFromPreStartCheck({ found, claimStatus, duplicateClusterRisk });
+  return buildFeasibilityVerdict(feasibilityInput);
+}
+
+/**
+ * Compose the immutable AcceptanceCriteria document for one target issue + its feasibility verdict.
+ *
+ * @param {{ title: string, body?: string | null, labels?: string[] }} issue
+ * @param {import("@loopover/engine").FeasibilityGateResult} feasibility
+ * @returns {import("@loopover/engine").AcceptanceCriteria}
+ */
+export function buildCodingTaskAcceptanceCriteria(issue, feasibility) {
+  const promptPacket = buildPromptPacket({
+    taskBrief: buildTaskBrief(issue),
+    constraints: buildConstraints(issue),
+    feasibilityNotes: buildFeasibilityNotes(feasibility),
+    retrievalContext: "",
+  });
+  return buildAcceptanceCriteria({ promptPacket, feasibility });
+}
+
+/**
+ * Write the acceptance-criteria document into the prepared worktree -- only when its own verdict authorizes
+ * it (shouldWriteAcceptanceCriteria: verdict === "go"). A raise/avoid verdict writes nothing; the caller is
+ * expected to abandon the attempt rather than start it, per acceptance-criteria.ts's own documented design.
+ *
+ * @param {string} workingDirectory
+ * @param {import("@loopover/engine").AcceptanceCriteria} acceptanceCriteria
+ * @returns {{ written: boolean, path: string | null }}
+ */
+function assertContainedPath(root, path) {
+  const relativePath = relative(root, path);
+  if (relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath))) return;
+  throw new Error(`Refusing to write acceptance criteria outside the worktree: ${path}`);
+}
+
+export function writeAcceptanceCriteriaFile(workingDirectory, acceptanceCriteria) {
+  if (!shouldWriteAcceptanceCriteria(acceptanceCriteria.verdict)) return { written: false, path: null };
+  const root = realpathSync(workingDirectory);
+  const path = join(root, ACCEPTANCE_CRITERIA_FILENAME);
+  assertContainedPath(root, path);
+
+  let fd;
+  try {
+    fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+    writeFileSync(fd, serializeAcceptanceCriteria(acceptanceCriteria), "utf8");
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+
+  return { written: true, path };
+}
+
+/**
+ * The coding-agent driver's own prompt text (agent-sdk-driver.ts's header: "forwarded verbatim as the
+ * prompt -- the acceptance-criteria document already lives inside the worktree", so this points to it
+ * rather than repeating its content).
+ */
+function buildInstructions(issue, acceptanceCriteriaPath) {
+  return [
+    `Resolve the following GitHub issue in this repository: #${issue.number} -- ${issue.title}`,
+    "",
+    (issue.body ?? "").trim(),
+    "",
+    `A structured acceptance-criteria document describing what "done" means for this attempt is at ${acceptanceCriteriaPath} -- read it and ensure your change satisfies every criterion before finishing.`,
+  ].join("\n");
+}
+
+/**
+ * Full composition: feasibility -> acceptance criteria -> (if authorized) write the file -> instructions.
+ * Returns `ready: false` (with the computed feasibility verdict, for the caller to report) when the
+ * verdict is `raise`/`avoid` -- the caller should abandon the attempt rather than proceed with no real
+ * acceptance-criteria file on disk.
+ *
+ * @param {{
+ *   repoFullName: string, issue: { number: number, title: string, body?: string | null, labels?: string[] },
+ *   context: { issues: Array<{ number: number }>, pullRequests: unknown[] },
+ *   claimLedger: { listClaims: (filter: { repoFullName: string, status: string }) => Array<{ issueNumber: number }> },
+ *   workingDirectory: string,
+ * }} input
+ * @returns {import("./coding-task-spec.js").CodingTaskSpecResult}
+ */
+export function buildCodingTaskSpec(input) {
+  const feasibility = buildCodingTaskFeasibility(input.repoFullName, input.issue, input.context, input.claimLedger);
+  const acceptanceCriteria = buildCodingTaskAcceptanceCriteria(input.issue, feasibility);
+  const writeResult = writeAcceptanceCriteriaFile(input.workingDirectory, acceptanceCriteria);
+
+  if (!writeResult.written) {
+    return { ready: false, verdict: feasibility.verdict, feasibility };
+  }
+
+  return {
+    ready: true,
+    verdict: feasibility.verdict,
+    feasibility,
+    acceptanceCriteriaPath: writeResult.path,
+    instructions: buildInstructions(input.issue, writeResult.path),
+    title: input.issue.title,
+    body: input.issue.body ?? undefined,
+    labels: input.issue.labels,
+    linkedIssues: [input.issue.number],
+  };
+}

package/lib/config-precedence.d.ts

@@ -0,0 +1,25 @@
+import type { MinerActionMode, MinerKillSwitchScope } from "@loopover/engine";
+import type { CodingAgentExecutionMode } from "@loopover/engine";
+import type { ForgeConfig } from "./forge-config.js";
+
+export function resolveDocumentedKillSwitchScope(
+  env: Record<string, string | undefined>,
+  repoPaused: boolean,
+): MinerKillSwitchScope;
+
+export function resolveDocumentedGovernorActionMode(input: {
+  killSwitchScope: MinerKillSwitchScope;
+  repoLiveModeOptIn?: unknown;
+  globalLiveModeOptIn: boolean;
+}): MinerActionMode;
+
+export function resolveDocumentedCodingAgentMode(
+  env: Record<string, string | undefined>,
+  cliLiveFlag: boolean,
+): CodingAgentExecutionMode;
+
+export function resolveDocumentedDiscoverTokenEnvVar(input?: {
+  cliTokenEnv?: string | null;
+  optionsTokenEnv?: string | null;
+  forge?: Partial<ForgeConfig>;
+}): string;

package/lib/config-precedence.js

@@ -0,0 +1,38 @@
+/** Documented config-resolution helpers for precedence tests (#5198). Thin wrappers over existing resolvers —
+ *  no new precedence rules. See `docs/config-precedence.md`. */
+
+import {
+  isGlobalMinerCodingAgentPause,
+  resolveCodingAgentExecutionMode,
+  resolveMinerActionMode,
+  resolveMinerKillSwitch,
+} from "@loopover/engine";
+import { resolveForgeConfig } from "./forge-config.js";
+
+/** Kill-switch scope from operator env + parsed goal-spec `killSwitch.paused`. */
+export function resolveDocumentedKillSwitchScope(env, repoPaused) {
+  const global = /^(1|true|yes|on)$/i.test(env.GITTENSORY_MINER_KILL_SWITCH ?? "");
+  return resolveMinerKillSwitch({ global, repoPaused });
+}
+
+/** Governor action mode from kill-switch scope + env/yml live opt-ins. */
+export function resolveDocumentedGovernorActionMode(input) {
+  return resolveMinerActionMode(input);
+}
+
+/** Coding-agent mode from operator env pause + CLI `--live` (via agentDryRun). */
+export function resolveDocumentedCodingAgentMode(env, cliLiveFlag) {
+  return resolveCodingAgentExecutionMode({
+    globalPaused: isGlobalMinerCodingAgentPause(env),
+    agentDryRun: cliLiveFlag ? false : true,
+  });
+}
+
+/** Discover credential env var name: CLI > programmatic > forge default. Mirrors discover-cli.js. */
+export function resolveDocumentedDiscoverTokenEnvVar(input = {}) {
+  const parsedTokenEnv = input.cliTokenEnv ?? null;
+  const optionsTokenEnv = input.optionsTokenEnv ?? null;
+  if (parsedTokenEnv !== null) return parsedTokenEnv;
+  if (optionsTokenEnv !== null) return optionsTokenEnv;
+  return resolveForgeConfig(input.forge).tokenEnvVar;
+}

package/lib/deny-check.d.ts

@@ -0,0 +1,11 @@
+export type ParsedDenyCheckArgs =
+  | {
+      tool: string;
+      input: Record<string, unknown>;
+      json: boolean;
+    }
+  | { error: string };
+
+export function parseDenyCheckArgs(args: string[]): ParsedDenyCheckArgs;
+
+export function runDenyCheck(args: string[]): number;

package/lib/deny-check.js

@@ -0,0 +1,76 @@
+import { evaluateDenyHooks } from "./deny-hooks.js";
+import { argsWantJson, reportCliFailure } from "./cli-error.js";
+
+const DENY_CHECK_USAGE =
+  "Usage: gittensory-miner hooks check --tool <name> --input <json> [--json]";
+
+function parseToolInput(raw) {
+  if (raw === undefined) {
+    return { error: "Missing value for --input." };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { error: "Tool input must be a JSON object." };
+    }
+    return { value: parsed };
+  } catch {
+    return { error: "Tool input must be valid JSON." };
+  }
+}
+
+export function parseDenyCheckArgs(args) {
+  const options = {
+    json: false,
+    tool: undefined,
+    input: undefined,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--tool" || token === "--name") {
+      const tool = args[++index];
+      if (!tool) return { error: "Missing value for --tool." };
+      options.tool = tool;
+      continue;
+    }
+    if (token === "--input") {
+      const parsed = parseToolInput(args[++index]);
+      if ("error" in parsed) return { error: parsed.error };
+      options.input = parsed.value;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      return { error: `Unknown option: ${token}` };
+    }
+    return { error: DENY_CHECK_USAGE };
+  }
+
+  if (!options.tool || !options.input) {
+    return { error: DENY_CHECK_USAGE };
+  }
+
+  return options;
+}
+
+export function runDenyCheck(args) {
+  const parsed = parseDenyCheckArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  const verdict = evaluateDenyHooks({ name: parsed.tool, input: parsed.input });
+  if (parsed.json) {
+    console.log(JSON.stringify(verdict));
+  } else if (!verdict.allowed) {
+    console.error(verdict.blockedBy?.reason ?? "Blocked by deny hook.");
+  } else {
+    console.log("allowed");
+  }
+
+  return verdict.allowed ? 0 : 1;
+}

package/lib/deny-hook-synthesis.d.ts

@@ -0,0 +1,93 @@
+import type { DenyRule } from "./deny-hooks.js";
+
+export type BlockerHistoryRecord = {
+  repoFullName?: string | null;
+  blockerCodes: string[];
+  changedPaths?: string[];
+  guardrailMatches?: string[];
+  pullNumber?: number | null;
+  recordedAt?: string | null;
+};
+
+export type DenyRuleProposalStatus = "proposed" | "approved" | "rejected";
+
+export type DenyRuleProposalAudit = {
+  kind: string;
+  path?: string;
+  pathPattern?: string;
+  occurrenceCount?: number;
+  blockerCodes?: string[];
+  synthesizedAt: string;
+};
+
+export type DenyRuleProposal = {
+  id: string;
+  status: DenyRuleProposalStatus;
+  rule: DenyRule;
+  audit: DenyRuleProposalAudit;
+};
+
+export type SynthesisConfig = {
+  minPathOccurrences?: number;
+  maxProposals?: number;
+};
+
+export const DEFAULT_SYNTHESIS_CONFIG: Readonly<Required<SynthesisConfig>>;
+
+export function normalizeBlockerHistoryRecord(record: unknown): BlockerHistoryRecord | null;
+
+export function normalizeBlockerHistory(records: unknown): BlockerHistoryRecord[];
+
+export function canonicalizeChangedPath(path: unknown): string | null;
+
+export function changedPathToDenyGlob(path: string): string | null;
+
+export function isCoveredByDefaultDenyRules(pathPattern: string): boolean;
+
+export function aggregateBlockerHistory(records: unknown): {
+  pathCounts: Map<string, number>;
+  pathBlockers: Map<string, Set<string>>;
+  blockerCounts: Map<string, number>;
+  recordCount: number;
+};
+
+export function synthesizeDenyRuleProposals(
+  records: unknown,
+  config?: SynthesisConfig,
+): DenyRuleProposal[];
+
+export function resolveEffectiveDenyRules(options?: {
+  includeDefaults?: boolean;
+  approvedProposals?: DenyRuleProposal[];
+}): DenyRule[];
+
+export function setProposalStatuses(
+  proposals: DenyRuleProposal[],
+  updates: Record<string, DenyRuleProposalStatus> | Map<string, DenyRuleProposalStatus>,
+): DenyRuleProposal[];
+
+export function resolveDenyHookSynthesisDbPath(env?: Record<string, string | undefined>): string;
+
+export type DenyHookSynthesisStore = {
+  dbPath: string;
+  refreshProposals(
+    repoFullName: string,
+    history: unknown,
+    config?: SynthesisConfig,
+    apiBaseUrl?: string,
+  ): DenyRuleProposal[];
+  listProposals(repoFullName: string, apiBaseUrl?: string): DenyRuleProposal[];
+  setProposalStatus(
+    repoFullName: string,
+    proposalId: string,
+    status: DenyRuleProposalStatus,
+    apiBaseUrl?: string,
+  ): void;
+  resolveEffectiveRules(
+    repoFullName: string,
+    options?: { includeDefaults?: boolean; apiBaseUrl?: string },
+  ): DenyRule[];
+  close(): void;
+};
+
+export function initDenyHookSynthesisStore(dbPath?: string): DenyHookSynthesisStore;