@sun-asterisk/sungen 3.2.17 → 3.2.18

package/src/harness/sensors.ts

@@ -10,6 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
+import { readTextFile } from './read-text';
 
 // Business-critical category keywords (matched by CONTAINMENT against the VP category, so a
 // compound category like LIST-DISPLAY / ADD-TO-CART / PRODUCT-DISCOVERY classifies correctly).
@@ -56,7 +57,7 @@ export interface Catalog {
 
 export function loadCatalog(): Catalog {
   const p = path.join(__dirname, 'catalog', 'universal-viewpoints.yaml');
-  return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
+  return parseYaml(readTextFile(p)) as Catalog;
 }
 
 // Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
@@ -76,6 +77,10 @@ const has = (haystacks: string[], kw: string) => {
 
 export interface GateResult {
   pageType: string | null;
+  /** How the page type was decided — a declaration is authoritative, a guess is not. */
+  pageTypeSource?: 'declared' | 'detected' | 'undetermined';
+  /** Keyword evidence behind a detected type (best hits vs the runner-up). */
+  pageTypeEvidence?: { hits: number; runnerUp: number };
   themesTotal: number;
   themesCovered: number;       // deeply covered (has a data assertion)
   coverageRatio: number;
@@ -83,7 +88,18 @@ export interface GateResult {
   universalGaps: string[];
 }
 
-export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false): GateResult {
+/**
+ * An explicit `page-type: <id>` line in test-viewpoint.md — the project stating what
+ * kind of screen this is. A declaration always beats keyword detection.
+ */
+export function declaredPageType(viewpointText: string, catalog: Catalog): string | null {
+  const m = viewpointText.match(/^\s*(?:[-*]\s*)?\**page[- ]?type\**\s*[:=]\s*`?([a-z0-9-]+)`?/im);
+  if (!m) return null;
+  const id = m[1].toLowerCase();
+  return Object.keys(catalog.page_types).includes(id) ? id : null;
+}
+
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false, viewpointText = ''): GateResult {
   const haystacks = [
     ...scenarios.map((s) => s.haystack),
     ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
@@ -94,14 +110,35 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
   // too, so a mobile commerce/form screen is selected as ecommerce-list/form by keyword fit —
   // `mobile-home` does not crowd out a better-fitting type. With no type matching → pageType stays
   // null → no themes required → the gate passes leniently rather than false-FAILing.
+  // Detection needs EVIDENCE, not a single coincidental word. A knowledge-base search
+  // screen was classified `ecommerce-list` on ONE keyword hit and then judged against
+  // cart / add-to-cart / brand-filter themes it can never have — 40% of the quality
+  // score decided by one word, in both directions (an earlier misread scored it `auth`
+  // and handed it 3/3). Below the threshold the page type is UNDETERMINED: no themes
+  // are demanded (the audit says so instead of inventing a gap), and the project can
+  // settle it for good by declaring `page-type:` in test-viewpoint.md.
+  const MIN_HITS = 2;        // at least two distinct keywords
+  const MIN_MARGIN = 1;      // and a clear lead over the runner-up
   let pageType: string | null = null;
+  let source: GateResult['pageTypeSource'] = 'undetermined';
   let best = 0;
-  for (const [pt, def] of Object.entries(catalog.page_types)) {
-    if (pt.startsWith('mobile-') && !isMobile) continue;
-    const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
-    if (hits > best) { best = hits; pageType = pt; }
+  let runnerUp = 0;
+  const declared = declaredPageType(viewpointText, catalog);
+  if (declared) {
+    pageType = declared;
+    source = 'declared';
+  } else {
+    for (const [pt, def] of Object.entries(catalog.page_types)) {
+      if (pt.startsWith('mobile-') && !isMobile) continue;
+      const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
+      if (hits > best) { runnerUp = best; best = hits; pageType = pt; }
+      else if (hits > runnerUp) { runnerUp = hits; }
+    }
+    if (pageType && best >= MIN_HITS && best - runnerUp >= MIN_MARGIN) source = 'detected';
+    else { pageType = null; source = 'undetermined'; }
   }
 
+  const evidence = { hits: best, runnerUp };
   const gaps: GateResult['gaps'] = [];
   let total = 0, covered = 0;
   if (pageType) {
@@ -127,8 +164,13 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
 
   return {
     pageType,
+    pageTypeSource: source,
+    pageTypeEvidence: evidence,
     themesTotal: total,
     themesCovered: covered,
+    // No page type → no themes → the ratio is NOT a free 1.0: the score treats this
+    // axis as not-applicable and renormalises, so breadth can neither be faked nor
+    // punished by a guess.
     coverageRatio: total ? covered / total : 1,
     gaps,
     universalGaps,
@@ -376,8 +418,13 @@ export function coverageBalance(scenarios: ScenarioInfo[]): BalanceResult {
     byBucket[bucketForCategory(s.category)]++;
   }
 
-  const core = byBucket['business-core'];
-  const secondary = byBucket['presentation'] + byBucket['validation-security'];
+  // `behavior` (LOGIC / TRANSITION / WORKFLOW) IS business behaviour — it is the
+  // main category of sungen's own prescribed taxonomy. Counting only the commerce/API
+  // vocabulary (CART, PRODUCT, CHECKOUT, ENDPOINT…) as core meant a standard suite of
+  // 37 VP-LOGIC scenarios scored core=0 → a balance axis of 0% on a perfectly
+  // well-balanced suite. Navigation joins the secondary side, where it belongs.
+  const core = byBucket['business-core'] + byBucket['behavior'];
+  const secondary = byBucket['presentation'] + byBucket['validation-security'] + byBucket['navigation'];
   const imbalanced = secondary > core * 1.5 && core > 0;
   const unclassifiedRatio = scenarios.length ? byBucket['other'] / scenarios.length : 0;
   // A high `other` share means the VP taxonomy drifted from the catalog — the balance axis is then

package/src/harness/spec-coverage.ts

@@ -10,6 +10,7 @@
  */
 import * as fs from 'fs';
 import { ScenarioInfo } from './parse';
+import { readTextFile } from './read-text';
 
 export type Modality = 'MUST' | 'SHOULD' | 'MAY';
 
@@ -20,6 +21,11 @@ export interface SpecCoverageResult {
   frTotal: number;
   frCovered: number;
   uncoveredMust: { id: string; text: string }[];
+  /** Requirements counted as covered ONLY by keyword inference — no scenario
+   *  cites the id. The audit accepts that (it asks "did you think about this
+   *  requirement?"), but the link is not machine-checkable: delivery's
+   *  requirement table and any later refactor cannot follow it. */
+  inferredOnly: string[];
   triggerGaps: TriggerGap[];     // per-constraint trigger matrix gaps
   verdict: 'pass' | 'warn' | 'fail';
 }
@@ -40,8 +46,12 @@ const ACTION_TRIGGER: { trigger: string; re: RegExp }[] = [
 ];
 
 function modalityOf(text: string): Modality {
-  if (/\bMUST\b/.test(text)) return 'MUST';
-  if (/\bSHOULD\b/.test(text)) return 'SHOULD';
+  // Specs are written in the project's language — a Vietnamese spec states
+  // obligation with PHẢI / KHÔNG ĐƯỢC and recommendation with NÊN. Reading only
+  // English keywords silently demoted every requirement to MAY, so the
+  // "uncovered MUST" finding could never fire on those projects.
+  if (/\bMUST\b/i.test(text) || /\bPHẢI\b/i.test(text) || /KHÔNG ĐƯỢC/i.test(text)) return 'MUST';
+  if (/\bSHOULD\b/i.test(text) || /\bNÊN\b/i.test(text)) return 'SHOULD';
   return 'MAY';
 }
 
@@ -54,7 +64,7 @@ function actionTriggersIn(text: string): string[] {
 
 export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows: ValRow[] } {
   if (!fs.existsSync(specPath)) return { frs: [], valRows: [] };
-  const lines = fs.readFileSync(specPath, 'utf-8').split('\n');
+  const lines = readTextFile(specPath).split('\n');
 
   const frs: FrClause[] = [];
   for (const line of lines) {
@@ -97,12 +107,13 @@ function scenarioBlocks(featureText: string): string[] {
 export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featureText: string): SpecCoverageResult {
   const { frs, valRows } = parseSpecClauses(specPath);
   if (!fs.existsSync(specPath) || (frs.length === 0 && valRows.length === 0)) {
-    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], triggerGaps: [], verdict: 'pass' };
+    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], verdict: 'pass' };
   }
   const featLower = featureText.toLowerCase();
 
   // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
   const uncoveredMust: { id: string; text: string }[] = [];
+  const inferredOnly: string[] = [];
   let frCovered = 0;
   for (const fr of frs) {
     const idLower = fr.id.toLowerCase();
@@ -110,8 +121,12 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     const words = [...new Set((fr.text.toLowerCase().match(/[a-z][a-z-]{4,}/g) || []))]
       .filter((w) => !/must|should|system|screen|users?|value|input|field/.test(w));
     const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= Math.min(2, words.length));
-    if (cited || kwHit) frCovered++;
-    else if (fr.modality === 'MUST') uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+    if (cited || kwHit) {
+      frCovered++;
+      if (!cited) inferredOnly.push(fr.id); // covered, but nothing links it explicitly
+    } else if (fr.modality === 'MUST') {
+      uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+    }
   }
 
   // Per-constraint trigger coverage — the matrix-collapse catch.
@@ -135,5 +150,5 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
   const verdict: SpecCoverageResult['verdict'] =
     uncoveredMust.length > 0 || triggerGaps.length > 0 ? 'fail' : 'pass';
 
-  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, triggerGaps, verdict };
+  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, inferredOnly, triggerGaps, verdict };
 }

package/src/harness/trace.ts

@@ -15,23 +15,24 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { reportSlug } from './unit-paths';
 import { segmentRuns, latestRunEvents, LedgerEvent } from './ledger';
+import { readTextFile } from './read-text';
 
 interface ManualItem { scenario: string; reason: string }
 
 function readJson(p: string): any | null {
-  try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null; } catch { return null; }
+  try { return fs.existsSync(p) ? JSON.parse(readTextFile(p)) : null; } catch { return null; }
 }
 
 function readLedger(screen: string): any[] {
   const p = path.join(process.cwd(), '.sungen', 'ledger', `${reportSlug(screen)}.jsonl`);
   if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  return readTextFile(p).split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
 }
 
 /** Parse @manual scenarios + the explanatory comment line above each. */
 function parseManual(featurePath: string): ManualItem[] {
   if (!fs.existsSync(featurePath)) return [];
-  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const lines = readTextFile(featurePath).split('\n');
   const out: ManualItem[] = [];
   for (let i = 0; i < lines.length; i++) {
     const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);

package/src/harness/viewpoint-baseline.ts

@@ -0,0 +1,128 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseViewpointOverview } from './parse';
+
+/**
+ * Keep the yardstick from moving with the thing it measures.
+ *
+ * `test-viewpoint.md` is the project's declaration of WHAT must be tested, and two
+ * scored axes measure the suite against it: `traceability` (do scenarios use the
+ * declared viewpoint ids?) and `atomicLedger` (is every declared item covered?).
+ * Both are only evidence while the declaration is INDEPENDENT of the suite.
+ *
+ * A `/sungen:create-test` run rewrote a filled test-viewpoint.md, replacing the
+ * declared categories with exactly the ones it had just generated. Both axes read
+ * 100% by construction — and the performance viewpoint it dropped on the way
+ * (4 perf scenarios → 2) went unreported, because VP-PERF was no longer declared
+ * for anything to be missing from.
+ *
+ * So: remember the declaration, and when it changes, say so and stop counting the
+ * two axes that depend on it until a human accepts the new baseline. Same rule the
+ * score model already applies to an undetermined page type — absent independent
+ * evidence scores nothing, in either direction.
+ */
+
+/** Axes whose evidence is `test-viewpoint.md` — excluded while the baseline is unconfirmed. */
+export const VIEWPOINT_DEPENDENT_AXES = ['atomicLedger', 'traceability'] as const;
+
+export interface ViewpointBaseline {
+  status: 'absent' | 'new' | 'unchanged' | 'changed';
+  /** sha1 of the normalized file — '' when the unit has no test-viewpoint.md. */
+  hash: string;
+  ids: string[];
+  /** Only on `changed`: how the declaration moved. */
+  added?: string[];
+  removed?: string[];
+  recordedAt?: string;
+}
+
+interface BaselineFile {
+  version: 1;
+  units: Record<string, { hash: string; ids: string[]; recordedAt: string }>;
+}
+
+function baselinePath(projectRoot: string): string {
+  return path.join(projectRoot, '.sungen', 'viewpoint-baseline.json');
+}
+
+function readBaselineFile(projectRoot: string): BaselineFile {
+  const p = baselinePath(projectRoot);
+  if (!fs.existsSync(p)) return { version: 1, units: {} };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8')) as BaselineFile;
+    return parsed && typeof parsed === 'object' && parsed.units ? parsed : { version: 1, units: {} };
+  } catch {
+    return { version: 1, units: {} };   // unreadable → treat as unrecorded, never throw
+  }
+}
+
+function writeBaselineFile(projectRoot: string, data: BaselineFile): void {
+  const p = baselinePath(projectRoot);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+}
+
+/**
+ * Hash the DECLARATION, not the prose: an author reflowing a sentence must not read
+ * as the taxonomy moving. Only the declared viewpoint ids are fingerprinted.
+ */
+function fingerprint(ids: string[]): string {
+  return crypto.createHash('sha1').update(ids.join('\n')).digest('hex').slice(0, 12);
+}
+
+/**
+ * Compare the unit's current test-viewpoint declaration to the recorded baseline.
+ * Read-only — recording is the caller's decision, so an audit stays a measurement
+ * and `--accept-viewpoint` stays the explicit human act. A first sighting reports
+ * `new` (nothing to compare against yet).
+ */
+export function checkViewpointBaseline(
+  projectRoot: string,
+  unitId: string,
+  viewpointPath: string,
+): ViewpointBaseline {
+  if (!fs.existsSync(viewpointPath)) return { status: 'absent', hash: '', ids: [] };
+  const ids = parseViewpointOverview(viewpointPath).map((v) => v.id).sort();
+  const hash = fingerprint(ids);
+  if (ids.length === 0) return { status: 'absent', hash: '', ids: [] };
+
+  const file = readBaselineFile(projectRoot);
+  const recorded = file.units[unitId];
+  if (!recorded) return { status: 'new', hash, ids };
+  if (recorded.hash === hash) return { status: 'unchanged', hash, ids, recordedAt: recorded.recordedAt };
+
+  const before = new Set(recorded.ids ?? []);
+  const now = new Set(ids);
+  return {
+    status: 'changed',
+    hash,
+    ids,
+    added: ids.filter((i) => !before.has(i)),
+    removed: (recorded.ids ?? []).filter((i) => !now.has(i)),
+    recordedAt: recorded.recordedAt,
+  };
+}
+
+/** Record the current declaration as the accepted baseline (`sungen audit --accept-viewpoint`). */
+export function acceptViewpointBaseline(
+  projectRoot: string,
+  unitId: string,
+  current: { hash: string; ids: string[] },
+): void {
+  const file = readBaselineFile(projectRoot);
+  file.units[unitId] = {
+    hash: current.hash,
+    ids: current.ids,
+    recordedAt: new Date().toISOString(),
+  };
+  writeBaselineFile(projectRoot, file);
+}
+
+/** Read the declaration without recording anything (used by `--accept-viewpoint`). */
+export function readViewpointDeclaration(viewpointPath: string): { hash: string; ids: string[] } | null {
+  if (!fs.existsSync(viewpointPath)) return null;
+  const ids = parseViewpointOverview(viewpointPath).map((v) => v.id).sort();
+  if (ids.length === 0) return null;
+  return { hash: fingerprint(ids), ids };
+}

package/src/harness/viewpoint-ledger.ts

@@ -10,6 +10,7 @@
  */
 import * as fs from 'fs';
 import { ScenarioInfo } from './parse';
+import { readTextFile } from './read-text';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -27,7 +28,7 @@ const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page',
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
 export function parseViewpointItems(viewpointPath: string): { id?: string; text: string }[] {
   if (!fs.existsSync(viewpointPath)) return [];
-  const lines = fs.readFileSync(viewpointPath, 'utf-8').split('\n');
+  const lines = readTextFile(viewpointPath).split('\n');
   const items: { id?: string; text: string }[] = [];
   let inFence = false;
   for (const raw of lines) {

package/src/orchestrator/assets-drift.ts

@@ -0,0 +1,64 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getPackageVersion } from '../exporters/package-info';
+
+/**
+ * Are this project's AI assets (commands + skills under `.claude/` etc.) the ones
+ * the running sungen would write?
+ *
+ * Upgrading the npm package does NOT refresh them — `sungen update` does. Nothing
+ * said so, so a project kept running prompts from an older build indefinitely: a
+ * QA upgraded, re-ran `/sungen:create-test`, and got the OLD command (141 lines vs
+ * the shipped 267) with none of the newer guidance. The failure is invisible
+ * because everything still "works", just to an older specification.
+ *
+ * The manifest already records the version + a hash per managed file; this only
+ * reads it and reports.
+ */
+export interface AssetsDrift {
+  recordedVersion: string;
+  runningVersion: string;
+  /** Managed files whose content no longer matches the manifest's hash. */
+  changed: number;
+  total: number;
+}
+
+export function checkAssetsDrift(cwd: string): AssetsDrift | null {
+  const manifestPath = path.join(cwd, '.sungen', 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;   // not a sungen project (yet)
+
+  let manifest: { version?: string; managed?: Record<string, string> };
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null;                                    // unreadable → say nothing
+  }
+  const recordedVersion = manifest.version ?? '';
+  const runningVersion = getPackageVersion();
+  const managed = manifest.managed ?? {};
+  const total = Object.keys(managed).length;
+  if (!recordedVersion || total === 0) return null;
+
+  // A version match is the common case — trust it and skip hashing entirely.
+  if (recordedVersion === runningVersion) return null;
+
+  let changed = 0;
+  for (const rel of Object.keys(managed)) {
+    if (!fs.existsSync(path.join(cwd, rel))) changed++;
+  }
+  return { recordedVersion, runningVersion, changed, total };
+}
+
+/** One line, on stderr so `--json` output stays machine-readable. */
+export function warnAssetsDrift(cwd: string): void {
+  const drift = checkAssetsDrift(cwd);
+  if (!drift) return;
+  const gray = '\x1b[90m';
+  const cyan = '\x1b[36m';
+  const reset = '\x1b[0m';
+  process.stderr.write(
+    `${gray}note: this project's AI commands/skills were written by sungen ${drift.recordedVersion}, ` +
+    `you are running ${drift.runningVersion} — run ${cyan}sungen update${reset}${gray} to refresh them ` +
+    `(upgrading the package alone does not).${reset}\n`,
+  );
+}

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -115,12 +115,16 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
      - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests
      - **Continue without it** — generate tests from spec and other sources only
 
+   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations as part of generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves, so an unannounced rewrite lowers the score rather than raising it.
+
    **Context discovery (prefer an isolated agent).** Reading all sources here can flood this context. **Claude Code:** spawn the **`sungen-discovery`** sub-agent (Task tool, `subagent_type: sungen-discovery`) to read spec/figma/ui/live in isolation and return a **compact discovery report** (sources, completeness, conflicts, recommended route, key facts); use that report instead of pasting raw sources. **Copilot / no sub-agents:** do the reading inline as below.
 {{/cap}}
 {{^cap parallel-subagents}}
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
      - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
      - **2) Continue without it** — generate tests from spec and other sources only
+
+   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations while generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves.
 {{/cap}}
 
    **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
@@ -256,3 +260,23 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 {{^cap parallel-subagents}}
 **No selectors.yaml** — selectors are generated during `/sungen-run-test`.
 {{/cap}}
+
+## Finish — always hand the next step back
+
+Do not stop after writing the files. Close every run with, in this order:
+
+1. **The traceability check below** — an untagged requirement becomes an uncovered gap at delivery.
+2. **The harness result in one line** — score, gate verdict, and the axis the `SCORE-CAPPED` finding
+   names (that finding is the single answer to "how do I raise the score").
+3. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
+   `/sungen:run-test <name>` (recommended once the tiers are written), re-running `create-test` to
+   extend, and "Done for now". A run that ends without this leaves the operator guessing.
+
+### Requirement traceability
+
+Cross-check `requirements/spec.md` against the scenarios you wrote: every `FR-`/`TR-`/`NFR-` id
+must either carry a `@spec:<id>` tag on the scenario that proves it, or be a conscious
+out-of-scope decision you state in the summary. `sungen audit` reports `SPEC-TRACE-IMPLICIT` for
+requirements it could only match by keyword — treat that list as a to-do: add the tag to the
+proving scenario, do not leave the link to inference. Delivery's requirement table follows the
+tag only, so an untagged requirement is later reported as an uncovered gap.