@sun-asterisk/sungen 3.2.1-beta.1 → 3.2.2-beta.10

package/src/cli/commands/depth-lint.ts

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runDepthLint, renderDepthLint } from '../../harness/depth-lint';
+import { reportSlug } from '../../harness/unit-paths';
+
+function findScreenDir(name: string): string | null {
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+export function registerDepthLintCommand(program: Command): void {
+  program
+    .command('depth-lint')
+    .description('Harness: classify shallow business-critical scenarios → deepen-in-place (with the data-assertion template) vs cross-screen (route to a flow). Generation-time depth self-check (#384).')
+    .option('-s, --screen <name>', 'Screen or flow name to lint')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const dir = findScreenDir(name);
+        if (!dir) throw new Error(`Not found: qa/screens/${name} or qa/flows/${name}`);
+
+        const report = runDepthLint(dir, name);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const outPath = path.join(outDir, `${reportSlug(name)}-depth-lint.json`);
+        fs.writeFileSync(outPath, JSON.stringify(report, null, 2), 'utf-8');
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          renderDepthLint(report);
+          console.log(`  Report: ${path.relative(process.cwd(), outPath)}`);
+          console.log('');
+        }
+        // Non-zero when there are deepen-in-place candidates the generator should fix before audit.
+        process.exit(report.deepen.length > 0 ? 2 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/gate.ts

@@ -0,0 +1,44 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runGate, renderGate, GatePhase } from '../../harness/journey';
+
+function findScreenDir(name: string): string | null {
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+const PHASES: GatePhase[] = ['create', 'run', 'deliver'];
+
+export function registerGateCommand(program: Command): void {
+  program
+    .command('gate')
+    .description('Inter-phase HALT gate (#381): a phase boundary passes only when its required obligations are satisfied or explicitly waived. Exit 2 = HALT (no silent bad output crosses the boundary).')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('-p, --phase <phase>', `Phase boundary: ${PHASES.join(' | ')}`)
+    .option('--json', 'Output the raw verdict')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const phase = options.phase as GatePhase;
+        if (!PHASES.includes(phase)) throw new Error(`Provide --phase <${PHASES.join('|')}>`);
+        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const verdict = runGate(process.cwd(), name, phase);
+        if (options.json) console.log(JSON.stringify(verdict, null, 2));
+        else console.log(renderGate(verdict));
+
+        // Exit 2 on HALT — usable in CI / the orchestration loop to block the next phase.
+        process.exit(verdict.status === 'halt' ? 2 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/journey.ts

@@ -0,0 +1,59 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runJourney, waive, signoff, renderJourneyBoard } from '../../harness/journey';
+import { reportSlug } from '../../harness/unit-paths';
+
+function findScreenDir(name: string): string | null {
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+export function registerJourneyCommand(program: Command): void {
+  program
+    .command('journey')
+    .description('Durable "you are here" board (#381): obligations + what-to-review + next, synthesised read-only from the audit report + ledger already on disk.')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason')
+    .option('--reason <text>', 'The reason a waived obligation is acceptable (mandatory with --waive)')
+    .option('--signoff', 'Sign off the review queue — the single human gate (allowed only when every other obligation is satisfied/waived)')
+    .option('--by <name>', 'Who is signing off (recorded with --signoff)')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const report = options.waive
+          ? waive(process.cwd(), name, options.waive, options.reason || '')
+          : options.signoff
+            ? signoff(process.cwd(), name, options.by)
+            : runJourney(process.cwd(), name);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'journey');
+        fs.mkdirSync(outDir, { recursive: true });
+        const slug = reportSlug(name);
+        fs.writeFileSync(path.join(outDir, `${slug}.json`), JSON.stringify(report, null, 2), 'utf-8');
+        const board = renderJourneyBoard(report);
+        fs.writeFileSync(path.join(outDir, `${slug}.board.md`), board, 'utf-8');
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          console.log('');
+          console.log(board);
+          console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, `${slug}.board.md`))}`);
+          console.log('');
+        }
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -15,6 +15,9 @@ import { registerFigmaCommand } from './commands/figma';
 import { registerAddFlowCommand } from './commands/add-flow';
 import { registerDashboardCommand } from './commands/dashboard';
 import { registerAuditCommand } from './commands/audit';
+import { registerDepthLintCommand } from './commands/depth-lint';
+import { registerJourneyCommand } from './commands/journey';
+import { registerGateCommand } from './commands/gate';
 import { registerIngestCommand } from './commands/ingest';
 import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
@@ -57,6 +60,9 @@ async function main() {
   registerAddFlowCommand(program);
   registerDashboardCommand(program);
   registerAuditCommand(program);
+  registerDepthLintCommand(program);
+  registerJourneyCommand(program);
+  registerGateCommand(program);
   registerManifestCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);

package/src/exporters/feature-parser.ts

@@ -164,6 +164,9 @@ export function splitVpAndName(scenarioName: string): { vpId?: string; category1
  * Map VP prefix to Category 2.
  * XSS/Injection security tests are input-validation tests → Function.
  * All other VP-SEC tests (auth, RBAC, access control) → Accessing.
+ * API auth viewpoints (missing/invalid/insufficient credentials) are access-control
+ * tests → Accessing; every other API viewpoint (contract, error, idempotency, flow,
+ * async, and the numbered baseline ids) is functional → Function.
  */
 export function mapVpToCategory2(vpId: string | undefined, scenarioName?: string): string {
   if (!vpId) return 'Function';
@@ -171,12 +174,66 @@ export function mapVpToCategory2(vpId: string | undefined, scenarioName?: string
     if (scenarioName && /xss|injection/i.test(scenarioName)) return 'Function';
     return 'Accessing';
   }
+  if (vpId.startsWith('VP-API-')) {
+    if (vpId.startsWith('VP-API-AUTH')) return 'Accessing';
+    return 'Function';
+  }
   if (vpId.startsWith('VP-UI-')) return 'GUI';
   if (vpId.startsWith('VP-VAL-')) return 'Function';
   if (vpId.startsWith('VP-LOGIC-')) return 'Function';
   return 'Function';
 }
 
+// ---------------------------------------------------------------------------
+// API annotation helpers
+// Used by the XLSX API-detail sheet only — no effect on CSV/BM-2-901-13 path.
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract ordered @api:<name> call sequence from feature-level or scenario tags.
+ * Tags may contain call arguments: @api:register(name={{x}},email={{y}}) — we strip
+ * the argument parens and keep only the endpoint name.
+ *
+ * Example: ["@api:register(name={{n}})", "@api:count_users(email={{e}})"]
+ *       → ["register", "count_users"]
+ */
+export function extractApiCallOrder(tags: string[]): string[] {
+  return tags
+    .filter((t) => t.startsWith('@api:'))
+    .map((t) => {
+      const body = t.slice('@api:'.length);
+      const parenIdx = body.indexOf('(');
+      return parenIdx >= 0 ? body.slice(0, parenIdx) : body;
+    });
+}
+
+/**
+ * Extract the @cases:<dataset> name from tags (returns the first one found, or null).
+ * Used to label the "cases" annotation so the detail sheet can note which scenarios
+ * exercise a given endpoint with a matrix of input/status pairs.
+ */
+export function extractCasesDataset(tags: string[]): string | null {
+  const tag = tags.find((t) => t.startsWith('@cases:'));
+  return tag ? tag.slice('@cases:'.length) : null;
+}
+
+/**
+ * Extract the concurrency invariant text from @concurrent:<N> and @query:<oracle> tags.
+ * N is the number of parallel fires; the invariant the band proves is exactly-one success
+ * (regardless of N), cross-checked by the @query DB oracle. Returns e.g.
+ * "2× parallel → exactly-one; @query user_count", or '' when absent.
+ */
+export function extractConcurrencyInvariant(tags: string[]): string {
+  const concurrentTag = tags.find((t) => t.startsWith('@concurrent:'));
+  if (!concurrentTag) return '';
+  const n = concurrentTag.slice('@concurrent:'.length);
+  const queryTag = tags.find((t) => t.startsWith('@query:'));
+  const oracle = queryTag ? queryTag.slice('@query:'.length).split('(')[0] : '';
+  const parts = [`${n}× parallel → exactly-one`];
+  if (oracle) parts.push(`@query ${oracle}`);
+  return parts.join('; ');
+}
+
 /**
  * Generate TC ID, namespaced by screen/flow so it is globally unique across the
  * whole project. This matters because the dashboard tracks each test case by its

package/src/exporters/types.ts

@@ -128,3 +128,41 @@ export interface EnvironmentInfo {
   projectName: string;
   executor: string;
 }
+
+/**
+ * One row in the "API detail" worksheet — one row per catalog endpoint.
+ * Populated from the apis.yaml catalog + scenario annotations (@cases, @api, @concurrent).
+ * Only emitted for api-kind units; never touches the BM-2-901-13 Testcases sheet.
+ */
+export interface ApiDetailRow {
+  /** Endpoint path from catalog (e.g. /register, /users/count?email=:email) */
+  endpoint: string;
+  /** HTTP method (GET, POST, …) */
+  method: string;
+  /** Auth / datasource string composed from catalog datasource + any @auth tag */
+  authDatasource: string;
+  /** Request shape: body fields / params / encoding from the catalog entry */
+  requestShape: string;
+  /** Expected-status matrix: the catalog expect.status plus a pointer to any @cases dataset
+   *  that drives this endpoint, e.g. "201; @cases:register_cases". */
+  expectedStatusMatrix: string;
+  /** Ordered @api:<name> call sequence for flow scenarios referencing this endpoint */
+  flowSteps: string;
+  /** Concurrency invariant for @concurrent scenarios, e.g. "2× parallel → exactly-one; @query <oracle>" */
+  concurrencyInvariant: string;
+}
+
+/**
+ * Catalog entry as parsed from apis.yaml.
+ * All fields are typed loosely (unknown) because the yaml structure may vary — callers
+ * must guard before use.
+ */
+export interface ApiCatalogEntry {
+  method?: string;
+  path?: string;
+  datasource?: string;
+  description?: string;
+  body?: unknown;
+  params?: unknown;
+  expect?: { status?: number | string };
+}

package/src/exporters/xlsx-exporter.ts

@@ -13,10 +13,15 @@ import * as fs from 'fs';
 import * as path from 'path';
 import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
-import { ScreenSummary, TestCaseRow } from './types';
+import { ApiCatalogEntry, ApiDetailRow, ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
 import { SUN_LOGO_PNG_BASE64 } from './sun-logo';
 import { deliverableBasename } from './csv-exporter';
+import {
+  extractApiCallOrder,
+  extractCasesDataset,
+  extractConcurrencyInvariant,
+} from './feature-parser';
 
 const COL_COUNT = 16;
 const HEADER_FILL = 'FFD9D2E9'; // lavender — matches the summary-header band on row 6
@@ -37,15 +42,31 @@ function applyBorder(cell: AnyCell): void {
   };
 }
 
+/**
+ * Optional context for the supplementary "API detail" worksheet.
+ * Passed only when the unit is kind:api. When omitted, only the standard
+ * Testcases sheet is emitted (non-api delivery stays byte-identical).
+ */
+export interface ApiDetailContext {
+  /** Parsed apis.yaml catalog keyed by endpoint name */
+  catalog: Record<string, ApiCatalogEntry>;
+  /** Pre-built detail rows (one per catalog endpoint) */
+  rows: ApiDetailRow[];
+}
+
 export function renderXlsx(
   summary: ScreenSummary,
   rows: TestCaseRow[],
-  specLink: string
+  specLink: string,
+  apiDetail?: ApiDetailContext,
 ): ExcelJS.Workbook {
   const wb = new ExcelJS.Workbook();
   wb.creator = 'sungen delivery';
   wb.created = new Date();
   addTestcaseSheet(wb, 'Testcases', summary, rows, specLink);
+  if (apiDetail) {
+    addApiDetailSheet(wb, apiDetail.rows);
+  }
   return wb;
 }
 
@@ -410,6 +431,159 @@ function addTestcaseSheet(
   };
 }
 
+// ---------------------------------------------------------------------------
+// API detail sheet (api-kind units only)
+// Second worksheet appended after Testcases — never alters the Testcases sheet.
+// ---------------------------------------------------------------------------
+
+const API_DETAIL_HEADER_FILL = 'FF2E5984'; // dark blue header for differentiation
+const API_DETAIL_HEADER_FONT = 'FFFFFFFF'; // white text on dark header
+
+/**
+ * Build ApiDetailRow[] from the apis.yaml catalog + feature-level annotations.
+ * Called once per feature file for api-kind units in the delivery pipeline.
+ *
+ * @param catalog   Parsed apis.yaml keyed by endpoint name
+ * @param scenarios Scenario-level tag arrays from parseFeatureMetadata().scenarios
+ */
+export function buildApiDetailRows(
+  catalog: Record<string, ApiCatalogEntry>,
+  scenarios: Array<{ tags: string[] }>,
+): ApiDetailRow[] {
+  const rows: ApiDetailRow[] = [];
+
+  for (const [endpointName, entry] of Object.entries(catalog)) {
+    const method = (entry.method ?? '').toUpperCase();
+    const endpoint = entry.path ?? endpointName;
+    const datasource = entry.datasource ?? '';
+
+    // Auth: look for @auth: tag in any scenario that calls this endpoint.
+    const authTags = scenarios.flatMap((s) => {
+      const calls = extractApiCallOrder(s.tags);
+      if (!calls.includes(endpointName)) return [];
+      return s.tags.filter((t) => t.startsWith('@auth:'));
+    });
+    const uniqueAuth = [...new Set(authTags.map((t) => t.slice('@auth:'.length)))];
+    const authDatasource = [datasource, ...uniqueAuth].filter(Boolean).join('; ');
+
+    // Request shape: compose from body + params + encoding.
+    const bodyStr = entry.body
+      ? `body: ${typeof entry.body === 'string' ? entry.body : JSON.stringify(entry.body)}`
+      : '';
+    const paramsArr = Array.isArray(entry.params) ? entry.params as string[] : [];
+    const paramsStr = paramsArr.length > 0 ? `params: [${paramsArr.join(', ')}]` : '';
+    const requestShape = [bodyStr, paramsStr].filter(Boolean).join('; ') || '—';
+
+    // Expected-status matrix: aggregate @cases dataset labels + expected status
+    // from scenarios that call this endpoint. Fall back to catalog expect.status.
+    const statusEntries: string[] = [];
+    for (const sc of scenarios) {
+      const calls = extractApiCallOrder(sc.tags);
+      if (!calls.includes(endpointName)) continue;
+      const dataset = extractCasesDataset(sc.tags);
+      if (dataset) {
+        // @cases dataset name as label — actual per-row statuses live in test-data.yaml
+        statusEntries.push(`@cases:${dataset}`);
+      }
+    }
+    // Show the catalog baseline status plus a pointer to any @cases matrix dataset (the per-row
+    // statuses live in test-data; resolving them into this cell is a later enrichment).
+    const catalogStatus = entry.expect?.status != null ? String(entry.expect.status) : '';
+    const expectedStatusMatrix =
+      [catalogStatus, ...new Set(statusEntries)].filter(Boolean).join('; ') || '—';
+
+    // Flow steps: ordered @api names from flow-tagged scenarios referencing this endpoint.
+    const flowStepsSet = new Set<string>();
+    for (const sc of scenarios) {
+      const calls = extractApiCallOrder(sc.tags);
+      if (!calls.includes(endpointName)) continue;
+      // All scenarios show their call order; flow scenarios show multi-step chains.
+      if (calls.length > 1) {
+        flowStepsSet.add(calls.join(' → '));
+      }
+    }
+    const flowSteps = [...flowStepsSet].join('; ') || '—';
+
+    // Concurrency invariant: from @concurrent scenarios calling this endpoint.
+    const concurrencyParts: string[] = [];
+    for (const sc of scenarios) {
+      const calls = extractApiCallOrder(sc.tags);
+      if (!calls.includes(endpointName)) continue;
+      const inv = extractConcurrencyInvariant(sc.tags);
+      if (inv) concurrencyParts.push(inv);
+    }
+    const concurrencyInvariant = concurrencyParts.join('; ') || '—';
+
+    rows.push({
+      endpoint,
+      method,
+      authDatasource,
+      requestShape,
+      expectedStatusMatrix,
+      flowSteps,
+      concurrencyInvariant,
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Append a second "API detail" worksheet to the workbook.
+ * Called only for api-kind units; no effect on the Testcases sheet or other sheets.
+ *
+ * Columns: Endpoint · Method · Auth/Datasource · Request shape ·
+ *          Expected-status matrix · Flow steps · Concurrency invariant
+ */
+export function addApiDetailSheet(wb: ExcelJS.Workbook, detailRows: ApiDetailRow[]): void {
+  const ws = wb.addWorksheet('API detail');
+  const ARIAL_FONT = 'Arial';
+
+  ws.columns = [
+    { header: 'Endpoint',                width: 35 },
+    { header: 'Method',                  width: 10 },
+    { header: 'Auth / Datasource',       width: 22 },
+    { header: 'Request shape',           width: 40 },
+    { header: 'Expected-status matrix',  width: 30 },
+    { header: 'Flow steps',              width: 40 },
+    { header: 'Concurrency invariant',   width: 35 },
+  ];
+
+  // Style the auto-generated header row (row 1).
+  const headerRow = ws.getRow(1);
+  headerRow.height = 30;
+  headerRow.eachCell((cell) => {
+    cell.font = { bold: true, color: { argb: API_DETAIL_HEADER_FONT }, name: ARIAL_FONT };
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: API_DETAIL_HEADER_FILL } };
+    cell.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+    applyBorder(cell);
+  });
+
+  ws.views = [{ state: 'frozen', ySplit: 1 }];
+
+  for (const r of detailRows) {
+    const row = ws.addRow([
+      r.endpoint,
+      r.method,
+      r.authDatasource,
+      r.requestShape,
+      r.expectedStatusMatrix,
+      r.flowSteps,
+      r.concurrencyInvariant,
+    ]);
+    row.alignment = { vertical: 'top', wrapText: true };
+    row.eachCell({ includeEmpty: true }, (cell) => {
+      applyBorder(cell);
+      cell.font = { name: ARIAL_FONT };
+    });
+  }
+
+  ws.autoFilter = {
+    from: { row: 1, column: 1 },
+    to: { row: ws.rowCount, column: 7 },
+  };
+}
+
 /**
  * Write the workbook to `qa/deliverables/<screen>-testcases[.env].xlsx`.
  * When `SUNGEN_ENV` is set, the env name is appended so locale exports don't

package/src/harness/depth-lint.ts

@@ -0,0 +1,122 @@
+/**
+ * Depth lint (issue #384) — a deterministic, generation-time depth self-check.
+ *
+ * The audit's `assertionDepth` sensor decides WHICH business-critical scenarios are shallow
+ * (the authoritative set). This lint adds the missing half: for each shallow business-critical
+ * scenario it classifies the *fix* using the catalog's per-theme `depth` metadata —
+ *   • cross_screen:false  → DEEPEN in place (emit the theme's `depth.template` value assertion)
+ *   • cross_screen:true   → DEFER (flow-own, or @manual:Mx with a reason) — leaves the depth denominator
+ * so a generator (or the create-test repair step) can act mechanically BEFORE the first audit,
+ * instead of churning the 3-round repair budget on scenarios that can't be deepened on-screen.
+ *
+ * Reuses the audit plumbing verbatim (parse + catalog + assertionDepth) → same verdict as `sungen audit`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import { loadCatalog, viewpointGate, assertionDepth, dataThemesFor, CatalogTheme } from './sensors';
+
+export type DepthAction = 'deepen' | 'defer';
+
+export interface DepthLintItem {
+  scenario: string;
+  theme: string | null;
+  action: DepthAction;
+  /** the exact deep step to emit (deepen) or the routing hint (defer) */
+  fix: string;
+}
+
+export interface DepthLintReport {
+  screen: string;
+  pageType: string | null;
+  focus: string;
+  threshold: number;
+  bcDepthRatio: number;
+  verdict: 'pass' | 'warn' | 'fail';
+  businessCriticalTotal: number;
+  shallowTotal: number;
+  /** shallow business-critical scenarios that CAN be deepened on-screen (actionable now) */
+  deepen: DepthLintItem[];
+  /** shallow business-critical scenarios that are cross-screen → route to a flow / @manual */
+  defer: DepthLintItem[];
+}
+
+/** Find the data-theme a scenario belongs to (precise depth.keywords, fallback theme.keywords). */
+function matchTheme(s: ScenarioInfo, dataThemes: CatalogTheme[]): CatalogTheme | undefined {
+  return dataThemes.find((t) => {
+    const kws = t.depth?.keywords?.length ? t.depth.keywords : t.keywords;
+    return kws.some((k) => s.haystack.includes(k.toLowerCase()));
+  });
+}
+
+export function runDepthLint(screenDir: string, screenName: string, focus = 'functional'): DepthLintReport {
+  const last = screenName.split('/').pop() || screenName;
+  const featurePath = path.join(screenDir, 'features', `${last}.feature`);
+  const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
+
+  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
+  const catalog = loadCatalog();
+  const gate = viewpointGate(scenarios, viewpoints, catalog);
+  const dataThemes = dataThemesFor(catalog, gate.pageType);
+  const depth = assertionDepth(scenarios, dataThemes, focus);
+
+  const byName = new Map(scenarios.map((s) => [s.name, s]));
+  const deepen: DepthLintItem[] = [];
+  const defer: DepthLintItem[] = [];
+
+  for (const sb of depth.shallowBusinessCritical) {
+    const s = byName.get(sb.name);
+    const theme = s ? matchTheme(s, dataThemes) : undefined;
+    const crossScreen = theme?.depth?.cross_screen ?? false;
+    if (crossScreen) {
+      defer.push({
+        scenario: sb.name,
+        theme: theme?.theme ?? null,
+        action: 'defer',
+        fix: `cross-screen — own it in a flow (sungen add-flow) or tag @manual:Mx with a reason; do not fake an on-screen data assertion`,
+      });
+    } else {
+      deepen.push({
+        scenario: sb.name,
+        theme: theme?.theme ?? null,
+        action: 'deepen',
+        fix: theme?.depth?.template ?? `add a data assertion (\`... with {{value}}\` or \`see all ... contain {{v}}\`)`,
+      });
+    }
+  }
+
+  return {
+    screen: screenName,
+    pageType: gate.pageType,
+    focus,
+    threshold: depth.threshold,
+    bcDepthRatio: depth.bcDepthRatio,
+    verdict: depth.verdict,
+    businessCriticalTotal: depth.businessCriticalTotal,
+    shallowTotal: depth.businessCriticalShallow,
+    deepen,
+    defer,
+  };
+}
+
+export function renderDepthLint(r: DepthLintReport): void {
+  const pct = (n: number) => `${Math.round(n * 100)}%`;
+  console.log('');
+  console.log(`━━━ Depth lint: ${r.screen} (page-type ${r.pageType ?? 'unknown'}) ━━━`);
+  console.log('');
+  console.log(`  businessDepth ${pct(r.bcDepthRatio)} (threshold ${pct(r.threshold)} · focus ${r.focus}) → ${r.verdict.toUpperCase()}`);
+  console.log(`  ${r.businessCriticalTotal} business-critical · ${r.shallowTotal} shallow → ${r.deepen.length} deepen-in-place · ${r.defer.length} cross-screen`);
+  if (r.deepen.length) {
+    console.log('');
+    console.log('  ── DEEPEN IN PLACE (fix before audit) ──');
+    for (const d of r.deepen) console.log(`   • ${d.scenario}\n       [${d.theme}] → ${d.fix}`);
+  }
+  if (r.defer.length) {
+    console.log('');
+    console.log('  ── CROSS-SCREEN (route to flow / @manual:Mx) ──');
+    for (const d of r.defer) console.log(`   • ${d.scenario}  [${d.theme}]`);
+  }
+  if (!r.deepen.length && !r.defer.length) console.log('  ✓ no shallow business-critical scenarios');
+  console.log('');
+}