@izkac/forgekit 0.1.0

package/src/review/schema-consistency.test.mjs

@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  LENSES,
+  SCOPE_TYPES,
+  SEVERITIES,
+  ALL_VERDICTS,
+  CONFIDENCES,
+  STATS_KEYS,
+} from './lib.mjs';
+
+/**
+ * The agent-facing JSON Schema and the runtime validator in lib.mjs describe the
+ * same contract. They live in different trees (the skill vs. scripts/), so this
+ * test fails loudly if their enums ever drift apart.
+ */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const schemaPath = path.join(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'skills',
+  'thorough-code-review',
+  'reference',
+  'report-schema.json',
+);
+const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+
+const runtimeSchemaPath = path.join(__dirname, 'schema.json');
+const runtimeSchema = JSON.parse(fs.readFileSync(runtimeSchemaPath, 'utf8'));
+
+const sorted = (arr) => [...arr].sort();
+
+test('schema file exists and parses', () => {
+  assert.ok(schema && typeof schema === 'object');
+});
+
+test('lens enum matches lib.LENSES', () => {
+  assert.deepEqual(sorted(schema.properties.lenses.items.enum), sorted(LENSES));
+});
+
+test('scope.type enum matches lib.SCOPE_TYPES', () => {
+  assert.deepEqual(sorted(schema.properties.scope.properties.type.enum), sorted(SCOPE_TYPES));
+});
+
+test('finding.severity enum matches lib.SEVERITIES', () => {
+  assert.deepEqual(sorted(schema.$defs.finding.properties.severity.enum), sorted(SEVERITIES));
+});
+
+test('finding.verdict enum matches lib.ALL_VERDICTS', () => {
+  assert.deepEqual(sorted(schema.$defs.finding.properties.verdict.enum), sorted(ALL_VERDICTS));
+});
+
+test('finding.phase1_confidence enum matches lib.CONFIDENCES', () => {
+  assert.deepEqual(
+    sorted(schema.$defs.finding.properties.phase1_confidence.enum),
+    sorted(CONFIDENCES),
+  );
+});
+
+test('second_opinion verdict enum matches lib.ALL_VERDICTS', () => {
+  assert.deepEqual(
+    sorted(schema.$defs.finding.properties.second_opinion.properties.verdict.enum),
+    sorted(ALL_VERDICTS),
+  );
+});
+
+test('stats keys match lib.STATS_KEYS', () => {
+  assert.deepEqual(sorted(Object.keys(schema.properties.stats.properties)), sorted(STATS_KEYS));
+});
+
+test('runtime schema.json shares top-level property names with the reference schema', () => {
+  assert.deepEqual(
+    sorted(Object.keys(runtimeSchema.properties)),
+    sorted(Object.keys(schema.properties)),
+  );
+});

package/src/review/schema.json

@@ -0,0 +1,196 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgekit.local/schemas/code-review-report.json",
+  "title": "ThoroughCodeReviewReport",
+  "type": "object",
+  "required": ["review_id", "kind", "created_at", "scope", "lenses", "summary", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "review_id": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "enum": ["review", "reverify"] },
+    "created_at": { "type": "string", "format": "date-time" },
+    "scope": {
+      "type": "object",
+      "required": ["type", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["uncommitted", "branch", "paths", "commit_range", "file"]
+        },
+        "description": { "type": "string", "minLength": 1 },
+        "base_sha": { "type": "string" },
+        "head_sha": { "type": "string" },
+        "paths": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "lenses": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "security",
+          "correctness",
+          "smells",
+          "architecture",
+          "performance",
+          "tests",
+          "contracts",
+          "errors",
+          "maintainability"
+        ]
+      }
+    },
+    "parent_report": { "type": "string" },
+    "summary": {
+      "type": "object",
+      "required": ["tentative_count"],
+      "additionalProperties": true,
+      "properties": {
+        "tentative_count": { "type": "integer", "minimum": 0 },
+        "confirmed": { "type": "integer", "minimum": 0 },
+        "downgraded": { "type": "integer", "minimum": 0 },
+        "false_positive": { "type": "integer", "minimum": 0 },
+        "needs_decision": { "type": "integer", "minimum": 0 },
+        "resolved": { "type": "integer", "minimum": 0 },
+        "still_open": { "type": "integer", "minimum": 0 },
+        "partially_fixed": { "type": "integer", "minimum": 0 },
+        "regressed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "dedupe_preflight": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "count": { "type": "integer", "minimum": 0 },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "location", "claim"],
+            "properties": {
+              "id": { "type": "string" },
+              "location": { "type": "string" },
+              "claim": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "description": "Recall / completeness pass ledger.",
+      "additionalProperties": true,
+      "properties": {
+        "files_reviewed": { "type": "array", "items": { "type": "string" } },
+        "files_skipped": { "type": "array", "items": { "type": "string" } },
+        "lenses_without_findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["lens", "reason"],
+            "properties": {
+              "lens": {
+                "type": "string",
+                "enum": [
+                  "security",
+                  "correctness",
+                  "smells",
+                  "architecture",
+                  "performance",
+                  "tests",
+                  "contracts",
+                  "errors",
+                  "maintainability"
+                ]
+              },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "signals": {
+      "type": "object",
+      "description": "Signals pre-flight: deterministic tools run before the scout.",
+      "additionalProperties": true,
+      "properties": {
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "status": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "stats": {
+      "type": "object",
+      "description": "Pipeline stats: subagent counts and shortcut tallies for the run.",
+      "additionalProperties": false,
+      "properties": {
+        "scouts": { "type": "integer", "minimum": 0 },
+        "skeptics_dedicated": { "type": "integer", "minimum": 0 },
+        "skeptics_batched": { "type": "integer", "minimum": 0 },
+        "inline_verdicts": { "type": "integer", "minimum": 0 },
+        "grounded_skips": { "type": "integer", "minimum": 0 },
+        "carried_forward": { "type": "integer", "minimum": 0 },
+        "second_opinions": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "required": ["id", "lens", "location", "claim", "severity", "verdict", "verdict_reason"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^(F|dup)-[0-9]{3}$" },
+        "lens": {
+          "type": "string",
+          "enum": [
+            "security",
+            "correctness",
+            "smells",
+            "architecture",
+            "performance",
+            "tests",
+            "contracts",
+            "errors",
+            "maintainability"
+          ]
+        },
+        "location": { "type": "string", "minLength": 1 },
+        "claim": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string" },
+        "severity": { "type": "string", "enum": ["critical", "important", "minor"] },
+        "phase1_confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+        "original_severity": { "type": "string", "enum": ["critical", "important", "minor"] },
+        "verdict": {
+          "type": "string",
+          "enum": [
+            "confirmed",
+            "false_positive",
+            "downgraded",
+            "needs_decision",
+            "resolved",
+            "still_open",
+            "partially_fixed",
+            "regressed"
+          ]
+        },
+        "verdict_reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/src/review/signals.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Signals pre-flight: map a review scope to the workspaces it touches and emit
+ * the deterministic grounding commands (typecheck / lint / test) to run before
+ * the scout. Grounding the scout in real tool output cuts hallucinated findings
+ * and raises recall on the smells / contracts / tests lenses.
+ *
+ * Read-only and fast: it PLANS the commands rather than running them, so the
+ * agent can run exactly the relevant ones and read full output. Use `--json`
+ * for machine-readable output.
+ *
+ * Usage:
+ *   review signals [--paths a,b] [--type <t>] [--base-branch main] [--json]
+ */
+
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { mapPathsToWorkspaces, suggestSignalCommands } from './lib.mjs';
+import { loadWorkspaces } from '../lib/workspaces.mjs';
+
+const CONTRACT_HINT = /(contract|openapi|routes?\/|\.openapi\.)/i;
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = { paths: null, type: 'uncommitted', baseBranch: 'main', json: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--paths') opts.paths = argv[++i].split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--type') opts.type = argv[++i];
+    else if (arg === '--base-branch') opts.baseBranch = argv[++i];
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return opts;
+}
+
+/**
+ * @param {ReturnType<typeof parseArgs>} opts
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function resolveScopePaths(opts, cwd) {
+  if (opts.paths) return opts.paths;
+  const run = (args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+  try {
+    if (opts.type === 'branch') {
+      return run(['diff', '--name-only', `${opts.baseBranch}...HEAD`]).split('\n').filter(Boolean);
+    }
+    const tracked = run(['diff', '--name-only', 'HEAD']).split('\n').filter(Boolean);
+    const untracked = run(['ls-files', '--others', '--exclude-standard']).split('\n').filter(Boolean);
+    return [...new Set([...tracked, ...untracked])];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {ReturnType<typeof parseArgs>} opts
+ * @param {string} [cwd]
+ * @param {Array<{ name: string, dir: string, scripts?: Record<string, string> }>} [packagesOverride]
+ * @returns {{ exitCode: number, plan: Record<string, unknown>, message: string }}
+ */
+export function runSignals(opts, cwd = process.cwd(), packagesOverride) {
+  const paths = resolveScopePaths(opts, cwd);
+  const packages = packagesOverride ?? loadWorkspaces(cwd);
+  const { workspaces, unmatched } = mapPathsToWorkspaces(paths, packages);
+  const commands = suggestSignalCommands(workspaces);
+  const contractTouch = paths.some((p) => CONTRACT_HINT.test(p));
+
+  const notes = [];
+  if (contractTouch) {
+    notes.push('Contract/route files touched — verify OpenAPI route-parity (contracts lens).');
+  }
+  if (unmatched.length > 0) {
+    notes.push(`${unmatched.length} path(s) outside any workspace — review with root tooling.`);
+  }
+
+  const plan = {
+    scope_paths: paths,
+    workspaces: workspaces.map((w) => w.name),
+    commands,
+    notes,
+  };
+
+  if (opts.json) {
+    return { exitCode: 0, plan, message: JSON.stringify(plan, null, 2) };
+  }
+
+  const lines = [];
+  lines.push(`Signals pre-flight — ${paths.length} path(s) in scope`);
+  lines.push(`Workspaces: ${workspaces.length ? workspaces.map((w) => w.name).join(', ') : '(none)'}`);
+  lines.push('');
+  lines.push('Run these grounding commands, then convert failures to tentative findings:');
+  if (commands.length === 0) lines.push('  (no workspace scripts detected for the scope)');
+  for (const c of commands) lines.push(`  ${c}`);
+  if (notes.length > 0) {
+    lines.push('');
+    lines.push('Notes:');
+    for (const n of notes) lines.push(`  - ${n}`);
+  }
+
+  return { exitCode: 0, plan, message: lines.join('\n') };
+}
+
+function printHelp() {
+  console.log(`Usage: review signals [options]
+
+Plan the deterministic grounding commands for a review scope.
+
+Options:
+  --paths a,b         Comma list of scoped paths (default: detect from git)
+  --type <t>          uncommitted | branch (git detection mode; default: uncommitted)
+  --base-branch <b>   Merge base for --type branch (default: main)
+  --json              Machine-readable output
+  -h, --help          Show this help
+`);
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      printHelp();
+      process.exit(0);
+    }
+    const result = runSignals(opts);
+    console.log(result.message);
+    process.exit(result.exitCode);
+  } catch (err) {
+    console.error(/** @type {Error} */ (err).message);
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  main();
+}

package/src/review/signals.test.mjs

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mapPathsToWorkspaces, suggestSignalCommands } from './lib.mjs';
+import { parseArgs, runSignals } from './signals.mjs';
+
+const PACKAGES = [
+  { name: '@janus/persona', dir: 'services/persona', scripts: { typecheck: 'tsc', test: 'vitest' } },
+  { name: '@janus/mercury', dir: 'services/mercury', scripts: { test: 'vitest' } },
+  { name: '@janus/persona-contract', dir: 'packages/persona-contract', scripts: { build: 'tsc' } },
+];
+
+test('mapPathsToWorkspaces matches the deepest owning workspace', () => {
+  const { workspaces, unmatched } = mapPathsToWorkspaces(
+    [
+      'services/persona/src/routes/profile.ts',
+      'services/mercury/src/index.ts',
+      'docs/thorough-code-review.md',
+    ],
+    PACKAGES,
+  );
+  assert.deepEqual(
+    workspaces.map((w) => w.name),
+    ['@janus/mercury', '@janus/persona'],
+  );
+  assert.deepEqual(unmatched, ['docs/thorough-code-review.md']);
+});
+
+test('mapPathsToWorkspaces normalizes backslashes and dedupes', () => {
+  const { workspaces } = mapPathsToWorkspaces(
+    ['services\\persona\\a.ts', 'services\\persona\\b.ts'],
+    PACKAGES,
+  );
+  assert.equal(workspaces.length, 1);
+  assert.equal(workspaces[0].name, '@janus/persona');
+});
+
+test('suggestSignalCommands emits only scripts that exist, in run order', () => {
+  const commands = suggestSignalCommands([
+    { name: '@janus/persona', scripts: { typecheck: 'tsc', test: 'vitest' } },
+    { name: '@janus/mercury', scripts: { test: 'vitest' } },
+  ]);
+  assert.deepEqual(commands, [
+    'npm run typecheck -w @janus/persona',
+    'npm run test -w @janus/persona',
+    'npm run test -w @janus/mercury',
+  ]);
+});
+
+test('runSignals plans commands and flags contract touches', () => {
+  const opts = parseArgs(['--paths', 'services/persona/src/routes/profile.ts', '--json']);
+  const result = runSignals(opts, process.cwd(), PACKAGES);
+  assert.equal(result.exitCode, 0);
+  assert.deepEqual(result.plan.workspaces, ['@janus/persona']);
+  assert.ok(result.plan.commands.includes('npm run typecheck -w @janus/persona'));
+  assert.ok(result.plan.notes.some((n) => n.includes('route-parity')));
+});
+
+test('runSignals reports paths outside any workspace', () => {
+  const opts = parseArgs(['--paths', 'scripts/review/lib.mjs']);
+  const result = runSignals(opts, process.cwd(), PACKAGES);
+  assert.ok(result.plan.notes.some((n) => n.includes('outside any workspace')));
+});

package/src/score-cli.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Score the active Forge session (L2 scorecard).
+ *
+ * Usage:
+ *   forge score [--session <id>] [--write] [--json]
+ *
+ * Without --write: print JSON to stdout.
+ * With --write: also write scorecard.json + scorecard.md into the session dir.
+ */
+
+import { loadSession, readActive } from './lib.mjs';
+import { formatScorecardMarkdown, scoreSession, writeSessionScorecard } from './score.mjs';
+
+const args = process.argv.slice(2);
+if (args[0] === '--help') {
+  process.stdout.write(
+    'Usage: forge score [--session <id>] [--write] [--json]\n' +
+      '  Scores session artifacts (spine, deferrals, product-loop, evidence, pace).\n' +
+      '  --write  save scorecard.json + scorecard.md into the session dir\n' +
+      '  --json   print JSON (default); omit for markdown summary on stdout\n',
+  );
+  process.exit(0);
+}
+
+let sessionId = null;
+let write = false;
+let asJson = true;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--write') {
+    write = true;
+  } else if (args[i] === '--markdown' || args[i] === '--md') {
+    asJson = false;
+  } else if (args[i] === '--json') {
+    asJson = true;
+  }
+}
+
+if (!sessionId) {
+  const active = readActive();
+  sessionId = active?.sessionId;
+}
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { dir, session } = loadSession(sessionId);
+const result = write
+  ? writeSessionScorecard({ sessionDir: dir, session })
+  : { card: scoreSession({ sessionDir: dir, session }), jsonPath: null, mdPath: null };
+
+const { card } = result;
+if (asJson) {
+  process.stdout.write(`${JSON.stringify(card, null, 2)}\n`);
+} else {
+  process.stdout.write(formatScorecardMarkdown(card));
+}
+
+if (write && result.mdPath) {
+  process.stderr.write(`Wrote ${result.mdPath}\n`);
+}
+
+// Non-zero if grade is D/F — useful in CI / finish hooks
+process.exit(card.grade === 'D' || card.grade === 'F' ? 1 : 0);