@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/harness/defect-draft.ts

@@ -0,0 +1,115 @@
+/**
+ * `sungen defect draft` — turn each `product-candidate` row of a unit's last triage into a record
+ * `qa/defects/DEF-NNN-<slug>.md` (see defects.ts for the link checks). Deterministic: Steps come
+ * from the scenario's Gherkin with test-data resolved, Expected/Actual from the assertion, and the
+ * severity is PROPOSED by rule until QA confirms it. Never overwrites a file, and never drafts a
+ * scenario an existing record already names.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stringify as toYaml } from 'yaml';
+import type { ResolvedUnit } from '../cli/resolve-unit';
+import { redactSecrets } from '../exporters/api-testcase-formatter';
+import { getEnvironment } from '../exporters/run-environment';
+import { parseFeatureMetadata } from '../exporters/feature-parser';
+import { mergeFeatureAndSpec, MergedScenario } from '../exporters/scenario-merger';
+import { maskCredentialValue } from '../exporters/sensitive-key';
+import { parseSpecFile } from '../exporters/spec-parser';
+import { loadTestData, substituteTestDataVars } from '../exporters/test-data-resolver';
+import { readCapabilities } from './capability';
+import { defectsDir, nextDefectId, readDefects } from './defects';
+import type { TriageRow } from './triage';
+import { readTriageReport, unitSecrets } from './triage-unit';
+
+export interface DraftResult {
+  /** `sungen triage` has not run for this unit. */
+  missingTriage?: boolean;
+  written: string[];
+  skipped: Array<{ scenario: string; id: string }>;
+}
+
+/** Blocking actions: a @high scenario that fails on one of these is `major`, otherwise `minor`. */
+const BLOCKING = /\b(?:submit|save|apply|log ?in|sign ?in|sign ?up|register|checkout|pay|confirm|send|navigate|redirect)\b/i;
+
+const slug = (s: string): string =>
+  s.replace(/^\s*(?:VP|FL)-[A-Z0-9-]+\s+/i, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50).replace(/-$/, '');
+
+interface UnitScenario { merged: MergedScenario; testData: Record<string, string>; secrets: string[] }
+
+/** Scenario title → its merged Gherkin, test-data (credentials masked) and secret values. */
+function unitScenarios(cwd: string, unit: ResolvedUnit): Map<string, UnitScenario> {
+  const out = new Map<string, UnitScenario>();
+  const featuresDir = path.join(unit.dir, 'features');
+  if (!fs.existsSync(featuresDir)) return out;
+  for (const f of fs.readdirSync(featuresDir).filter((x) => x.endsWith('.feature'))) {
+    const base = f.replace(/\.feature$/, '');
+    const spec = parseSpecFile(path.join(cwd, 'specs', 'generated', unit.unitId, `${base}.spec.ts`));
+    const dataFile = path.join(unit.dir, 'test-data', `${base}.yaml`);
+    const raw = fs.existsSync(dataFile) ? loadTestData(dataFile) : {};
+    const testData = Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, maskCredentialValue(k, String(v))]));
+    const secrets = unitSecrets(raw, cwd);
+    for (const m of mergeFeatureAndSpec(parseFeatureMetadata(path.join(featuresDir, f)), spec)) {
+      out.set(m.feature.name, { merged: m, testData, secrets });
+    }
+  }
+  return out;
+}
+
+function render(cwd: string, unit: ResolvedUnit, id: string, row: TriageRow, sc: UnitScenario | undefined): string {
+  const tags = sc?.merged.feature.tags ?? [];
+  const resolve = (t: string): string => (sc ? substituteTestDataVars(t, sc.testData) : t);
+  const steps = (sc?.merged.resolvedSteps ?? []).map((s) => resolve(s.text));
+  const thens = (sc?.merged.resolvedExpected ?? []).map((s) => resolve(s.text));
+  const high = tags.some((t) => t === '@high' || t === '@critical');
+  const severity = high && BLOCKING.test([row.scenario, ...steps].join(' ')) ? 'major' : 'minor';
+  const specFile = path.join(unit.dir, 'requirements', 'spec.md');
+  const env = getEnvironment(cwd);
+  const front = {
+    id, title: row.scenario, severity, severity_source: 'proposed', status: 'open',
+    units: [unit.unitId], scenarios: [row.scenario], claims: row.ids, legacy: row.legacy,
+    spec: fs.existsSync(specFile) ? path.relative(cwd, specFile) : '',
+    found: {
+      date: new Date().toISOString().slice(0, 10),
+      env: process.env.SUNGEN_ENV || 'default',
+      base_url: env.baseURL,
+      platform: row.variant || readCapabilities(cwd).platform || 'web',
+    },
+    tracker: '',
+  };
+  const body = [
+    '---', toYaml(front).trimEnd(), '---', '',
+    `# ${id}: ${row.scenario}`, '',
+    '## Summary', '', '(to fill: what is wrong, where, and who it affects)', '',
+    '## Steps to reproduce', '', ...(steps.length ? steps.map((s, i) => `${i + 1}. ${s}`) : ['(scenario steps not found — see the feature)']), '',
+    '## Expected', '', ...thens.map((t) => `- ${t}`), ...(row.expected ? [`- Asserted value: ${row.expected}`] : []), '',
+    '## Actual', '', `- ${row.received ? `Received: ${row.received}` : row.evidence}`, '',
+    '## Evidence', '', `- Error: ${row.evidence}`, ...(row.tracePath ? [`- Trace: ${row.tracePath}`] : []), '',
+    '## Notes', '', `- Triage: ${row.class} (${row.ruleId})${row.variant ? ` on ${row.variant}` : ''}`, '',
+  ].join('\n');
+  return redactSecrets(body, sc?.secrets ?? []);
+}
+
+export function draftDefects(cwd: string, unit: ResolvedUnit, opts: { scenario?: string } = {}): DraftResult {
+  const triage = readTriageReport(cwd, unit.unitId);
+  if (!triage) return { missingTriage: true, written: [], skipped: [] };
+  const recorded = new Map<string, string>();
+  for (const r of readDefects(cwd)) if (r.units.includes(unit.unitId)) for (const s of r.scenarios) recorded.set(s, r.id);
+
+  const wanted = triage.rows.filter((r) => r.class === 'product-candidate'
+    && (!opts.scenario || r.scenario.includes(opts.scenario) || r.ids.includes(opts.scenario)));
+  const scenarios = unitScenarios(cwd, unit);
+  const result: DraftResult = { written: [], skipped: [] };
+  const seen = new Set<string>();
+  for (const row of wanted) {
+    if (seen.has(row.scenario)) continue;   // one record per scenario, even across OS variants
+    seen.add(row.scenario);
+    const existing = recorded.get(row.scenario);
+    if (existing) { result.skipped.push({ scenario: row.scenario, id: existing }); continue; }
+    const id = nextDefectId(cwd);
+    const file = path.join(defectsDir(cwd), `${id}-${slug(row.scenario) || 'defect'}.md`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, render(cwd, unit, id, row, scenarios.get(row.scenario)), { encoding: 'utf-8', flag: 'wx' });
+    result.written.push(path.relative(cwd, file));
+  }
+  return result;
+}

package/src/harness/defects.ts

@@ -0,0 +1,94 @@
+/**
+ * Defect records — `qa/defects/DEF-NNN-<slug>.md`, one project-wide folder. A scenario points at a
+ * record with `@known-defect:DEF-NNN`; the record points back at units, scenarios, claims and legacy
+ * TCs in its frontmatter. This module reads the records and checks both directions of that link.
+ * Drafting a record from a triage row lives in defect-draft.ts.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export const DEFECT_STATUSES = ['open', 'fixed', 'verified', 'closed', 'wont-fix'] as const;
+export type DefectStatus = typeof DEFECT_STATUSES[number];
+
+export interface DefectRecord {
+  id: string;
+  title: string;
+  severity: string;
+  status: string;
+  units: string[];
+  scenarios: string[];
+  /** Project-relative path of the record file. */
+  file: string;
+}
+
+const DEF_FILE = /^(DEF-(\d+))-.*\.md$/;
+const KNOWN_DEFECT_TAG = /@known-defect:(DEF-\d+)\b/g;
+
+export function defectsDir(cwd: string): string {
+  return path.join(cwd, 'qa', 'defects');
+}
+
+function defectFiles(cwd: string): string[] {
+  const dir = defectsDir(cwd);
+  return fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => DEF_FILE.test(f)).sort() : [];
+}
+
+/** The next free id: one above the highest number on disk, zero-padded to 3. */
+export function nextDefectId(cwd: string): string {
+  const max = defectFiles(cwd).reduce((m, f) => Math.max(m, Number(f.match(DEF_FILE)![2])), 0);
+  return `DEF-${String(max + 1).padStart(3, '0')}`;
+}
+
+const list = (v: unknown): string[] => (Array.isArray(v) ? v.map(String) : []);
+
+/** Every record whose frontmatter parses; a malformed file is skipped, never thrown on. */
+export function readDefects(cwd: string): DefectRecord[] {
+  const out: DefectRecord[] = [];
+  for (const f of defectFiles(cwd)) {
+    const file = path.join(defectsDir(cwd), f);
+    try {
+      const fm = parseYaml(fs.readFileSync(file, 'utf-8').split(/^---\s*$/m)[1] ?? '') as Record<string, unknown> | null;
+      if (!fm || typeof fm !== 'object') continue;
+      out.push({
+        id: String(fm.id ?? f.match(DEF_FILE)![1]),
+        title: String(fm.title ?? ''),
+        severity: String(fm.severity ?? ''),
+        status: String(fm.status ?? ''),
+        units: list(fm.units),
+        scenarios: list(fm.scenarios),
+        file: path.relative(cwd, file),
+      });
+    } catch {
+      // unreadable frontmatter: not a record we can reason about
+    }
+  }
+  return out;
+}
+
+/**
+ * Advisory audit findings for one unit (never scored):
+ *   DEFECT-REF-MISSING     a `@known-defect:DEF-NNN` tag with no record file.
+ *   DEFECT-ORPHAN (info)   an OPEN record of this unit names a scenario the unit no longer has.
+ */
+export function defectLinkFindings(cwd: string, unitId: string, featureText: string, scenarioNames: string[]): string[] {
+  const records = readDefects(cwd);
+  const findings: string[] = [];
+  const known = new Set(records.map((r) => r.id));
+  const tagged = new Set([...featureText.matchAll(KNOWN_DEFECT_TAG)].map((m) => m[1]));
+  for (const id of tagged) {
+    if (!known.has(id)) {
+      findings.push(`DEFECT-REF-MISSING: \`@known-defect:${id}\` has no record in qa/defects/ — draft it with \`sungen defect draft --screen ${unitId}\`, or correct the id.`);
+    }
+  }
+  const names = new Set(scenarioNames);
+  for (const r of records) {
+    if (r.status !== 'open' || !r.units.includes(unitId)) continue;
+    for (const s of r.scenarios) {
+      if (!names.has(s)) {
+        findings.push(`DEFECT-ORPHAN (info): ${r.id} is open and names scenario "${s}", which ${unitId} no longer has — update the record's scenarios, or close it.`);
+      }
+    }
+  }
+  return findings;
+}

package/src/harness/depth-lint.ts

@@ -15,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { loadUnitScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { loadCatalog, viewpointGate, assertionDepth, dataThemesFor, CatalogTheme } from './sensors';
+import { keywordHit } from './keyword-match';
 
 export type DepthAction = 'deepen' | 'defer';
 
@@ -45,7 +46,7 @@ export interface DepthLintReport {
 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()));
+    return kws.some((k) => keywordHit(s.haystack, k));
   });
 }
 

package/src/harness/flow-check.ts

@@ -12,6 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { featureFilesFor } from './unit-paths';
+import { keywordHit } from './keyword-match';
 import { loadScenarios } from './parse';
 import { parseScenarios } from './capability-plan';
 import { readTextFile } from './read-text';
@@ -45,7 +46,10 @@ function featureTags(fp: string): string[] {
 }
 function targetsFromHint(hint: string): string[] {
   const h = hint.toLowerCase();
-  const hits = KNOWN_TARGETS.filter((k) => h.includes(k));
+  // Word-aware (#779): every KNOWN_TARGET is an ordinary noun, so a substring test read
+  // `re·order` / `dis·order` as the target `order` and then matched the two to each other —
+  // a deferral about reorder history reported COVERED by a flow scenario about a disorder.
+  const hits = KNOWN_TARGETS.filter((k) => keywordHit(h, k));
   if (hits.length) return hits;
   // fallback: significant words after "->"
   const after = h.split('->').pop() || h;
@@ -87,7 +91,7 @@ export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport
       // `@owned-by:<flow>` names the owner explicitly → only that flow's scenarios can cover it
       // (a false @owned-by is then surfaced as missing). Else any flow may cover it (legacy).
       const pool = s.ownedBy ? flowScenarios.filter((fs2) => fs2.flow === s.ownedBy) : flowScenarios;
-      const matches = pool.filter((fs2) => targets.some((t) => fs2.haystack.includes(t)));
+      const matches = pool.filter((fs2) => targets.some((t) => keywordHit(fs2.haystack, t)));
       let verdict: Deferral['verdict'] = 'missing';
       let via: string | undefined;
       if (matches.some((m) => m.deep)) { verdict = 'covered'; via = matches.find((m) => m.deep)!.flow; }

package/src/harness/keyword-match.ts

@@ -0,0 +1,85 @@
+/**
+ * Keyword matching for the audit's coverage sensors — the single rule every "does a scenario
+ * mention this?" question goes through.
+ *
+ * WHY THIS EXISTS (#776). The sensors used to ask `haystack.includes(keyword)`. A substring match
+ * is satisfied by a keyword buried inside an unrelated word, and it fails in the direction that
+ * HIDES problems: a theme nobody tested reads as covered. Measured case — the scenario title
+ * "…five steps from email through to information entry" made `format-boundary` covered on a screen
+ * with no text input at all, because in·format·ion contains `format`. That one word moved the
+ * screen from 7.9 FAIL to 8.9 PASS.
+ *
+ * THE RULE: anchor a word boundary at the START of the keyword, leave the END free.
+ *
+ * Not `\b…\b` at both ends, which is the obvious fix and is wrong. Every collision this defect
+ * produces is a PREFIX collision — the innocent word carries extra letters BEFORE the keyword:
+ *
+ *     format  ← in·format·ion, ·format·ting        range   ← ar·range·ment, o·range
+ *     saved   ← un·saved                           created ← re·created
+ *     success ← un·success·ful                     length  ← wave·length
+ *
+ * The `unsaved` / `unsuccessful` pair is the sharp end: the prefix INVERTS the meaning, so a
+ * scenario asserting a submit FAILED is what marks the submit-SUCCESS theme covered.
+ *
+ * Meanwhile English inflection lives entirely in the SUFFIX, and a trailing `\b` destroys it:
+ * `submit` stops matching "submitted", `success` stops matching "successfully", `valid` stops
+ * matching "validation", `create` stops matching "created". Those are true positives, and a
+ * both-ends boundary turns 4 of 5 of them into false gaps — trading a silent failure for a noisy
+ * one. A leading boundary alone kills all six collisions above and keeps all of them.
+ *
+ * WHAT THIS RULE DOES NOT FIX, stated rather than implied. A free suffix still admits a collision
+ * when the keyword is a true PREFIX of a common unrelated word:
+ *
+ *     feed → "feedback"    list → "listener"    length → "lengthy"
+ *
+ * No boundary rule can separate `feed` from `feedback`, so the cure is a less ambiguous KEYWORD,
+ * which is a catalog decision rather than a matcher one. #778 took it: the shipped catalog no
+ * longer carries any of the three bare forms — `"product list"`, `"feed item"` and
+ * `"max length"` / `"min length"` replaced them, and `cart-correctness` lost bare `price` and
+ * `quantity` (ordinary listing vocabulary that credited a cart theme on a screen with no cart).
+ *
+ * That closes today's instances, not the class. `tests/harness/keyword-word-boundary.run.ts`
+ * section (e) sweeps every single-word ASCII keyword in the catalog — theme `keywords`,
+ * `detect_keywords` and `depth.keywords` alike — so a NEW loose keyword fails the suite instead of
+ * entering silently. Adding one is possible, but only as a conscious act via that file's
+ * `KNOWN_LOOSE` map, which #778 left empty.
+ *
+ * NON-ASCII KEYWORDS fall back to substring, on purpose. JavaScript's `\b` is defined against
+ * `[A-Za-z0-9_]`, so `\bログイン` and `\bđăng nhập` never match anything at all — the anchor would
+ * silently disable the keyword rather than tighten it. Japanese and Chinese have no word
+ * boundaries to anchor to, which is precisely where substring matching is the CORRECT behaviour
+ * and the false-positive risk is low. Today every keyword reaching here is ASCII by construction
+ * (the catalog is English; the ledger and spec sensors extract words with `[a-z]` character
+ * classes), so this branch is a guard against a future non-ASCII catalog entry failing closed.
+ */
+
+/** True when `kw`'s first character can carry a `\b` anchor — i.e. it is an ASCII word character. */
+const anchorable = (kw: string): boolean => /^[a-z0-9_]/i.test(kw);
+
+const cache = new Map<string, RegExp | null>();
+
+/**
+ * Compile `kw` to its matcher, or `null` when the keyword must be compared as a plain substring.
+ * Cached: the sensors re-ask the same handful of catalog keywords once per scenario.
+ */
+function matcherFor(kw: string): RegExp | null {
+  const key = kw.toLowerCase();
+  if (cache.has(key)) return cache.get(key)!;
+  const re = anchorable(key)
+    ? new RegExp(`\\b${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`)
+    : null;
+  cache.set(key, re);
+  return re;
+}
+
+/** Does `haystack` mention `kw` as a word (not as the tail of a longer one)? */
+export function keywordHit(haystack: string, kw: string): boolean {
+  const h = haystack.toLowerCase();
+  const re = matcherFor(kw);
+  return re ? re.test(h) : h.includes(kw.toLowerCase());
+}
+
+/** Does ANY of `haystacks` mention `kw`? */
+export function hasKeyword(haystacks: string[], kw: string): boolean {
+  return haystacks.some((h) => keywordHit(h, kw));
+}

package/src/harness/manifest.ts

@@ -13,6 +13,7 @@ import * as path from 'path';
 import { createHash } from 'crypto';
 import { featureFilesFor, reportSlug } from './unit-paths';
 import { readTextFile } from './read-text';
+import { vpCodeOf } from './parse';
 
 export interface SpecSection { name: string; hash: string }
 export interface ManifestEntry { scenario: string; vpCode?: string; section: string; specHash: string }
@@ -90,8 +91,7 @@ function parseFeatureSections(featurePath: string): { scenario: string; vpCode?:
     const s = line.match(/^Scenario:\s*(.*)$/);
     if (s) {
       const name = s[1].trim();
-      const code = name.match(/\bVP-[A-Z]+-\d+/i)?.[0];
-      out.push({ scenario: name, vpCode: code, section });
+      out.push({ scenario: name, vpCode: vpCodeOf(name).vpCode, section });
     }
   }
   return out;

package/src/harness/next-step.ts

@@ -16,9 +16,12 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
 import { reportSlug, featureFilesFor } from './unit-paths';
 import { readTextFile } from './read-text';
 import { checkAssetsDrift } from '../orchestrator/assets-drift';
+import { viewpointFileIsAiDraft } from './viewpoint-draft-header';
+import { readViewpointDeclaration } from './viewpoint-baseline';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -40,6 +43,8 @@ export interface UnitState {
   kind: 'screen' | 'flow' | 'api';
   hasSpec: boolean;
   hasViewpoint: boolean;
+  /** test-viewpoint.md carries `drafted-by: ai` — written by the AI, not yet accepted by a QA. */
+  viewpointIsAiDraft?: boolean;
   hasContract: boolean;
   hasFlowInventory: boolean;
   scenarioCount: number;
@@ -87,6 +92,29 @@ function countScenarios(unitDir: string, unit: string): number {
  * Everything the resolver needs, read from disk. `unitId` is the catalog id
  * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory.
  */
+const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
+
+/**
+ * Does the selector text resolve at least one element? A scaffold resolves none: the web one holds
+ * only the `page` route, the mobile one only header comments. Matching the WORD "placeholder" was
+ * wrong both ways (#868): it flagged a real file whose key names an input's placeholder text, and
+ * missed both scaffolds, which never contain it.
+ */
+function hasResolvedSelector(selectorText: string): boolean {
+  let doc: unknown;
+  try { doc = parseYaml(selectorText); } catch { return selectorText.trim().length >= 40; }
+  if (!doc || typeof doc !== 'object') return false;
+  // A real cell, not a marker left to be filled in. Numbers count (an id or index can be numeric).
+  const real = (v: unknown): boolean => (typeof v === 'string' || typeof v === 'number')
+    && String(v).trim() !== '' && !/^(?:todo|tbd|placeholder|replace me)$/i.test(String(v).trim());
+  return Object.values(doc as Record<string, unknown>).some((e) => {
+    if (!e || typeof e !== 'object') return false;
+    const { type, value, name, locator } = e as { type?: unknown; value?: unknown; name?: unknown; locator?: unknown };
+    // Every SelectorEntry shape: a CSS `locator`, or a non-page `type` with a value or a role name.
+    return real(locator) || (typeof type === 'string' && type !== 'page' && (real(value) || real(name)));
+  });
+}
+
 export function readUnitState(
   projectRoot: string, unitDir: string, unit: string, kind: UnitState['kind'],
 ): UnitState {
@@ -101,7 +129,7 @@ export function readUnitState(
   // `readTextFile` throws on a missing file, and every path here is legitimately absent at some
   // point in a unit's life — the resolver exists to report exactly that, so it must not crash on it.
   const read = (p: string): string => (fs.existsSync(p) ? readTextFile(p) : '');
-  const selectorText = selectorFiles.map((f) => read(path.join(selectorsDir, f))).join('\n');
+  const selectorTexts = selectorFiles.map((f) => read(path.join(selectorsDir, f)));
   const contractPath = path.join(req, 'flow-contract.yaml');
   const contractText = read(contractPath);
 
@@ -116,7 +144,9 @@ export function readUnitState(
   });
   const hasResults = specDirs.some((d) => {
     try {
-      return fs.readdirSync(d).some((f) => f.endsWith('-test-result.json'));
+      // `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env
+      // run (SUNGEN_ENV=staging) the env; both are runs (#868).
+      return fs.readdirSync(d).some((f) => RESULT_FILE.test(f));
     } catch { return false; }
   });
   let hasDeliverable = false;
@@ -131,6 +161,9 @@ export function readUnitState(
     unit, kind,
     hasSpec: exists(path.join(req, 'spec.md')),
     hasViewpoint: exists(path.join(req, 'test-viewpoint.md')),
+    // An id-less draft has nothing to accept: only the missing-yardstick step speaks for it.
+    viewpointIsAiDraft: viewpointFileIsAiDraft(path.join(req, 'test-viewpoint.md'))
+      && readViewpointDeclaration(path.join(req, 'test-viewpoint.md')) !== null,
     hasContract: exists(contractPath),
     // A contract WITHOUT `flows:` can only be scored per phase, which is a materially weaker
     // claim — so it is part of the state, not a detail.
@@ -139,8 +172,7 @@ export function readUnitState(
     hasSelectors: selectorFiles.length > 0,
     // A scaffolded selector file exists but resolves nothing; treating it as "done" is what
     // makes a run look further along than it is.
-    selectorsArePlaceholder: selectorFiles.length > 0
-      && (/TODO|PLACEHOLDER|REPLACE ME/i.test(selectorText) || selectorText.trim().length < 40),
+    selectorsArePlaceholder: selectorFiles.length > 0 && !selectorTexts.some(hasResolvedSelector),
     compiled, hasResults, hasDeliverable,
     assetsDrift: (() => {
       const d = checkAssetsDrift(projectRoot);
@@ -170,6 +202,7 @@ const REPAIRABLE = [
   'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'SPEC-CLAUSE-UNCOVERED',
   'TRIGGER-UNCOVERED', 'PERMISSION-PAIR-MISSING', 'VISIBILITY-PAIR-MISSING',
   'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
+  'UI-INVENTORY-MISSING', 'UI-INVENTORY-INCOMPLETE', 'UI-ITEM-UNCOVERED',
 ];
 
 /**
@@ -219,6 +252,15 @@ export function deriveSteps(s: UnitState): NextStep[] {
     });
     return out;
   }
+  // Before any generation: the AI drafts the viewpoint and audits it BEFORE it writes scenarios, so
+  // this is exactly where a draft would otherwise be accepted by the process that wrote it.
+  if (s.viewpointIsAiDraft) {
+    out.push({
+      kind: 'decide',
+      command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
+      because: 'test-viewpoint.md is marked `drafted-by: ai` — nobody has reviewed it, so the ledger and traceability axes are held as unverified. A QA reviews the claims (adds what matters, deletes what does not), then accepts; the command records the baseline and removes the marker. A decision, not a step: an agent presents it and does not run it',
+    });
+  }
   if (s.scenarioCount === 0) {
     out.push({ kind: 'do', command: design, because: 'no scenarios exist yet' });
     return out;
@@ -234,7 +276,7 @@ export function deriveSteps(s: UnitState): NextStep[] {
     out.push({ kind: 'do', command: `sungen audit --screen ${s.unit}`, because: 'the suite has never been measured' });
     return out;
   }
-  if (s.audit.viewpointBaselineStatus === 'changed') {
+  if (s.audit.viewpointBaselineStatus === 'changed' && !s.viewpointIsAiDraft) {   // the draft's own decide step is already above
     out.push({
       kind: 'decide',
       command: `sungen audit --screen ${s.unit} --accept-viewpoint`,