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

package/src/harness/viewpoint-ledger.ts

@@ -58,13 +58,6 @@ function claimedCount(text: string): number | null {
 }
 
 const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.Title, VP7-002, MS-HP-001, TV-01
-/**
- * A bullet declares only the id it STARTS with (after a `[ ]` checkbox); one further along is a
- * citation (`… (SG-01, …)`). `- **High** VP-…` or `- Email shown — VP-…` therefore carry no id.
- */
-const BULLET_ID = new RegExp(`^[\\s(#]*(?:\\[[ xX]\\]\\s*)?\\[?${ID_RE.source}`);
-/** A table cell that is an id and nothing else. */
-const WHOLE_ID = new RegExp(`^${ID_RE.source}$`);
 
 /**
  * Lines that DECLARE something about the checklist rather than being a checklist item —
@@ -109,31 +102,17 @@ const PROCEDURE_LEAD = /^(?:how to (?:run|test|reproduce|verify)|(?:manual )?pro
 const LIST_ITEM = /^(?:[-*+]|\d+[.)])\s+/;
 const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page', 'screen', 'button', 'link', 'text', 'check', 'verify', 'should', 'with', 'when', 'then', 'user', 'this', 'that', 'each', 'item', 'items']);
 
-/**
- * `decision`: a `- D4: …` line under Design Decisions. It names the spec's intent so rows can cite
- * it; its testable part is carried by a VP row (review check 8). No scenario ever carries `D4`, so
- * as a ledger item it stayed MISSING for good — "not tested" decisions included (phase-7 D5). The
- * ledger skips it; the continuity, source and integrity checks still read it. Only that section
- * declares: a QA claim labelled `D8` elsewhere stays a claim, and an id-less decision bullet stays
- * the prose claim it always was.
- */
-export interface ViewpointItem { id?: string; text: string; decision?: true }
-const DECISION_ID = /^D\d+$/;
-const DECISIONS_SECTION = /^(?:design decisions?|quyết định(?: thiết kế)?)\b/i;
-
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
-export function parseViewpointItems(viewpointPath: string): ViewpointItem[] {
+export function parseViewpointItems(viewpointPath: string): { id?: string; text: string }[] {
   if (!fs.existsSync(viewpointPath)) return [];
   const lines = readViewpointText(viewpointPath).split('\n');
-  const items: ViewpointItem[] = [];
+  const items: { id?: string; text: string }[] = [];
   let inFence = false;
   let inDeclarationSection = false;
   // The level an excluded section was opened at. A SUBSECTION inherits it: `### Optional`
   // nested under `## 8. Traceability Index` used to re-open the section and hand its rows
   // back as claims, because exclusion was recomputed from scratch at every heading.
   let excludedAt: number | null = null;
-  // The level the Design Decisions section was opened at, while inside it (see `decision`).
-  let decisionsAt: number | null = null;
   // Inside the list a PROCEDURE_LEAD introduced: the indent of the lead (-1 for a paragraph lead),
   // whose list items — and their wrapped continuation lines — are steps. A heading, a table, a
   // new lead, or (after a paragraph lead) a blank line once a step was read ends it: when in
@@ -168,28 +147,21 @@ export function parseViewpointItems(viewpointPath: string): ViewpointItem[] {
     if (heading) {
       const level = heading[1].length;
       if (excludedAt !== null && level > excludedAt) continue;   // still inside the excluded section
-      if (decisionsAt !== null && level > decisionsAt) continue; // a subsection of Design Decisions
       // A heading both ends the previous section and decides whether this one declares or claims.
       // Strip an ordinal prefix ("## 5. Known Issues", "## 8. Viewpoint Grouping") before
       // testing. The regex anchors at the start, so a NUMBERED heading matched nothing and
       // every excluded section leaked its rows back in as claims — a real viewpoint numbers
       // its sections, so in practice the exclusion list was doing nothing at all (#657).
-      // `Phần 4:` / `Part 4.` / `Mục 4.` number a section the same way.
-      const headText = heading[2].replace(/[*`]/g, '').replace(/^\s*(?:(?:[Pp]hần|[Pp]art|[Mm]ục|[Ss]ection)\s+)?(?:\d+|[A-Z])\s*[.):]\s*/, '').trim();
+      const headText = heading[2].replace(/[*`]/g, '').replace(/^\s*(?:\d+|[A-Z])\s*[.):]\s*/, '').trim();
       inDeclarationSection = DECLARATION_SECTION.test(headText);
       excludedAt = inDeclarationSection ? level : null;
-      decisionsAt = DECISIONS_SECTION.test(headText) ? level : null;
       continue;
     }
     if (inDeclarationSection) continue;
     let text = '';
     let lead = '';
-    let declared: RegExpMatchArray | null = null;
     const bullet = line.match(/^(?:[-*+]|\d+[.)])\s+(.*)$/);
-    if (bullet) {
-      text = bullet[1]; lead = bullet[1];
-      declared = lead.replace(/[*`]/g, '').match(BULLET_ID);
-    }
+    if (bullet) { text = bullet[1]; lead = bullet[1]; }
     else if (line.startsWith('|')) {                       // table data row
       if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
       // The row right above a `|---|` separator IS the header, whatever its words (`Skill #`,
@@ -200,14 +172,7 @@ export function parseViewpointItems(viewpointPath: string): ViewpointItem[] {
       const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
       if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status|step|flow|ref|level|question|screen|actor|branches from|own steps|component|thành phần|trường|bước)$/i.test(cells[0] || '')) continue; // header
       text = cells.join(' — ');
-      // The lead is the row's FIRST cell, empty or not: a continuation row (`| | | case | … see SG-02 |`)
-      // declares nothing. A later cell holding an id and nothing else still declares (`| x | VP-UI-001 |`),
-      // and so does a row number followed by a cell that starts with one (`| 1 | VP-UI-001 — … |`).
-      const raw = line.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.replace(/[*`]/g, '').trim());
-      lead = raw[0] ?? '';
-      declared = lead.match(ID_RE)
-        ?? (/^\d+\.?$/.test(lead) ? (raw[1] ?? '').match(BULLET_ID) : null)
-        ?? raw.slice(1).map((c) => c.match(WHOLE_ID)).find(Boolean) ?? null;
+      lead = cells[0] ?? '';
     } else continue;
     text = text.replace(/[*`]/g, '').trim();
     if (!text) continue;
@@ -222,16 +187,15 @@ export function parseViewpointItems(viewpointPath: string): ViewpointItem[] {
     // under a grouping section. It declares nothing; it points at things declared elsewhere.
     const leadIds = new Set((leadClean.match(new RegExp(ID_RE.source, 'g')) || []).filter((x) => /\d/.test(x)));
     if (leadIds.size > 1) continue;
-    const id = declared && /\d/.test(declared[1]) ? declared[1] : undefined; // require a digit so prose words aren't IDs
+    const idM = leadClean.match(ID_RE) ?? text.match(ID_RE);
+    const id = idM && /\d/.test(idM[1]) ? idM[1] : undefined; // require a digit so prose words aren't IDs
     // A row keyed by a bare GROUP prefix ("VP-LOGIC — transitions — High — why the flow exists")
     // declares a family and its priority, not a checklist item: nothing can "cover" it, and
     // demanding coverage sends the author looking for a test that was never meant to exist.
     if (/^VP-[A-Z]+\s*(?:—|-|\||$)/.test(leadClean) && !/\d/.test(leadClean)) continue;
     const words = (text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w));
     if (!id && words.length < 2) continue;                 // not substantive enough to track
-    items.push(decisionsAt !== null && id && DECISION_ID.test(id)
-      ? { id, text: text.slice(0, 100), decision: true }
-      : { id, text: text.slice(0, 100) });
+    items.push({ id, text: text.slice(0, 100) });
   }
   return items;
 }
@@ -242,7 +206,6 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
   // (#622) — silently collapsing those would remove its input.
   const seen = new Set<string>();
   const items = parseViewpointItems(viewpointPath)
-    .filter((i) => !i.decision)
     .filter((i) => { const k = `${i.id ?? ''}|${i.text}`; if (seen.has(k)) return false; seen.add(k); return true; });
   if (!fs.existsSync(viewpointPath) || items.length === 0) {
     return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [], manualOnly: [], partial: [] };
@@ -434,15 +397,11 @@ export function viewpointIntegrity(
 
   // The Priority-Viewpoints table: `| <id> | <priority> | <reason> |`.
   const vpText = readViewpointText(viewpointPath);
-  const words = [...vpText
+  const rows = [...vpText
     .matchAll(new RegExp(`^\\|\\s*((?:VP|FL)[A-Z0-9._-]*)\\s*\\|\\s*(${PRIORITY_WORDS})\\s*\\|`, 'gim'))]
     .map((m) => m[2].toLowerCase());
-  // Fold only synonyms (Medium / Med / Normal are one level). `critical` stays its own word: a
-  // Critical / High / High table is a ranking, and folding it into `high` made it read as uniform.
-  const level = (w: string): string => (/^(?:medium|med|normal)$/.test(w) ? 'normal' : w);
-  const uniformPriority = words.length >= 3 && new Set(words.map(level)).size === 1
-    ? { levels: [words[0]], rows: words.length } // the word QA wrote, not the folded key
-    : null;
+  const levels = [...new Set(rows)];
+  const uniformPriority = rows.length >= 3 && levels.length === 1 ? { levels, rows: rows.length } : null;
 
   return { duplicateIds, danglingRefs, uniformPriority };
 }

package/src/index.ts

@@ -20,7 +20,8 @@ export type { ResolvedAppProfile } from './generators/test-generator/app-profile
 export type { MappedStep } from './generators/test-generator/step-mapper';
 // The shared "nothing honest to compile" step body. Exported for the driver SPI: a pattern that
 // must refuse (SG-W017 and siblings) emits THIS rather than shipping a one-sided refusal template,
-// which would fail the adapter-parity gate and push playwright off its refusal-only floor of 0.
+// which would fail the adapter-parity gate and push playwright off its refusal-only floor (1 — the
+// `date-picker-unsupported` refusal both adapters ship for the resolver-based fill-input pattern, #907).
 export { unsupportedStepCode } from './generators/test-generator/patterns/unsupported-step-code';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';

package/src/orchestrator/ai-skills/commands.ts

@@ -63,13 +63,15 @@ export function parseCommandSource(text: string, id: string): CommandSource {
 }
 
 const unquote = (s: string) => s.replace(/^['"]|['"]$/g, '');
+/** A YAML single-quoted scalar: an apostrophe is written twice, or it ends the value early (#899). */
+const sq = (s: string) => `'${s.replace(/'/g, "''")}'`;
 
 /** Claude command file — MUST reproduce the exact existing format (byte-identical gate). */
 export function renderClaudeCommand(c: CommandSource): string {
   const fm = [
     '---',
     ...(c.name ? [`name: ${c.name}`] : []), // some commands (locale) omit name
-    `description: '${c.description}'`,
+    `description: ${sq(c.description)}`,
     `argument-hint: ${c.argumentHint}`,
     `allowed-tools: ${c.claudeTools}`,
     '---',
@@ -82,8 +84,8 @@ export function renderCopilotCommand(c: CommandSource): string {
   const fm = [
     '---',
     `name: sungen-${c.id}`,
-    `description: '${c.description}'`,
-    `argument-hint: '${unquote(c.argumentHint)}'`,
+    `description: ${sq(c.description)}`,
+    `argument-hint: ${sq(unquote(c.argumentHint))}`,
     `agent: 'agent'`,
     `tools: ${c.copilotTools}`,
     '---',

package/src/orchestrator/ai-skills/golden-skills.test.ts

@@ -16,12 +16,14 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { parseDocument } from 'yaml';
 import { buildOutputs } from './build';
 import { parseCommandSource } from './commands';
 
 const FIX = path.resolve(__dirname, '..', '..', '..', 'tests', 'golden', 'ai-skills', 'fixtures');
 const SRC = path.resolve(__dirname, '..', 'templates', 'ai-src', 'skills');
 const SRC_CMD = path.resolve(__dirname, '..', 'templates', 'ai-src', 'commands');
+const SRC_CFG = path.resolve(__dirname, '..', 'templates', 'ai-src', 'config');
 const UPDATE = process.argv.includes('--update');
 
 function lint(): string[] {
@@ -47,6 +49,18 @@ function lint(): string[] {
     if (!c.description) errs.push(`commands/${f}: missing description`);
     if (c.order != null) { const k = String(c.order); if (seen.has(k)) { /* allowed: parallel entrypoints */ } else seen.set(k, f); }
   }
+  // The CLAUDE.md / copilot-instructions tables are the always-loaded index of what ships, so
+  // they must list every skill and command, with the right count (#899).
+  const skills = fs.readdirSync(SRC).filter((d) => fs.existsSync(path.join(SRC, d, 'SKILL.md')));
+  const cmds = fs.readdirSync(SRC_CMD).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+  for (const [cfg, prefix] of [['claude.md', '/sungen:'], ['copilot.md', '/sungen-']] as const) {
+    const t = fs.readFileSync(path.join(SRC_CFG, cfg), 'utf8');
+    for (const s of skills) if (!t.includes(`| \`${s}\` |`)) errs.push(`config/${cfg}: skills table misses ${s}`);
+    const listed = (c: string) => [' ', '`'].some((end) => t.includes(`| \`${prefix}${c}${end}`));
+    for (const c of cmds) if (!listed(c)) errs.push(`config/${cfg}: workflow table misses ${prefix}${c}`);
+    const n = t.match(/## Workflow \((\d+) AI commands\)/)?.[1];
+    if (Number(n) !== cmds.length) errs.push(`config/${cfg}: says ${n} AI commands, ${cmds.length} ship`);
+  }
   return errs;
 }
 
@@ -77,6 +91,15 @@ function run() {
     else codexNames.set(m[1], f.outputPath);
   }
 
+  // The key regex in lint() accepts frontmatter a real YAML parser rejects (an unquoted ": ", an
+  // unescaped apostrophe inside '...'), and assistants then drop every field silently (#899).
+  // Parse what ships — renderers re-quote command fields, so a valid source is not enough.
+  for (const f of outputs) {
+    if (!f.content.startsWith('---')) continue;
+    const doc = parseDocument(f.content.slice(3, f.content.indexOf('\n---', 3)));
+    for (const e of doc.errors) lintErrs.push(`${f.outputPath}: frontmatter is not valid YAML — ${e.message.split('\n')[0]}`);
+  }
+
   if (UPDATE) {
     fs.rmSync(FIX, { recursive: true, force: true });
     for (const f of outputs) {

package/src/orchestrator/flow-manager.ts

@@ -8,7 +8,6 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
-import { viewpointScaffold } from './viewpoint-scaffold';
 
 export interface FlowOptions {
   name: string;
@@ -144,7 +143,7 @@ export class FlowManager {
     fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName, isMobile), 'utf-8');
 
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
-    fs.writeFileSync(viewpointPath, viewpointScaffold(`${options.name} Flow`, isMobile), 'utf-8');
+    fs.writeFileSync(viewpointPath, this.generateViewpointTemplate(options), 'utf-8');
 
     console.log(`Created files:`);
     console.log(`  ${path.relative(this.cwd, featurePath)}`);
@@ -218,7 +217,7 @@ export class FlowManager {
       restored.push(file);
     };
     ensure(path.join(paths.requirementsDir, 'spec.md'), () => this.generateSpecTemplate(options, flowName, isMobile));
-    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => viewpointScaffold(`${options.name} Flow`, isMobile));
+    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => this.generateViewpointTemplate(options));
     ensure(paths.featurePath, () => this.generateFeatureTemplate(options, flowName, isMobile));
     return restored;
   }
@@ -288,6 +287,57 @@ export class FlowManager {
 `;
   }
 
+  private generateViewpointTemplate(options: FlowOptions): string {
+    return [
+      `# ${options.name} Flow — Test Viewpoints`,
+      '',
+      '## Edge Cases',
+      '',
+      '<!-- Sample — replace with actual edge cases for this flow:',
+      '- Network drops between screen transitions — should resume or show error?',
+      '- Session expires mid-flow — should redirect to login and preserve progress?',
+      '- Browser back button at step 3 — should return to step 2 with data intact?',
+      '- Complete flow twice rapidly — should prevent duplicate submissions',
+      '-->',
+      '',
+      '## Known Issues',
+      '',
+      '<!-- Sample — replace with actual known issues:',
+      '- [BUG-001] Form data lost if user navigates away and returns',
+      '- [BUG-002] Confirmation page shows stale data on slow connections',
+      '-->',
+      '',
+      '## Design Decisions',
+      '',
+      '<!-- Sample — replace with actual design decisions:',
+      '- Flow requires completing all steps in order (no skip)',
+      '- Draft is auto-saved at each step transition',
+      '- Cancel at any step discards the entire flow',
+      '-->',
+      '',
+      '## Cross-Screen Concerns',
+      '',
+      '<!-- Sample — replace with actual cross-screen concerns:',
+      '- Auth role must remain consistent across all screens',
+      '- Data entered in step 1 must be visible in confirmation (step 3)',
+      '- Error in step 2 should allow returning to step 1 without re-entering data',
+      '-->',
+      '',
+      '## Priority Viewpoints',
+      '',
+      '<!-- Rate importance for this flow (High / Medium / Low / Skip):',
+      '',
+      '| VP | Priority | Reason |',
+      '|---|----------|--------|',
+      '| VP-UI | Medium | Standard forms across screens |',
+      '| VP-VAL | High | Cross-screen validation rules |',
+      '| VP-LOGIC | High | Multi-step business logic, state transitions |',
+      '| VP-SEC | Medium | Auth must persist, role-based access at each screen |',
+      '-->',
+      '',
+    ].join('\n');
+  }
+
   private generateFeatureTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
     const description = options.description || `complete the ${options.name} flow`;
 

package/src/orchestrator/screen-manager.ts

@@ -8,7 +8,7 @@ import * as path from 'path';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 import { resolveWebBaseUrl } from '../exporters/env-qa';
-import { viewpointScaffold } from './viewpoint-scaffold';
+import { uiPatternRows } from './viewpoint-pattern-catalog';
 
 export interface ScreenOptions {
   name: string;
@@ -158,11 +158,59 @@ export class ScreenManager {
       fs.writeFileSync(specPath, this.generateSpecTemplate(options, screenName), 'utf-8');
     }
 
-    // Generate requirements test-viewpoint.md (only on first screen creation): the QA template,
-    // samples inside comments, so an untouched file declares nothing (see viewpoint-scaffold.ts).
+    // Generate requirements test-viewpoint.md (only on first screen creation)
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
     if (!fs.existsSync(viewpointPath)) {
-      fs.writeFileSync(viewpointPath, viewpointScaffold(options.name, isMobile), 'utf-8');
+      fs.writeFileSync(viewpointPath, [
+        `# ${options.name} — Test Viewpoints`,
+        '',
+        '## Edge Cases',
+        '',
+        '<!-- Sample — replace with actual edge cases for this screen:',
+        '- Paste emoji into text fields (e.g., 🎉👋) — should accept or sanitize?',
+        '- Input 10,000+ characters into free text — truncate or reject?',
+        '- Double-click Submit rapidly — should only create 1 record',
+        '- Browser back button after successful submit — should not re-submit',
+        '-->',
+        '',
+        '## Known Issues',
+        '',
+        '<!-- Sample — replace with actual known issues:',
+        '- [BUG-001] Date picker does not work on Safari < 16',
+        '- [BUG-002] File upload silently fails for files > 20MB (no error shown)',
+        '- Search does not handle Vietnamese accents correctly ("Nguyên" ≠ "Nguyen")',
+        '-->',
+        '',
+        '## Design Decisions',
+        '',
+        '<!-- Sample — replace with actual design decisions:',
+        '- Show all validation errors at once (not one at a time) — per UX review',
+        '- Cancel button resets form completely (no draft saving)',
+        '- Anonymous mode hides sender name but keeps department visible',
+        '-->',
+        '',
+        '## UI Patterns Identified',
+        '',
+        '<!-- Check applicable patterns for this screen (numbered as in the sungen-viewpoint skill):',
+        '',
+        '| # | Pattern | Applicable? | Notes |',
+        '|---|---------|-------------|-------|',
+        ...uiPatternRows(isMobile),
+        '-->',
+        '',
+        '## Priority Viewpoints',
+        '',
+        '<!-- Rate importance for this screen (High / Medium / Low / Skip):',
+        '',
+        '| VP | Priority | Reason |',
+        '|---|----------|--------|',
+        '| VP-UI | High | Complex form with many states |',
+        '| VP-VAL | High | 14 validation rules from spec |',
+        '| VP-LOGIC | Medium | Standard CRUD, no complex business rules |',
+        '| VP-SEC | Low | Internal tool, basic auth only |',
+        '-->',
+        '',
+      ].join('\n'), 'utf-8');
     }
 
     // Auto-screenshot: capture page only when --capture is set and not mobile (requires --path)

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -119,7 +119,7 @@ if 1, 3 or 8 fails, propose SPLITTING into separate flows:
 4. Is that outcome **valuable to the actor**? (an order placed, a password reset — not "a page rendered")
 5. Is **every step necessary** for that outcome?
 6. Are all steps at the **same business abstraction**?
-7. Are optional/error branches **phases of this goal** (ER/EH), not new goals?
+7. Are optional/error branches **flows of this goal** (Alternate / Exception flows), not new goals?
 8. Does **no segment** form an independently valuable flow on its own?
 9. Can you write **a single clear final assertion**?
 10. Can you name it "**Verb + outcome**"? (`place-order`, `reset-password` — not `cart-and-filter`)
@@ -134,8 +134,11 @@ Record the screen list — you will need it for:
 ### 1b. Author the Flow Contract (`requirements/flow-contract.yaml`)
 
 Write the answers down as the flow's contract — `sungen audit` scores the flow **against it**
-(the `flowCoverage` axis: HP/ER/EH journey phases; `FLOW-OUTCOME-UNPROVEN` when no automated
-scenario asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it):
+(the `flowCoverage` axis, per declared flow; `FLOW-OUTCOME-UNPROVEN` when no automated scenario
+asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it). The audit
+also requires **both guarantees** and the **`flows:` inventory** on every contract —
+`FLOW-GUARANTEE-MISSING` / `FLOW-INVENTORY-MISSING` otherwise, and the top mark is withheld — so
+write them now rather than meet them after the spec and viewpoint are reviewed:
 
 ```yaml
 goal: "Place an order for a product added from home"   # Verb + outcome
@@ -146,7 +149,22 @@ outcome:
   screen: checkout            # the [Screen:...] namespace carrying the final proof
   assertion: "The confirmation shows the order number and the paid total"
 value: "The customer has paid; the shop has a new order"
-phases: [HP, ER, EH]          # journey phases (default); add UI only if the flow owns UI states
+successGuarantee: "An order exists with the cart's lines and total; the cart is empty"
+minimalGuarantee: "No order and no charge without a confirmation; the cart is unchanged"   # what Exception flows assert
+phases: [BF, AF, EF]          # Basic / Alternate / Exception flows (default) — the first one must reach `outcome`
+flows:                        # the inventory: every flow of the use case, each with a status
+  - id: BF
+    outcome: "The successGuarantee — order confirmed with its number and total"
+    status: covered
+  - id: AF01
+    branchFrom: "BF step 3, the user edits the quantity in the cart"
+    outcome: "Re-enters BF at step 3 with the new total"
+    status: covered
+  - id: EF01
+    branchFrom: "BF step 4, the payment is declined"
+    outcome: "The minimalGuarantee — no order, cart kept, an error shown"
+    status: pending-clarification   # covered | deferred | pending-clarification | out-of-scope
+    reason: "The decline message is not in the spec — asked the BA"
 stateful: cart                # the mutated collection, if any — enables regression-depth dims
 golden: true                  # optional — release-critical: Final Inspection expects @golden scenarios here
 external:                     # optional — legs owned by another team/vendor (System INTEGRATION Testing)
@@ -155,6 +173,10 @@ external:                     # optional — legs owned by another team/vendor (
     screens: [payment]        # the flow namespaces that leg passes through
 ```
 
+`phases: [HP, ER, EH]` (happy path / error recovery / guards) is the lighter vocabulary for a short
+single-outcome flow — it still needs both guarantees and a `flows:` inventory. Enumerating the
+flows (the step × risk matrix) is described in the `sungen-tc-generation` skill, flow section.
+
 **A filled contract is an INPUT to generation — never an output.** Like `test-viewpoint.md`,
 generation must not rewrite it to match what was generated; disagree → propose the diff and ask.
 

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

@@ -64,8 +64,7 @@ restated from screen specs the project does not hold, say so: the audit reports
 `SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
 the source.
 
-**A viewpoint you draft (mode 2, step 3) carries BOTH classification axes** — on a QA-written one
-(mode 1) a missing axis or guarantee line is a row in `viewpoint-review.md`, not an edit. `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
+**The viewpoint carries BOTH classification axes.** `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
 by TECHNICAL RISK; `BF / AF / EF` classify by BUSINESS BRANCH. They answer different questions and
 neither replaces the other — a reviewer needs to see both, so use the compound id
 (`VP-SEC-EF02-001`) and give the viewpoint a section per flow as well as its priority table by
@@ -82,8 +81,8 @@ questions and only one of them is a yardstick:
 | `flow-contract.yaml` | the USE CASE — actor · trigger · goal · precondition · both guarantees · the flow inventory | `flowCoverage` |
 | `test-viewpoint.md` | the CLAIMS the suite must prove — cross-screen concerns, edge cases, design decisions, open questions, priorities | `atomicLedger` · `traceability` |
 
-If `requirements/test-viewpoint.md` is missing or still the scaffold, **draft it before generating**
-(mode 2, step 3 — `add-flow` scaffolds the template; a run that deletes or replaces it has removed the yardstick). Without it two scored
+If `requirements/test-viewpoint.md` is missing, **write it before generating** (`add-flow` scaffolds
+a template; a run that deletes or replaces it has removed the yardstick). Without it two scored
 axes are excluded and four sensors cannot run at all — the atomic ledger, the
 declaration-integrity checks, the browser-gesture check and the two-way continuity check — so the
 audit reports `VIEWPOINT-MISSING` and the result is *unmeasured*, not passing. And the reason the
@@ -96,8 +95,8 @@ ordering choice: a yardstick derived from the scenarios reads 100% by constructi
 dropped along the way stops being missing from anything. `sungen audit` now reports
 `VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
 holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
-is to write the claims from `spec.md` and the contract, mark the file `drafted-by: ai` (its first
-line), and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA in the hand-back (`AskUserQuestion`) with what the file declares — never as a question mid-run.
+is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
+review, and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA (`AskUserQuestion`) with what the file declares, and stop.
 
 **When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
 whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several
@@ -111,9 +110,8 @@ narrow the claim to what is actually proven.
 
 **Priority comes from the declaration.** A scenario tagged `@high` under a viewpoint row that says
 `Low` is `PRIORITY-CONTRADICTED` — a smoke run selects on the tag, so it picks up work the QA
-deliberately deprioritised. Inherit the declared priority; if the tag is right, the declaration is
-what is wrong — fix it in your own draft (mode 2), or report it in `viewpoint-review.md` for the QA
-(mode 1). Never leave both on record silently.
+deliberately deprioritised. Inherit the declared priority; if the tag is right, fix the
+declaration instead of leaving both on record.
 
 ---
 
@@ -207,11 +205,22 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    **Screen requirements** — check `<base>/${input:name}/requirements/`:
 {{/cap}}
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
-   - `test-viewpoint.md` → **Viewpoint — review or draft** below, once every source is read. No question here.
 {{#cap parallel-subagents}}
+   - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), use `AskUserQuestion` to ask:
+     - **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:
    1. If `spec_figma.md` exists → read it as Figma supplement (PAT flow already completed during `add-screen`). Do NOT call any `mcp__figma__*` tool.
@@ -235,18 +244,6 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    **Cross-check + Design Inventory**: when the unit holds any design source (`ui/` images, `ui/figma-meta.md`, `spec_figma.md`), follow `sungen-tc-generation` § **Design Inventory** (reading order, one `UI-NNN` row per item, `spec+design` / `design-only` / `conflict`) and **write `requirements/ui-inventory.md`** before generating — from the discovery report's UI INVENTORY block when a sub-agent read the sources. Every `design-only` / `conflict` item must then be covered (`@ui:UI-NNN`) or deferred with a reason (`# UI-DEFERRED: UI-NNN — <reason>`) in the `.feature`; `sungen audit` reports `UI-ITEM-UNCOVERED` otherwise. Show the user the conflicts and design-only items — they are decisions, not details.
 
-   **Viewpoint — review or draft (no question asked).** Run `sungen viewpoint scan --screen <name> --json` (a flow: `--flow <name>`). It reads ids and item numbers only. Its `mode` (1 or 2) and `modeReason` name the row below — follow them; the table explains them:
-
-   | `requirements/test-viewpoint.md` | Mode | You |
-   |---|---|---|
-   | missing; nothing but the scaffold (headings, `<…>` placeholders, empty tables); or ONE OR MORE VP rows and every one of them lacks a `Kỳ vọng` | **2 — draft** | Write it from `sungen-viewpoint/viewpoint-template.md`, first line `drafted-by: ai`, keeping any row already there. Each row answers "test CÁI GÌ" and "kỳ vọng ra sao"; where the spec states the expected result, write it; only what the spec leaves open becomes a closed question in mục 5, never an invented expectation; every accepted-input class the spec names (whitelist, value list, conversion) gets an "accepted, no error" row, citing the list by name; a VP that needs a real device, account or time is `# MANUAL/ENV`. Then scan again. |
-   | first line `drafted-by: ai` | **2 — re-review** | Your draft, not yet accepted: you may revise it, from the spec and the review. |
-   | anything else — QA-written, with or without VP ids (a scaffold from an older sungen reads as this row too: delete the file to have it drafted) | **1 — review only** | Never edit it. Generate from it as written; a gap is reported, not filled. |
-
-   Then review it with `sungen-viewpoint/review-checklist.md` and the scan JSON (mode 2: fix your draft until only QA decisions remain) and write `requirements/viewpoint-review.md`, overwritten each run. Mode 2 also runs `sungen audit --screen <name> --no-baseline` before generating. Keep the review's row count for the hand-back.
-
-   **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 — your own draft included: a draft is revised from the spec, never from the scenarios. 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 in `viewpoint-review.md`** — 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.
-
    Summarize what you found in requirements and present to the user.
 
 {{#cap parallel-subagents}}
@@ -287,7 +284,6 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
      - **BALANCE** → stop expanding secondary viewpoints; add business-core scenarios first.
      - **TRACE** → align `VP-` ids with the viewpoint-overview.
    - Stop when the gate PASSes and findings clear, **or** the budget is exhausted → report residual gaps honestly (never fake a pass).
-   - **Repair never edits a QA-written viewpoint (mode 1).** A finding whose fix is an edit to `test-viewpoint.md` becomes a row in `viewpoint-review.md` for the QA when it cites one of the file's VP ids (the checklist's audit rule; anything else goes in the hand-back); in a mode-2 draft, fix the draft.
 
 5.6. **Record (reuse + observability).** Build the manifest and report usage:
    - `sungen manifest --screen <name>` — fingerprints for next-run change detection. On a **re-run**, start the whole command by `sungen manifest --screen <name> --diff` and only regenerate scenarios whose spec section changed (keep/regenerate/retire).
@@ -301,7 +297,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
 5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + real `constraints` + `errorMap`), then run `sungen data lint --screen ${input:name}` and `sungen data gen --screen ${input:name}` per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves the rest), so it is safe here. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. Then `… data validate` (values correct) + `… data crosscheck` (testcase↔data agree); for a stateful precondition, `… data state --scaffold <name>` to auto-draft → fill entities + confirm with QA → `… data state`, weave the `@manual:data-setup` `Background` (works spec+viewpoint only). **Same standard as `/sungen:create-data-test`, applied inline — do NOT run that command separately afterwards.** No input fields (navigation/list) → skip.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
-5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass. Repair never edits a QA-written viewpoint (mode 1): a finding whose fix is an edit to `test-viewpoint.md` and cites one of its VP ids becomes a row in `viewpoint-review.md`; in a mode-2 draft, fix the draft.
+5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
 5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.
 6. **Converge — show the trace.** Run `sungen trace --screen ${input:name}` and present: process map (phases + repair rounds), bottlenecks, **HUMAN-LOOP FOCUS** (@manual to verify), audit score + gate + residual gaps. Then offer next steps based on which tier was just generated:
 {{/cap}}
@@ -367,13 +363,9 @@ 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. **The viewpoint review in one line** — `Viewpoint review: N điểm cần QA xem` (N = the `[ ]` rows
-   of `requirements/viewpoint-review.md`).
-4. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
+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, "Mở viewpoint-review.md" when N > 0, and "Done for now". After a mode-2 draft also list
-   the decision `sungen audit --screen <name> --accept-viewpoint` — for the QA to run once the draft
-   is reviewed; you never run it yourself. A run that ends without this leaves the operator guessing.
+   extend, and "Done for now". A run that ends without this leaves the operator guessing.
 
 ### Requirement traceability