@ngockhoale/ukit 1.6.7 → 2.0.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to UKit are documented here.
 
+## 2.0.0 - 2026-08-10
+
+### Added
+
+- **`skill-quality` skill** (maintainer-only) — adversarial pressure-testing process for template skills/agents before shipping changes, with `pressure-scenario-template.md`, `rationalization-table-template.md`, and `trigger-accuracy-template.md` companion files, plus `scripts/skill/audit-skill.mjs` (`yarn skill:audit`) for scaffolding scenario files and recording results. Not a `ukit` CLI command — a maintainer dev-tool, same tier as `yarn bug:triage`.
+- **`executing-plans` Preflight checklist + Blocker Classifier** — structured pre-execution checks and a formal blocker taxonomy, replacing an unstructured "When to Stop" bullet list.
+- **`handoff-planner` Scope Explosion Detector + Right-Sizing rule** — flags oversized multi-subsystem handoff requests and enforces task-granularity limits, on top of the existing wave-dependency logic.
+- **`RULES.md` / task template Interfaces block** — `Consumes`/`Produces` fields for explicit task-to-task data contracts in handoff cycles.
+- **`code-reviewer` agent generalized** with a `REVIEW_TARGET_TYPE` branch (`code` / `spec`), so it can review non-diff artifacts (e.g. specs) in addition to code diffs.
+- **`skillProfile.js` + `ukit doctor --skills`** — word-count budget report for every `templates/.claude/skills/*/SKILL.md`, flagging files over a 500-word default threshold.
+- **Project Pattern Learning** — schema + `ukit memory list --pending` / `approve` / `reject` CLI surface for proposing and confirming project-local conventions, gated on human approval (never auto-applied, project-local scope only).
+- **`project-learning` skill** — guides proposing/confirming project conventions through the new pattern-learning CLI.
+- Wired the previously dead `runHygiene()` (decision-superseding + session consolidation) into the live memory flow instead of leaving it uncalled.
+
+### Changed
+
+- Trimmed `templates/.claude/skills/**/SKILL.md` word count 31,227 → 25,900 words (17%) via companion-file extraction and in-place deduplication, with zero behavior loss (content relocated to companion `.md` files, never deleted, except one verbatim-duplicate line removed from `duraone`). See `docs/WORKLOG.md` Task 13 entry for the full per-skill breakdown.
+- Deleted 3 orphaned barrel `index.js` re-export files (`src/core/router/index.js`, `src/core/validation/index.js`, `src/core/memory/index.js`) with zero importers anywhere in the repo.
+- Raised the packed-artifact size budget in `tests/integration/packageArtifact.test.js` (`1,680,000` → `1,684,000` bytes packed, `5,283,000` → `5,291,000` bytes unpacked) — the artifact is dominated by binary assets (canvas fonts, OOXML XSD schemas) that skill-text trimming can't reduce.
+
+## 1.6.8 - 2026-08-09
+
+### Fixed
+
+- **`extract-image.mjs`** no longer re-arms `pending-<sha>.json` for an image that already has an `analyzed-<sha>.json` receipt. `selectImages()` always returns the most recent N images from the whole transcript, so a fully-analyzed image never fell out of that window on its own; since `vision-router.sh` calls `--mark-pending` on every prompt, this re-triggered the vision hint/gate on the same closed-out image forever, even on unrelated prompts. Both `--detect` and `--mark-pending` now skip any sha with an existing analyzed receipt.
+
 ## 1.6.7 - 2026-08-09
 
 ### Fixed

package/manifests/platform.full.yaml

@@ -686,6 +686,30 @@ items:
     packs:
       - core
 
+  - id: skill-quality-skill
+    type: skill
+    sourceTemplate: .claude/skills/skill-quality
+    targetPath: .claude/skills/skill-quality
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: project-learning-skill
+    type: skill
+    sourceTemplate: .claude/skills/project-learning/SKILL.md
+    targetPath: .claude/skills/project-learning/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: sql-optimization-patterns-skill
     type: skill
     sourceTemplate: .claude/skills/sql-optimization-patterns/SKILL.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.6.7",
+  "version": "2.0.1",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",
@@ -53,6 +53,7 @@
     "index:refresh": "node ./scripts/index/refresh-index.mjs",
     "index:query": "node ./scripts/index/query-index.mjs",
     "bug:triage": "node ./scripts/bug/triage.mjs",
+    "skill:audit": "node ./scripts/skill/audit-skill.mjs",
     "test:artifact": "vitest run tests/integration/packageArtifact.test.js",
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",

package/scripts/skill/audit-skill.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { initSkillAudit, recordAuditEntry, statusSkillAudit } from '../../src/skill/auditSkill.js';
+
+const [command, skillName] = process.argv.slice(2);
+const rootDir = process.cwd();
+
+if (!command || !skillName) {
+  console.error('Usage: yarn skill:audit <init|status|record> <skill-name>');
+  process.exitCode = 1;
+} else if (command === 'init') {
+  const result = await initSkillAudit({ rootDir, skillName });
+  console.log(`[skill:audit init] ${skillName}`);
+  console.log(`dir: ${result.auditDir}`);
+  console.log(`copied: ${result.copied.join(', ') || 'none'}`);
+  console.log(`skipped (already present): ${result.skipped.join(', ') || 'none'}`);
+} else if (command === 'status') {
+  const result = await statusSkillAudit({ rootDir, skillName });
+  console.log(`[skill:audit status] ${skillName}`);
+  console.log(`entries: ${result.entryCount}`);
+  console.log(`latest: ${result.latest ? JSON.stringify(result.latest) : 'none'}`);
+  console.log(`open rationalizations: ${result.openRationalizations.length}`);
+} else if (command === 'record') {
+  const stdinRaw = await readStdin();
+  const entry = JSON.parse(stdinRaw);
+  const record = await recordAuditEntry({ rootDir, skillName, entry });
+  console.log(`[skill:audit record] ${skillName}`);
+  console.log(JSON.stringify(record, null, 2));
+} else {
+  console.error(`Unknown command: ${command}. Usage: yarn skill:audit <init|status|record> <skill-name>`);
+  process.exitCode = 1;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}

package/src/cli/commands/doctor.js

@@ -7,9 +7,10 @@ import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
 import { loadManifest } from '../../manifest/loadManifest.js';
 import { detectStack } from '../../stack/detectStack.js';
 import { detectProviders } from '../../context/detectProviders.js';
+import { profileSkills } from '../../core/skillProfile.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
-const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS]);
+const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills']);
 
 export function printDoctorHelp() {
   console.log('Usage: ukit doctor [options]');
@@ -18,12 +19,13 @@ export function printDoctorHelp() {
   console.log('');
   console.log('Options:');
   console.log('  --help, -h      Show this help message');
+  console.log('  --skills        Also print a skill word-count/budget report');
 }
 
 export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
-    throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: --help, -h`);
+    throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: --help, -h, --skills`);
   }
 
   if (argv.some((flag) => DOCTOR_HELP_FLAGS.has(flag))) {
@@ -129,6 +131,24 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     console.log(`[UKit] Runtime config issues: ${runtimeConfigInspection.errors.join(' | ')}`);
   }
 
+  if (argv.includes('--skills')) {
+    const skillsDir = path.join(pathConfig.templatesRoot, '.claude', 'skills');
+    const skillReport = await profileSkills(skillsDir);
+    const overBudgetCount = skillReport.filter((s) => s.status === 'over-budget').length;
+
+    console.log('');
+    console.log('[UKit] Skill word-count report:');
+    console.log('[UKit]   Skill | Words | Status');
+    for (const skill of skillReport) {
+      console.log(`[UKit]   ${skill.name} | ${skill.wordCount} | ${skill.status}`);
+    }
+    console.log(
+      overBudgetCount > 0
+        ? `[UKit]   ${overBudgetCount} skill(s) over budget — consider moving detail to a companion reference file.`
+        : '[UKit]   All skills within budget.',
+    );
+  }
+
   const allPassed = Object.values(checks).every(Boolean);
   if (!allPassed) {
     console.log('[UKit] Some checks failed. Run `ukit install` to fix missing files.');

package/src/cli/commands/memory.js

@@ -2,15 +2,39 @@ import {
   exportMemory,
   forgetMemoryItem,
   listMemoryItems,
+  listPendingPatternCandidates,
+  resolvePatternCandidate,
+  runProjectHygiene,
 } from '../../core/memory/store.js';
 import { getContextInjection, search } from '../../core/memory/retrieval.js';
 import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
 import { pathExists } from '../../core/fileOps.js';
 import { detectProjectContext } from '../../context/detectProjectContext.js';
+import fs from 'node:fs/promises';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 
+async function listAllPendingPatternCandidates(projectRoot, runtimePaths) {
+  let entries = [];
+  try {
+    entries = await fs.readdir(runtimePaths.projectsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const projectId = entry.name.replace(/\.json$/, '');
+    const pending = await listPendingPatternCandidates(projectRoot, projectId);
+    for (const candidate of pending) {
+      results.push({ ...candidate, projectId });
+    }
+  }
+  return results;
+}
+
 export async function runMemory({ projectRoot, argv = [] }) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   if (!(await pathExists(runtimePaths.runtimeRoot))) {
@@ -26,6 +50,19 @@ export async function runMemory({ projectRoot, argv = [] }) {
   }
 
   if (subcommand === 'list') {
+    if (rest.includes('--pending')) {
+      const pending = await listAllPendingPatternCandidates(projectRoot, runtimePaths);
+      if (pending.length === 0) {
+        console.log('[UKit] No pending pattern candidates.');
+        return;
+      }
+
+      for (const candidate of pending) {
+        console.log(`${candidate.id} [${candidate.projectId}] — ${candidate.text}`);
+      }
+      return;
+    }
+
     const items = await listMemoryItems(projectRoot);
     if (items.length === 0) {
       console.log('[UKit] No memory items found.');
@@ -38,6 +75,40 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (subcommand === 'approve' || subcommand === 'reject') {
+    const projectFlagIndex = rest.indexOf('--project');
+    const explicitProjectId = projectFlagIndex >= 0 ? rest[projectFlagIndex + 1] : null;
+    const candidateArgs = projectFlagIndex >= 0
+      ? [...rest.slice(0, projectFlagIndex), ...rest.slice(projectFlagIndex + 2)]
+      : rest;
+    const candidateId = candidateArgs.join(' ').trim();
+    if (!candidateId) {
+      throw new Error(`Missing candidate id. Usage: ukit memory ${subcommand} <candidateId> [--project <id>]`);
+    }
+
+    const projectId = explicitProjectId ?? (await detectProjectContext(projectRoot)).project.name;
+    const resolved = await resolvePatternCandidate(
+      projectRoot,
+      projectId,
+      candidateId,
+      subcommand === 'approve' ? 'approve' : 'reject',
+    );
+
+    console.log(`[UKit] ${resolved.status === 'approved' ? 'Approved' : 'Rejected'} ${candidateId}.`);
+    return;
+  }
+
+  if (subcommand === 'hygiene') {
+    const projectFlagIndex = rest.indexOf('--project');
+    const explicitProjectId = projectFlagIndex >= 0 ? rest[projectFlagIndex + 1] : null;
+    const projectId = explicitProjectId ?? (await detectProjectContext(projectRoot)).project.name;
+
+    const result = await runProjectHygiene(projectRoot, projectId);
+    console.log(`[UKit] Ran hygiene for project ${projectId}.`);
+    console.log(`[UKit]   conventions=${result.conventions.length}, decisions=${result.decisions.length}, sessions=${result.sessions.length}`);
+    return;
+  }
+
   if (subcommand === 'search') {
     const query = rest.join(' ').trim();
     if (!query) {
@@ -115,12 +186,16 @@ export async function runMemory({ projectRoot, argv = [] }) {
 
 export function printMemoryHelp() {
   console.log('UKit Memory Commands');
-  console.log('Usage: ukit memory <list|search|recall|forget|export> [args]');
+  console.log('Usage: ukit memory <list|search|recall|forget|export|approve|reject|hygiene> [args]');
   console.log('');
   console.log('Subcommands:');
   console.log('  list               List memory items in shared .ukit/storage/memory');
+  console.log('  list --pending     List pending pattern candidates awaiting approval');
   console.log('  search <query>     Search memory summaries and content');
   console.log('  recall <task>      Print a compact previous-context block for the current task');
   console.log('  forget <id>        Remove one memory item by id');
   console.log('  export             Print all memory as JSON');
+  console.log('  approve <id> [--project <id>]  Approve a pending pattern candidate into project conventions');
+  console.log('  reject <id> [--project <id>]   Reject a pending pattern candidate');
+  console.log('  hygiene [--project <id>]  Run decision-conflict resolution + session archiving now');
 }

package/src/core/memory/store.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
 import path from 'node:path';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+import { runHygiene } from './hygiene.js';
 
 function defaultUserMemory() {
   return {
@@ -47,8 +50,9 @@ function summarizeUserMemory(userMemory) {
 
 function summarizeProjectMemory(projectMemory) {
   const decisionCount = Array.isArray(projectMemory.decisions) ? projectMemory.decisions.length : 0;
+  const conventionCount = Array.isArray(projectMemory.conventions) ? projectMemory.conventions.length : 0;
   const techStack = Array.isArray(projectMemory.techStack) ? projectMemory.techStack.join(', ') : '';
-  return `${projectMemory.name ?? projectMemory.id ?? 'project'} — ${decisionCount} decisions${techStack ? ` — ${techStack}` : ''}`;
+  return `${projectMemory.name ?? projectMemory.id ?? 'project'} — ${decisionCount} decisions, ${conventionCount} conventions${techStack ? ` — ${techStack}` : ''}`;
 }
 
 function summarizeSessionMemory(sessionMemory) {
@@ -170,6 +174,126 @@ export async function forgetMemoryItem(projectRoot, memoryId) {
   }
 }
 
+function normalizePatternText(text) {
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function sanitizeProjectId(projectId) {
+  return String(projectId).replace(/[\\/]/g, '-');
+}
+
+function projectMemoryPath(runtimePaths, projectId) {
+  return path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.json`);
+}
+
+async function readProjectMemoryForId(runtimePaths, projectId) {
+  const filePath = projectMemoryPath(runtimePaths, projectId);
+  const existing = await readJsonIfExists(filePath);
+  const memory = {
+    id: projectId,
+    conventions: [],
+    patternCandidates: [],
+    ...existing,
+  };
+  return { filePath, memory };
+}
+
+async function appendSessionArchive(runtimePaths, projectId, archivedSessions) {
+  if (!archivedSessions || archivedSessions.length === 0) {
+    return;
+  }
+
+  const archivePath = path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.archive.json`);
+  const existing = (await readJsonIfExists(archivePath)) ?? { sessions: [] };
+  const sessions = Array.isArray(existing.sessions) ? existing.sessions : [];
+  await writeJson(archivePath, { sessions: [...sessions, ...archivedSessions] });
+}
+
+async function persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory) {
+  const runtimeConfig = await loadRuntimeConfig(projectRoot);
+  const memoryConfig = runtimeConfig.memory ?? {};
+  const hygieneConfig = {
+    archiveAfterDays: memoryConfig.archiveAfterDays,
+    maxSessionsKept: memoryConfig.maxSessions,
+    ...(memoryConfig.redactSecrets === false ? { redactPatterns: [] } : {}),
+  };
+
+  const { projectMemory: hygienicMemory, archivedSessions } = runHygiene(memory, hygieneConfig);
+  await appendSessionArchive(runtimePaths, projectId, archivedSessions);
+  await writeJson(filePath, hygienicMemory);
+  return hygienicMemory;
+}
+
+export async function runProjectHygiene(projectRoot, projectId) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
+  return persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+}
+
+export async function proposePatternCandidate(projectRoot, projectId, candidate) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
+
+  const normalizedText = normalizePatternText(candidate?.text);
+  if (!normalizedText) {
+    throw new Error('proposePatternCandidate requires candidate.text');
+  }
+
+  const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+  const existingPending = patternCandidates.find(
+    (entry) => entry.status === 'pending' && normalizePatternText(entry.text) === normalizedText,
+  );
+  if (existingPending) {
+    return existingPending;
+  }
+
+  const entry = {
+    id: `pc_${crypto.randomBytes(6).toString('hex')}`,
+    text: candidate.text,
+    category: candidate?.category ?? null,
+    detectedFrom: candidate?.detectedFrom ?? null,
+    detectedAt: Date.now(),
+    status: 'pending',
+  };
+
+  memory.patternCandidates = [...patternCandidates, entry];
+  await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+  return entry;
+}
+
+export async function listPendingPatternCandidates(projectRoot, projectId) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const { memory } = await readProjectMemoryForId(runtimePaths, projectId);
+  const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+  return patternCandidates.filter((entry) => entry.status === 'pending');
+}
+
+export async function resolvePatternCandidate(projectRoot, projectId, candidateId, decision) {
+  if (decision !== 'approve' && decision !== 'reject') {
+    throw new Error(`Unknown decision: ${decision}`);
+  }
+
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
+
+  const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+  const target = patternCandidates.find((entry) => entry.id === candidateId);
+  if (!target) {
+    throw new Error(`Pattern candidate not found: ${candidateId}`);
+  }
+
+  target.status = decision === 'approve' ? 'approved' : 'rejected';
+  if (decision === 'approve') {
+    const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
+    if (!conventions.includes(target.text)) {
+      memory.conventions = [...conventions, target.text];
+    }
+  }
+
+  await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+  return target;
+}
+
 export async function countMemoryItems(projectRoot) {
   const exported = await exportMemory(projectRoot);
   return {

package/src/core/skillProfile.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_WORD_THRESHOLD = 500;
+
+function stripFrontmatter(content) {
+  if (!content.startsWith('---')) return content;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return content;
+  return content.slice(end + 4);
+}
+
+function countWords(text) {
+  const trimmed = text.trim();
+  return trimmed ? trimmed.split(/\s+/).length : 0;
+}
+
+export async function profileSkills(skillsDir, { threshold = DEFAULT_WORD_THRESHOLD } = {}) {
+  let entries;
+  try {
+    entries = await fs.readdir(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+    let content;
+    try {
+      content = await fs.readFile(skillFile, 'utf8');
+    } catch {
+      continue;
+    }
+    const wordCount = countWords(stripFrontmatter(content));
+    results.push({
+      name: entry.name,
+      wordCount,
+      status: wordCount > threshold ? 'over-budget' : 'ok',
+    });
+  }
+
+  return results.sort((a, b) => b.wordCount - a.wordCount);
+}

package/src/skill/auditSkill.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const TEMPLATE_FILES = [
+  'pressure-scenario-template.md',
+  'rationalization-table-template.md',
+  'trigger-accuracy-template.md',
+];
+
+export function getAuditDir(rootDir, skillName) {
+  return path.join(rootDir, 'docs', 'skill-audits', skillName);
+}
+
+function getHistoryPath(rootDir, skillName) {
+  return path.join(getAuditDir(rootDir, skillName), 'history.json');
+}
+
+export async function initSkillAudit({ rootDir = process.cwd(), skillName } = {}) {
+  if (!skillName) {
+    throw new Error('skillName is required. Usage: yarn skill:audit init <skill-name>');
+  }
+
+  const auditDir = getAuditDir(rootDir, skillName);
+  await fs.mkdir(auditDir, { recursive: true });
+
+  const templateSourceDir = path.join(rootDir, 'templates/.claude/skills/skill-quality');
+  const copied = [];
+  const skipped = [];
+
+  for (const fileName of TEMPLATE_FILES) {
+    const destPath = path.join(auditDir, fileName);
+    const alreadyExists = await fs.access(destPath).then(() => true).catch(() => false);
+    if (alreadyExists) {
+      skipped.push(fileName);
+      continue;
+    }
+    const sourcePath = path.join(templateSourceDir, fileName);
+    await fs.copyFile(sourcePath, destPath);
+    copied.push(fileName);
+  }
+
+  return { auditDir, copied, skipped };
+}
+
+export async function recordAuditEntry({ rootDir = process.cwd(), skillName, entry } = {}) {
+  if (!skillName) {
+    throw new Error('skillName is required. Usage: yarn skill:audit record <skill-name>');
+  }
+  if (!entry || !entry.phase) {
+    throw new Error('entry with a "phase" field (RED|GREEN|REFACTOR) is required');
+  }
+
+  const auditDir = getAuditDir(rootDir, skillName);
+  await fs.mkdir(auditDir, { recursive: true });
+
+  const historyPath = getHistoryPath(rootDir, skillName);
+  const history = await readHistory(historyPath);
+
+  const record = {
+    date: entry.date ?? new Date().toISOString().slice(0, 10),
+    phase: entry.phase,
+    complianceRate: entry.complianceRate ?? null,
+    rationalizationsFound: entry.rationalizationsFound ?? [],
+  };
+
+  history.push(record);
+  await fs.writeFile(historyPath, `${JSON.stringify(history, null, 2)}\n`, 'utf8');
+
+  return record;
+}
+
+export async function statusSkillAudit({ rootDir = process.cwd(), skillName } = {}) {
+  if (!skillName) {
+    throw new Error('skillName is required. Usage: yarn skill:audit status <skill-name>');
+  }
+
+  const historyPath = getHistoryPath(rootDir, skillName);
+  const history = await readHistory(historyPath);
+  const latest = history.length > 0 ? history[history.length - 1] : null;
+
+  const openRationalizations = history
+    .flatMap((record) => record.rationalizationsFound ?? [])
+    .filter((item) => !(typeof item === 'object' && item.closed === true));
+
+  return { latest, openRationalizations, entryCount: history.length };
+}
+
+async function readHistory(historyPath) {
+  const raw = await fs.readFile(historyPath, 'utf8').catch(() => null);
+  if (!raw) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}