tenbo-dashboard 0.6.0 → 0.7.0

package/bin/tenbo-dashboard.mjs

@@ -40,6 +40,7 @@ const commands = {
   'init-check': 'scripts/init-check.ts',
   sync: 'scripts/sync.ts',
   archive: 'scripts/archive.ts',
+  hook: 'scripts/hook.ts',
 };
 
 // Documented aliases for the bare-launch behavior. Users (and agents) reading
@@ -82,6 +83,9 @@ Usage:
   tenbo-dashboard metrics --all    Compute scope metrics
   tenbo-dashboard archive          Move old done/dropped items to roadmap-archive.yaml
                                    [--scope <id>] [--days 30] [--max 20]
+  tenbo-dashboard hook install     Install opt-in pre-commit validation hook
+                                   [--dry-run] [--force]
+  tenbo-dashboard hook uninstall   Remove the tenbo pre-commit hook (idempotent)
   tenbo-dashboard --version        Print package version
   tenbo-dashboard help             Show this help
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",

package/scripts/hook.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  planInstall,
+  applyInstall,
+  planUninstall,
+  applyUninstall,
+  formatInstallPlan,
+  stripHuskyBlock,
+  TENBO_HEADER_MARKER,
+  TENBO_HUSKY_BEGIN,
+  TENBO_HUSKY_END,
+  HOOK_BODY,
+} from './hook';
+
+let tmp: string;
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'tenbo-hook-'));
+  fs.mkdirSync(path.join(tmp, '.git', 'hooks'), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe('planInstall', () => {
+  it('plans a standalone install when no pre-commit hook exists', () => {
+    const plan = planInstall({ repoRoot: tmp });
+    expect(plan.mode).toBe('standalone');
+    expect(plan.writes).toHaveLength(1);
+    expect(plan.moves).toHaveLength(0);
+  });
+
+  it('detects an already-installed tenbo hook (header present)', () => {
+    const hookPath = path.join(tmp, '.git', 'hooks', 'pre-commit');
+    fs.writeFileSync(hookPath, `#!/usr/bin/env sh\n${TENBO_HEADER_MARKER}\necho hi\n`);
+    const plan = planInstall({ repoRoot: tmp });
+    expect(plan.mode).toBe('already-installed');
+    expect(plan.writes).toHaveLength(0);
+  });
+
+  it('chains a foreign hook by moving it aside to .local', () => {
+    const hookPath = path.join(tmp, '.git', 'hooks', 'pre-commit');
+    fs.writeFileSync(hookPath, '#!/bin/sh\necho foreign\n');
+    const plan = planInstall({ repoRoot: tmp });
+    expect(plan.mode).toBe('chained');
+    expect(plan.moves[0].to.endsWith('.local')).toBe(true);
+  });
+
+  it('--force overwrites a foreign hook in place', () => {
+    const hookPath = path.join(tmp, '.git', 'hooks', 'pre-commit');
+    fs.writeFileSync(hookPath, '#!/bin/sh\necho foreign\n');
+    const plan = planInstall({ repoRoot: tmp, force: true });
+    expect(plan.mode).toBe('standalone');
+    expect(plan.moves).toHaveLength(0);
+  });
+
+  it('prefers husky integration when .husky/pre-commit exists', () => {
+    const huskyPath = path.join(tmp, '.husky', 'pre-commit');
+    fs.mkdirSync(path.dirname(huskyPath), { recursive: true });
+    fs.writeFileSync(huskyPath, '#!/bin/sh\nnpx lint-staged\n');
+    const plan = planInstall({ repoRoot: tmp });
+    expect(plan.mode).toBe('husky');
+    expect(plan.writes[0].path).toBe(huskyPath);
+  });
+});
+
+describe('applyInstall + applyUninstall round-trip', () => {
+  it('standalone install creates an executable hook with the tenbo header', () => {
+    const plan = planInstall({ repoRoot: tmp });
+    applyInstall(plan);
+    const hookPath = path.join(tmp, '.git', 'hooks', 'pre-commit');
+    const body = fs.readFileSync(hookPath, 'utf8');
+    expect(body).toBe(HOOK_BODY);
+    expect(body).toContain(TENBO_HEADER_MARKER);
+    expect((fs.statSync(hookPath).mode & 0o111) !== 0).toBe(true);
+  });
+
+  it('chained install preserves the foreign hook at .local and restores on uninstall', () => {
+    const hookPath = path.join(tmp, '.git', 'hooks', 'pre-commit');
+    const original = '#!/bin/sh\necho foreign-hook\n';
+    fs.writeFileSync(hookPath, original);
+    fs.chmodSync(hookPath, 0o755);
+
+    applyInstall(planInstall({ repoRoot: tmp }));
+    expect(fs.readFileSync(hookPath + '.local', 'utf8')).toBe(original);
+    expect(fs.readFileSync(hookPath, 'utf8')).toContain(TENBO_HEADER_MARKER);
+
+    applyUninstall(planUninstall(tmp));
+    expect(fs.existsSync(hookPath + '.local')).toBe(false);
+    expect(fs.readFileSync(hookPath, 'utf8')).toBe(original);
+  });
+
+  it('husky install appends a delimited block; uninstall removes only that block', () => {
+    const huskyPath = path.join(tmp, '.husky', 'pre-commit');
+    fs.mkdirSync(path.dirname(huskyPath), { recursive: true });
+    const original = '#!/bin/sh\nnpx lint-staged\n';
+    fs.writeFileSync(huskyPath, original);
+
+    applyInstall(planInstall({ repoRoot: tmp }));
+    const after = fs.readFileSync(huskyPath, 'utf8');
+    expect(after).toContain(TENBO_HUSKY_BEGIN);
+    expect(after).toContain(TENBO_HUSKY_END);
+    expect(after).toContain('npx lint-staged');
+
+    applyUninstall(planUninstall(tmp));
+    const restored = fs.readFileSync(huskyPath, 'utf8');
+    expect(restored).not.toContain(TENBO_HUSKY_BEGIN);
+    expect(restored).toContain('npx lint-staged');
+  });
+});
+
+describe('planUninstall', () => {
+  it('reports not-installed when no hook exists', () => {
+    expect(planUninstall(tmp).mode).toBe('not-installed');
+  });
+
+  it('leaves foreign hooks alone (not-installed)', () => {
+    fs.writeFileSync(path.join(tmp, '.git', 'hooks', 'pre-commit'), '#!/bin/sh\necho foreign\n');
+    expect(planUninstall(tmp).mode).toBe('not-installed');
+  });
+});
+
+describe('stripHuskyBlock', () => {
+  it('removes only the tenbo block, preserving surrounding lines', () => {
+    const input = `line one\n\n${TENBO_HUSKY_BEGIN}\necho tenbo\n${TENBO_HUSKY_END}\nline two\n`;
+    const out = stripHuskyBlock(input);
+    expect(out).toContain('line one');
+    expect(out).toContain('line two');
+    expect(out).not.toContain('echo tenbo');
+    expect(out).not.toContain(TENBO_HUSKY_BEGIN);
+  });
+});
+
+describe('formatInstallPlan', () => {
+  it('renders a standalone plan with mode + writes', () => {
+    const out = formatInstallPlan(planInstall({ repoRoot: tmp }));
+    expect(out).toContain('Install mode: standalone');
+    expect(out).toContain('write:');
+  });
+});

package/scripts/hook.ts

@@ -0,0 +1,402 @@
+/**
+ * hook.ts — install / uninstall the opt-in tenbo pre-commit hook.
+ *
+ * Runs the deterministic validator (`tenbo-dashboard validate --strict`) at
+ * commit time so duplicate-IDs, broken refs, and schema violations surface
+ * BEFORE bad shapes enter history. Tier 1 only — no LLM, sub-500ms.
+ *
+ * Subcommands (from `tenbo-dashboard hook ...`):
+ *   install [--dry-run] [--force]
+ *   uninstall
+ *   status   (introspect — useful for tests + users)
+ *
+ * Install strategy (in order of preference):
+ *   1. If `.husky/pre-commit` exists → append a clearly-delimited tenbo block
+ *      to the husky file. Less surprising for husky users than touching
+ *      `.git/hooks/`.
+ *   2. Else if `.git/hooks/pre-commit` is absent → create it standalone with
+ *      the tenbo header.
+ *   3. Else if existing `.git/hooks/pre-commit` already carries the tenbo
+ *      header → no-op (already installed).
+ *   4. Else (foreign hook present) → chained-hook pattern: move existing to
+ *      `pre-commit.local`, write a new `pre-commit` that runs the local one
+ *      first (preserving exit code) then the tenbo check.
+ *
+ * Uninstall is surgical and idempotent — only undoes what install added.
+ *
+ * Written in vanilla TS (no external deps) and exported as pure functions
+ * for unit testing. The `if (isMain())` block runs the CLI side-effects.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+
+export const TENBO_HEADER_MARKER = '# tenbo-managed pre-commit hook (sk-032)';
+export const TENBO_HUSKY_BEGIN = '### tenbo-managed (sk-032) BEGIN ###';
+export const TENBO_HUSKY_END = '### tenbo-managed (sk-032) END ###';
+
+/** The body of the pre-commit script the hook runs (POSIX sh, no bash-isms). */
+export const HOOK_BODY = `#!/usr/bin/env sh
+${TENBO_HEADER_MARKER}
+# Runs the deterministic validator on .tenbo/ before allowing commit.
+# Errors block commit; warnings print but don't block.
+# Bypass with \`git commit --no-verify\`.
+
+# Skip if no .tenbo/ in repo (graceful no-op for non-tenbo repos)
+if [ ! -d .tenbo ]; then exit 0; fi
+
+# Run validate with strict mode
+npx --no-install tenbo-dashboard validate --strict
+`;
+
+/** Husky-style block, appended to an existing .husky/pre-commit file. */
+export const HUSKY_BLOCK = `\n${TENBO_HUSKY_BEGIN}
+if [ -d .tenbo ]; then
+  npx --no-install tenbo-dashboard validate --strict || exit $?
+fi
+${TENBO_HUSKY_END}\n`;
+
+/** Chained-hook pre-commit body when a foreign hook was present. */
+export function chainedHookBody(localHookRelPath: string): string {
+  return `#!/usr/bin/env sh
+${TENBO_HEADER_MARKER}
+# Chained install — runs the previously-installed hook first, then tenbo's
+# validator. Uninstalling restores the local hook to its original location.
+
+LOCAL_HOOK="$(dirname "$0")/${path.basename(localHookRelPath)}"
+if [ -x "$LOCAL_HOOK" ]; then
+  "$LOCAL_HOOK" "$@" || exit $?
+fi
+
+if [ -d .tenbo ]; then
+  npx --no-install tenbo-dashboard validate --strict
+fi
+`;
+}
+
+export type InstallMode = 'standalone' | 'chained' | 'husky' | 'already-installed';
+
+export interface InstallPlan {
+  mode: InstallMode;
+  /** Absolute paths the install would write/move. */
+  writes: { path: string; reason: string; chmod?: boolean }[];
+  moves: { from: string; to: string }[];
+  notes: string[];
+}
+
+export interface InstallContext {
+  repoRoot: string;
+  /** Whether to overwrite a foreign hook in place (skips chaining). */
+  force?: boolean;
+}
+
+function isTenboManaged(content: string): boolean {
+  return content.includes(TENBO_HEADER_MARKER) || content.includes(TENBO_HUSKY_BEGIN);
+}
+
+/** Compute the install plan WITHOUT touching the filesystem. */
+export function planInstall(ctx: InstallContext): InstallPlan {
+  const huskyPath = path.join(ctx.repoRoot, '.husky', 'pre-commit');
+  const hookPath = path.join(ctx.repoRoot, '.git', 'hooks', 'pre-commit');
+
+  // Husky integration: prefer if .husky/pre-commit exists.
+  if (fs.existsSync(huskyPath)) {
+    const content = fs.readFileSync(huskyPath, 'utf8');
+    if (isTenboManaged(content)) {
+      return {
+        mode: 'already-installed',
+        writes: [],
+        moves: [],
+        notes: [`tenbo block already present in ${huskyPath}`],
+      };
+    }
+    return {
+      mode: 'husky',
+      writes: [{ path: huskyPath, reason: 'append tenbo block to existing husky pre-commit', chmod: true }],
+      moves: [],
+      notes: [
+        `Detected husky at ${huskyPath} — appending tenbo block (delimited by ${TENBO_HUSKY_BEGIN} / ${TENBO_HUSKY_END}).`,
+      ],
+    };
+  }
+
+  // No husky. Look at .git/hooks/pre-commit.
+  if (!fs.existsSync(hookPath)) {
+    return {
+      mode: 'standalone',
+      writes: [{ path: hookPath, reason: 'create new pre-commit hook (no existing hook found)', chmod: true }],
+      moves: [],
+      notes: ['No existing pre-commit hook found — installing standalone.'],
+    };
+  }
+
+  const existing = fs.readFileSync(hookPath, 'utf8');
+  if (isTenboManaged(existing)) {
+    return {
+      mode: 'already-installed',
+      writes: [],
+      moves: [],
+      notes: [`Tenbo header already present in ${hookPath}`],
+    };
+  }
+
+  if (ctx.force) {
+    return {
+      mode: 'standalone',
+      writes: [{ path: hookPath, reason: 'overwrite foreign hook (--force)', chmod: true }],
+      moves: [],
+      notes: [`--force: overwriting existing non-tenbo hook at ${hookPath}.`],
+    };
+  }
+
+  // Chained install — preserve existing hook by moving it aside.
+  const localPath = hookPath + '.local';
+  return {
+    mode: 'chained',
+    writes: [{ path: hookPath, reason: 'write chained hook that runs local then tenbo', chmod: true }],
+    moves: [{ from: hookPath, to: localPath }],
+    notes: [
+      `Existing non-tenbo hook detected at ${hookPath}.`,
+      `It will be preserved at ${localPath} and chained: local hook runs first, then tenbo validator.`,
+    ],
+  };
+}
+
+/** Apply an install plan. Returns the same plan for caller reporting. */
+export function applyInstall(plan: InstallPlan): InstallPlan {
+  // Moves first (so chained mode can free the original path before write).
+  for (const m of plan.moves) {
+    fs.renameSync(m.from, m.to);
+  }
+  for (const w of plan.writes) {
+    fs.mkdirSync(path.dirname(w.path), { recursive: true });
+    let body: string;
+    if (plan.mode === 'husky') {
+      const existing = fs.existsSync(w.path) ? fs.readFileSync(w.path, 'utf8') : '';
+      body = existing.endsWith('\n') ? existing + HUSKY_BLOCK : existing + '\n' + HUSKY_BLOCK;
+    } else if (plan.mode === 'chained') {
+      const moved = plan.moves.find((m) => m.to.endsWith('.local'));
+      body = chainedHookBody(moved ? moved.to : 'pre-commit.local');
+    } else {
+      body = HOOK_BODY;
+    }
+    fs.writeFileSync(w.path, body);
+    if (w.chmod) fs.chmodSync(w.path, 0o755);
+  }
+  return plan;
+}
+
+export type UninstallMode = 'standalone' | 'chained' | 'husky' | 'not-installed';
+
+export interface UninstallPlan {
+  mode: UninstallMode;
+  removes: string[];
+  /** Move (restore) operations: e.g. `pre-commit.local` → `pre-commit`. */
+  restores: { from: string; to: string }[];
+  /** In-place edits (husky block removal). */
+  edits: { path: string; before: string; after: string }[];
+  notes: string[];
+}
+
+export function planUninstall(repoRoot: string): UninstallPlan {
+  const huskyPath = path.join(repoRoot, '.husky', 'pre-commit');
+  const hookPath = path.join(repoRoot, '.git', 'hooks', 'pre-commit');
+  const localPath = hookPath + '.local';
+
+  // Husky path takes priority if the husky file carries the tenbo block.
+  if (fs.existsSync(huskyPath)) {
+    const content = fs.readFileSync(huskyPath, 'utf8');
+    if (content.includes(TENBO_HUSKY_BEGIN)) {
+      const after = stripHuskyBlock(content);
+      return {
+        mode: 'husky',
+        removes: [],
+        restores: [],
+        edits: [{ path: huskyPath, before: content, after }],
+        notes: [`Removing tenbo block from ${huskyPath}.`],
+      };
+    }
+  }
+
+  if (!fs.existsSync(hookPath)) {
+    return { mode: 'not-installed', removes: [], restores: [], edits: [], notes: ['No tenbo-managed hook found.'] };
+  }
+
+  const content = fs.readFileSync(hookPath, 'utf8');
+  if (!content.includes(TENBO_HEADER_MARKER)) {
+    return {
+      mode: 'not-installed',
+      removes: [],
+      restores: [],
+      edits: [],
+      notes: [`Hook at ${hookPath} is not tenbo-managed — leaving it alone.`],
+    };
+  }
+
+  // Tenbo-managed. Chained if a sibling .local exists.
+  if (fs.existsSync(localPath)) {
+    return {
+      mode: 'chained',
+      removes: [],
+      restores: [{ from: localPath, to: hookPath }],
+      edits: [],
+      notes: [`Restoring previous hook from ${localPath} → ${hookPath}.`],
+    };
+  }
+
+  return {
+    mode: 'standalone',
+    removes: [hookPath],
+    restores: [],
+    edits: [],
+    notes: [`Removing tenbo-managed standalone hook at ${hookPath}.`],
+  };
+}
+
+export function applyUninstall(plan: UninstallPlan): UninstallPlan {
+  for (const r of plan.removes) {
+    if (fs.existsSync(r)) fs.unlinkSync(r);
+  }
+  for (const r of plan.restores) {
+    if (fs.existsSync(r.to)) fs.unlinkSync(r.to);
+    fs.renameSync(r.from, r.to);
+    fs.chmodSync(r.to, 0o755);
+  }
+  for (const e of plan.edits) {
+    fs.writeFileSync(e.path, e.after);
+  }
+  return plan;
+}
+
+/** Strip the husky tenbo block (between BEGIN/END markers, inclusive). Pure. */
+export function stripHuskyBlock(content: string): string {
+  const lines = content.split('\n');
+  const out: string[] = [];
+  let inside = false;
+  for (const line of lines) {
+    if (line.includes(TENBO_HUSKY_BEGIN)) {
+      inside = true;
+      // Drop a single leading blank line we may have added for spacing.
+      if (out.length && out[out.length - 1] === '') out.pop();
+      continue;
+    }
+    if (line.includes(TENBO_HUSKY_END)) {
+      inside = false;
+      continue;
+    }
+    if (!inside) out.push(line);
+  }
+  return out.join('\n');
+}
+
+/** Pretty-print a plan for --dry-run. */
+export function formatInstallPlan(plan: InstallPlan): string {
+  const lines: string[] = [];
+  lines.push(`Install mode: ${plan.mode}`);
+  for (const n of plan.notes) lines.push(`  - ${n}`);
+  for (const m of plan.moves) lines.push(`  move: ${m.from} → ${m.to}`);
+  for (const w of plan.writes) lines.push(`  write: ${w.path} (${w.reason})`);
+  if (plan.mode === 'already-installed') lines.push('  (no changes — already installed)');
+  return lines.join('\n');
+}
+
+export function formatUninstallPlan(plan: UninstallPlan): string {
+  const lines: string[] = [];
+  lines.push(`Uninstall mode: ${plan.mode}`);
+  for (const n of plan.notes) lines.push(`  - ${n}`);
+  for (const r of plan.removes) lines.push(`  remove: ${r}`);
+  for (const r of plan.restores) lines.push(`  restore: ${r.from} → ${r.to}`);
+  for (const e of plan.edits) lines.push(`  edit: ${e.path}`);
+  return lines.join('\n');
+}
+
+function isMain(): boolean {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const here = path.resolve(new URL(import.meta.url).pathname);
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}
+
+function printHelp(): void {
+  process.stdout.write(`tenbo-dashboard hook — opt-in pre-commit hook (sk-032)
+
+Usage:
+  tenbo-dashboard hook install [--dry-run] [--force]
+  tenbo-dashboard hook uninstall
+  tenbo-dashboard hook status
+
+Install runs the deterministic validator on .tenbo/ at commit time.
+Errors block commit; warnings print but don't block.
+Bypass per-commit with \`git commit --no-verify\`.
+
+Flags:
+  --dry-run   Print exactly what would change without writing.
+  --force     Overwrite an existing non-tenbo hook (use with care).
+
+Notes:
+  - Existing .git/hooks/pre-commit (foreign) is preserved via chained-hook pattern.
+  - .husky/pre-commit users get a delimited block appended (no .git/hooks/ touch).
+  - Re-running install after install is a no-op.
+`);
+}
+
+if (isMain()) {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  const cwd = process.cwd();
+  const repoRoot = findRepoRoot(cwd);
+
+  if (!action || action === 'help' || action === '--help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (!repoRoot) {
+    process.stderr.write('hook: not inside a git repository (no .git/ found in any parent).\n');
+    process.exit(1);
+  }
+
+  if (action === 'install') {
+    const dryRun = args.includes('--dry-run');
+    const force = args.includes('--force');
+    const plan = planInstall({ repoRoot, force });
+    if (dryRun) {
+      process.stdout.write(formatInstallPlan(plan) + '\n');
+      process.stdout.write('(dry-run — no changes written)\n');
+      process.exit(0);
+    }
+    if (plan.mode === 'already-installed') {
+      process.stdout.write('tenbo pre-commit hook already installed. No changes.\n');
+      process.exit(0);
+    }
+    applyInstall(plan);
+    process.stdout.write(formatInstallPlan(plan) + '\n');
+    process.stdout.write('Installed. Bypass with `git commit --no-verify`. Uninstall with `npx tenbo-dashboard hook uninstall`.\n');
+    process.exit(0);
+  }
+
+  if (action === 'uninstall') {
+    const plan = planUninstall(repoRoot);
+    if (plan.mode === 'not-installed') {
+      process.stdout.write('No tenbo-managed pre-commit hook found. Nothing to do.\n');
+      process.exit(0);
+    }
+    applyUninstall(plan);
+    process.stdout.write(formatUninstallPlan(plan) + '\n');
+    process.stdout.write('Uninstalled.\n');
+    process.exit(0);
+  }
+
+  if (action === 'status') {
+    const plan = planInstall({ repoRoot });
+    process.stdout.write(`hook status: ${plan.mode === 'already-installed' ? 'installed' : 'not installed'}\n`);
+    for (const n of plan.notes) process.stdout.write(`  - ${n}\n`);
+    process.exit(0);
+  }
+
+  process.stderr.write(`hook: unknown action '${action}'. Run \`tenbo-dashboard hook help\`.\n`);
+  process.exit(2);
+}

package/scripts/validate-cli.ts

@@ -50,6 +50,13 @@ export function computeDiff(prev: Snapshot | null, current: Snapshot): DiffResul
 export interface RenderOptions {
   verbose?: boolean;
   json?: boolean;
+  /**
+   * Strict mode (sk-032): reserved for future stricter behavior. Today the
+   * default already exits non-zero on errors and 0 on warnings, so --strict
+   * is a no-op semantically but a stable contract for the pre-commit hook.
+   * If we ever introduce a warning-blocks-commit mode it lands here.
+   */
+  strict?: boolean;
 }
 
 export interface RenderResult {
@@ -152,6 +159,7 @@ if (isMain()) {
   const args = process.argv.slice(2);
   const verbose = args.includes('--verbose');
   const json = args.includes('--json');
+  const strict = args.includes('--strict');
 
   const cwd = process.cwd();
   const repoRoot = findRepoRoot(cwd) ?? path.resolve(cwd, '..', '..');
@@ -169,7 +177,7 @@ if (isMain()) {
   fs.writeFileSync(statusPath, JSON.stringify(snapshot, null, 2) + '\n');
 
   const diff = computeDiff(prev, snapshot);
-  const rendered = renderOutput(snapshot, diff, { verbose, json });
+  const rendered = renderOutput(snapshot, diff, { verbose, json, strict });
   if (rendered.stdout) process.stdout.write(rendered.stdout);
   if (rendered.stderr) process.stderr.write(rendered.stderr);
   if (!json && !verbose) {

package/src/api/lib/validator.duplicateIds.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { validate } from './validator';
+import type { TenboState, Item } from '../../types';
+
+const baseItem = (over: Partial<Item> = {}): Item => ({
+  id: 'ed-001',
+  title: 't',
+  layer: 'l',
+  status: 'later',
+  description: 'a roadmap item used for duplicate-id tests now',
+  ...over,
+});
+
+function stateWithScopeItems(items: Item[], archived: Item[] = []): TenboState {
+  return {
+    scopes: [{
+      id: 'e',
+      path: '.',
+      description: 'editor scope description here for tests',
+      layers: [{ id: 'l', name: 'L', description: 'a small layer for testing now', files: ['x'] } as any],
+      items,
+      archivedItems: archived,
+    }],
+    crossCutting: [],
+    narratives: { 'e/l': '# L' },
+  } as any;
+}
+
+const dupErrors = (state: TenboState) =>
+  validate(state).errors.filter((e) => /^duplicate item id/.test(e.message)).map((e) => e.message);
+
+describe('validator — duplicate item ids', () => {
+  it('emits no duplicate-id error when every id appears once', () => {
+    const state = stateWithScopeItems([
+      baseItem({ id: 'ed-001' }),
+      baseItem({ id: 'ed-002' }),
+      baseItem({ id: 'ed-003' }),
+    ]);
+    expect(dupErrors(state)).toEqual([]);
+  });
+
+  it('errors when two active items share an id', () => {
+    const state = stateWithScopeItems([
+      baseItem({ id: 'ed-001' }),
+      baseItem({ id: 'ed-001', title: 'dup' }),
+    ]);
+    const msgs = dupErrors(state);
+    expect(msgs.length).toBe(1);
+    expect(msgs[0]).toMatch(/duplicate item id "ed-001"/);
+    expect(msgs[0]).toMatch(/active/);
+  });
+
+  it('errors when an id appears once in active and once in archive', () => {
+    const state = stateWithScopeItems(
+      [baseItem({ id: 'ed-001' })],
+      [baseItem({ id: 'ed-001', status: 'done' })],
+    );
+    const msgs = dupErrors(state);
+    expect(msgs.length).toBe(1);
+    expect(msgs[0]).toMatch(/active/);
+    expect(msgs[0]).toMatch(/archive/);
+  });
+
+  it('errors when an id appears in cross-cutting and a scope', () => {
+    const state: TenboState = {
+      ...stateWithScopeItems([baseItem({ id: 'x-001' })]),
+      crossCuttingRoadmap: [
+        { id: 'x-001', title: 'cross', status: 'now', description: 'a cross-cutting item', layers: [] } as any,
+      ],
+    };
+    const msgs = dupErrors(state);
+    expect(msgs.length).toBe(1);
+    expect(msgs[0]).toMatch(/cross-cutting/);
+  });
+
+  it('emits one error per duplicated id, not one per duplicate occurrence', () => {
+    const state = stateWithScopeItems([
+      baseItem({ id: 'ed-001' }),
+      baseItem({ id: 'ed-001' }),
+      baseItem({ id: 'ed-002' }),
+      baseItem({ id: 'ed-002' }),
+      baseItem({ id: 'ed-003' }),
+    ]);
+    const msgs = dupErrors(state);
+    expect(msgs.length).toBe(2);
+    expect(msgs.some((m) => m.includes('ed-001'))).toBe(true);
+    expect(msgs.some((m) => m.includes('ed-002'))).toBe(true);
+  });
+});

package/src/api/lib/validator.preflightViolations.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { validate } from './validator';
+import type { TenboState, Item } from '../../types';
+
+function stateWithItems(items: Item[]): TenboState {
+  return {
+    scopes: [{
+      id: 'e',
+      path: '.',
+      description: 'editor scope description here for tests',
+      layers: [{ id: 'l', name: 'L', description: 'a small layer for testing now', files: ['x'] } as any],
+      items,
+    }],
+    crossCutting: [],
+    narratives: { 'e/l': '# L' },
+  } as any;
+}
+
+const baseItem = (over: Partial<Item> = {}): Item => ({
+  id: 'ed-001',
+  title: 't',
+  layer: 'l',
+  status: 'now',
+  description: 'a roadmap item used for preflight tests now',
+  done_when: ['it works'],
+  goal_ref: ['g1'],
+  ...over,
+});
+
+const warningsFor = (state: TenboState, id: string) =>
+  validate(state).warnings.filter((w) => w.itemId === id).map((w) => w.message);
+
+describe('validator — preflight_violations (sk-029)', () => {
+  it('does not warn when item has no preflight_violations', () => {
+    const state = stateWithItems([baseItem()]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('pre-flight violation'))).toBe(false);
+  });
+
+  it('warns when an active item has an accepted pre-flight violation', () => {
+    const state = stateWithItems([baseItem({
+      preflight_violations: [{
+        check: 'ui-components anti-responsibility: no direct fs writes',
+        outcome: 'violation',
+        decision: 'accept-with-violation',
+        rationale: 'one-off debug helper',
+      }],
+    })]);
+    const msgs = warningsFor(state, 'ed-001');
+    expect(msgs.some((m) => m.includes('accepted 1 pre-flight violation'))).toBe(true);
+  });
+
+  it('does not warn for done or dropped items even with accepted violations', () => {
+    for (const status of ['done', 'dropped'] as const) {
+      const state = stateWithItems([baseItem({
+        status,
+        preflight_violations: [{
+          check: 'ui-components anti-responsibility: no direct fs writes',
+          outcome: 'violation',
+          decision: 'accept-with-violation',
+        }],
+      })]);
+      const msgs = warningsFor(state, 'ed-001');
+      expect(msgs.some((m) => m.includes('pre-flight violation'))).toBe(false);
+    }
+  });
+});

package/src/api/lib/validator.ts

@@ -30,6 +30,39 @@ export function validate(state: TenboState): ValidateResult {
   }
   for (const item of state.crossCuttingRoadmap ?? []) allItemIds.add(item.id);
 
+  // Duplicate-ID detection (sk-031). Walks active + archived + cross-cutting
+  // items, recording every (id → location) occurrence. An ID appearing more
+  // than once anywhere in the workspace is a hard data-integrity error: it
+  // breaks relationship validation, history (active vs archive), and item
+  // identity. Emits one error per duplicated ID listing all locations.
+  const idOccurrences = new Map<string, string[]>();
+  const recordOccurrence = (id: string, where: string) => {
+    if (!id || typeof id !== 'string') return;
+    const arr = idOccurrences.get(id) ?? [];
+    arr.push(where);
+    idOccurrences.set(id, arr);
+  };
+  for (const scope of state.scopes) {
+    for (const item of scope.items) {
+      recordOccurrence(item.id, `scopes/${scope.id}/roadmap.yaml (active)`);
+    }
+    for (const item of scope.archivedItems ?? []) {
+      recordOccurrence(item.id, `scopes/${scope.id}/roadmap-archive.yaml`);
+    }
+  }
+  for (const item of state.crossCuttingRoadmap ?? []) {
+    recordOccurrence(item.id, `.tenbo/roadmap.yaml (cross-cutting)`);
+  }
+  for (const [id, locs] of idOccurrences) {
+    if (locs.length > 1) {
+      errors.push({
+        level: 'error',
+        message: `duplicate item id "${id}" — appears in ${locs.join(' and ')}`,
+        itemId: id,
+      });
+    }
+  }
+
   const validateSupersededBy = (item: Item, scopeId?: string) => {
     if (item.superseded_by === undefined) return;
     const sb = item.superseded_by;
@@ -191,16 +224,12 @@ export function validate(state: TenboState): ValidateResult {
       }
     }
 
-    // Item rules
-    const seenIds = new Set<string>();
+    // Item rules. Note: cross-scope/active+archive duplicate-id detection runs
+    // once at the top of validate() (sk-031) — no per-scope seenIds needed.
     for (const item of scope.items) {
       if (!/^[a-z]{1,5}-\d{3,}$/.test(item.id)) {
         errors.push({ level: 'error', message: `item "${item.id}" has invalid id format (expected <prefix>-NNN, e.g. ed-001 or x-001)`, scope: scope.id, itemId: item.id });
       }
-      if (seenIds.has(item.id)) {
-        errors.push({ level: 'error', message: `duplicate item id "${item.id}"`, scope: scope.id, itemId: item.id });
-      }
-      seenIds.add(item.id);
       // Status is optional when phases are present (it's derived via roll-up).
       // Only validate when explicitly set.
       const hasPhases = Array.isArray(item.phases) && item.phases.length > 0;
@@ -323,6 +352,45 @@ export function validate(state: TenboState): ValidateResult {
         });
       }
 
+      // Pre-flight violations (sk-029). Optional field; surface as a health
+      // observation (warning) when an item carries any accept-with-violation
+      // entry. Skip done/dropped items — no value nagging completed work.
+      // Shape-check only: validate array shape and enum values; don't
+      // cross-validate `check` strings against any taxonomy.
+      if (item.preflight_violations !== undefined) {
+        if (!Array.isArray(item.preflight_violations)) {
+          errors.push({ level: 'error', message: `item "${item.id}" preflight_violations must be a list`, scope: scope.id, itemId: item.id });
+        } else {
+          const VALID_OUTCOMES = new Set(['violation', 'threshold-cross', 'dependency-direction']);
+          const VALID_DECISIONS = new Set(['accept-with-violation', 'scope-adjusted', 'deferred']);
+          let acceptedCount = 0;
+          for (const entry of item.preflight_violations) {
+            if (!entry || typeof entry !== 'object') {
+              errors.push({ level: 'error', message: `item "${item.id}" preflight_violations entry is not an object`, scope: scope.id, itemId: item.id });
+              continue;
+            }
+            if (typeof (entry as any).check !== 'string' || (entry as any).check.trim() === '') {
+              errors.push({ level: 'error', message: `item "${item.id}" preflight_violations entry missing string "check"`, scope: scope.id, itemId: item.id });
+            }
+            if (!VALID_OUTCOMES.has((entry as any).outcome)) {
+              errors.push({ level: 'error', message: `item "${item.id}" preflight_violations entry has invalid outcome "${(entry as any).outcome}"`, scope: scope.id, itemId: item.id });
+            }
+            if (!VALID_DECISIONS.has((entry as any).decision)) {
+              errors.push({ level: 'error', message: `item "${item.id}" preflight_violations entry has invalid decision "${(entry as any).decision}"`, scope: scope.id, itemId: item.id });
+            }
+            if ((entry as any).decision === 'accept-with-violation') acceptedCount++;
+          }
+          if (acceptedCount > 0 && item.status !== 'done' && item.status !== 'dropped') {
+            warnings.push({
+              level: 'warning',
+              message: `item ${item.id} has accepted ${acceptedCount} pre-flight violation(s) — review at next audit`,
+              scope: scope.id,
+              itemId: item.id,
+            });
+          }
+        }
+      }
+
       // Phase schema validation (Phase 3 of x-001).
       if (item.phases !== undefined) {
         if (!Array.isArray(item.phases)) {

package/src/types.ts

@@ -93,6 +93,18 @@ export interface Item {
    * refactor, bug} lacks this field.
    */
   doc_update?: string;
+  /**
+   * Pre-flight violations recorded at capture time when the user accepted an
+   * item despite a flagged violation. Each entry: which check fired, what the
+   * outcome was, what the user decided, and their rationale. Empty / undefined
+   * when item passed pre-flight cleanly. See sk-029.
+   */
+  preflight_violations?: Array<{
+    check: string;            // e.g. "ui-components anti-responsibility: no direct fs writes"
+    outcome: 'violation' | 'threshold-cross' | 'dependency-direction';
+    decision: 'accept-with-violation' | 'scope-adjusted' | 'deferred';
+    rationale?: string;
+  }>;
 }
 
 export interface Layer {