@sun-asterisk/sungen 3.2.24-beta.2 → 3.2.24-beta.3

package/src/harness/next-step.ts

@@ -0,0 +1,237 @@
+/**
+ * "What now?" — one deterministic resolver over the project's own state.
+ *
+ * The next step used to be hardcoded per command, and only two of twenty-nine printed one at
+ * all. So a run that ended anywhere else ended in silence: `sungen capability add mock`
+ * finished with a blank line, the operator's agent had nothing telling it what remained, and the
+ * whole session stopped mid-workflow (#597).
+ *
+ * Hardcoding it in the other twenty-seven would repeat the mistake in bulk. What decides the
+ * next step is not which command just ran — it is what the project now HOLDS: the artifacts on
+ * disk, the audit report in `.sungen/reports/`, the accepted viewpoint baseline, the compiled
+ * spec, the run results. So this reads that state and derives the answer, and every command ends
+ * by pointing here. One place to be right, one place to test.
+ *
+ * Deterministic and read-only: same project state → same answer, no network, no writes.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { reportSlug, featureFilesFor } from './unit-paths';
+import { readTextFile } from './read-text';
+
+export interface NextStep {
+  /** The command to run, as the operator would type it. */
+  command: string;
+  /** Why it is next — stated so an agent can weigh it, not just obey it. */
+  because: string;
+  /** `blocked` steps are not runnable yet; they name what to resolve first. */
+  kind: 'do' | 'blocked' | 'optional';
+}
+
+export interface UnitState {
+  unit: string;
+  kind: 'screen' | 'flow' | 'api';
+  hasSpec: boolean;
+  hasViewpoint: boolean;
+  hasContract: boolean;
+  hasFlowInventory: boolean;
+  scenarioCount: number;
+  hasSelectors: boolean;
+  selectorsArePlaceholder: boolean;
+  compiled: boolean;
+  hasResults: boolean;
+  hasDeliverable: boolean;
+  audit?: {
+    overall: number;
+    gateStatus: string;
+    findings: string[];
+    viewpointBaselineStatus?: string;
+  };
+  steps: NextStep[];
+}
+
+const exists = (p: string): boolean => fs.existsSync(p);
+
+function readJson(p: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readTextFile(p)) as Record<string, unknown>;
+  } catch {
+    return null;                                    // absent or unreadable — treated as "not run"
+  }
+}
+
+function countScenarios(unitDir: string, unit: string): number {
+  let n = 0;
+  for (const f of featureFilesFor(unitDir, unit)) {
+    const text = readTextFile(f) ?? '';
+    n += (text.match(/^\s*Scenario(?: Outline)?:/gm) ?? []).length;
+  }
+  return n;
+}
+
+/**
+ * Everything the resolver needs, read from disk. `unitId` is the catalog id
+ * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory.
+ */
+export function readUnitState(
+  projectRoot: string, unitDir: string, unit: string, kind: UnitState['kind'],
+): UnitState {
+  const req = path.join(unitDir, 'requirements');
+  const slug = reportSlug(unit);
+  const audit = readJson(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  const selectorsDir = path.join(unitDir, 'selectors');
+  let selectorFiles: string[] = [];
+  try {
+    selectorFiles = fs.readdirSync(selectorsDir).filter((f) => f.endsWith('.yaml'));
+  } catch { /* api units carry no selectors */ }
+  const selectorText = selectorFiles.map((f) => readTextFile(path.join(selectorsDir, f)) ?? '').join('\n');
+  const contractPath = path.join(req, 'flow-contract.yaml');
+  const contractText = readTextFile(contractPath) ?? '';
+
+  const specDirs = [
+    path.join(projectRoot, 'specs', 'generated', 'flows', unit),
+    path.join(projectRoot, 'specs', 'generated', unit),
+  ];
+  const compiled = specDirs.some((d) => {
+    try {
+      return fs.readdirSync(d).some((f) => f.endsWith('.spec.ts'));
+    } catch { return false; }
+  });
+  const hasResults = specDirs.some((d) => {
+    try {
+      return fs.readdirSync(d).some((f) => f.endsWith('-test-result.json'));
+    } catch { return false; }
+  });
+  let hasDeliverable = false;
+  try {
+    hasDeliverable = fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables'))
+      .some((f) => f.startsWith(`${slug}-`));
+  } catch { /* nothing exported yet */ }
+
+  const score = (audit?.score ?? {}) as { overall?: number };
+  const baseline = (audit?.viewpointBaseline ?? {}) as { status?: string };
+  const state: UnitState = {
+    unit, kind,
+    hasSpec: exists(path.join(req, 'spec.md')),
+    hasViewpoint: exists(path.join(req, 'test-viewpoint.md')),
+    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.
+    hasFlowInventory: /^\s*flows:\s*$/m.test(contractText),
+    scenarioCount: countScenarios(unitDir, unit),
+    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),
+    compiled, hasResults, hasDeliverable,
+    audit: audit
+      ? {
+        overall: typeof score.overall === 'number' ? score.overall : 0,
+        gateStatus: String(audit.gateStatus ?? 'UNKNOWN'),
+        findings: Array.isArray(audit.findings) ? (audit.findings as string[]) : [],
+        viewpointBaselineStatus: baseline.status,
+      }
+      : undefined,
+    steps: [],
+  };
+  state.steps = deriveSteps(state);
+  return state;
+}
+
+/** The finding codes worth naming in a next step — each maps to a specific repair. */
+const REPAIRABLE = [
+  'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
+  'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
+  'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'TRIGGER-UNCOVERED',
+  'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
+];
+
+/**
+ * The ordered answer. Earliest unmet precondition first, so the list reads as a path rather than
+ * a menu — and a `blocked` step names what to resolve instead of pretending it can run.
+ */
+export function deriveSteps(s: UnitState): NextStep[] {
+  const out: NextStep[] = [];
+  const design = s.kind === 'api' ? `/sungen:create-test ${s.unit}` : `/sungen:create-test ${s.unit}`;
+
+  if (!s.hasSpec && !s.hasViewpoint) {
+    out.push({
+      kind: 'blocked',
+      command: `write qa/${s.kind === 'screen' ? 'screens' : s.kind === 'flow' ? 'flows' : 'api'}/${s.unit}/requirements/spec.md`,
+      because: 'the unit has neither a spec nor a test-viewpoint, so there is nothing to generate FROM — generation without a source invents behaviour',
+    });
+    return out;
+  }
+  if (s.kind === 'flow' && !s.hasContract) {
+    out.push({
+      kind: 'blocked',
+      command: `author requirements/flow-contract.yaml, then ${design}`,
+      because: 'a flow with no contract is scored as a generic screen against page-type themes a journey cannot have (FLOW-CONTRACT-MISSING)',
+    });
+    return out;
+  }
+  if (s.scenarioCount === 0) {
+    out.push({ kind: 'do', command: design, because: 'no scenarios exist yet' });
+    return out;
+  }
+  if (s.kind === 'flow' && !s.hasFlowInventory) {
+    out.push({
+      kind: 'do',
+      command: `add \`flows:\` to requirements/flow-contract.yaml, then sungen audit --screen ${s.unit}`,
+      because: 'without the inventory, coverage is measured per PHASE — and a phase counts as covered as soon as one scenario carries it, so the number cannot tell you a flow is missing',
+    });
+  }
+  if (!s.audit) {
+    out.push({ kind: 'do', command: `sungen audit --screen ${s.unit}`, because: 'the suite has never been measured' });
+    return out;
+  }
+  if (s.audit.viewpointBaselineStatus === 'changed') {
+    out.push({
+      kind: 'do',
+      command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
+      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until you confirm the new declaration',
+    });
+  }
+  const repair = s.audit.findings
+    .map((f) => f.split(':')[0].trim())
+    .filter((code) => REPAIRABLE.includes(code));
+  if (repair.length > 0) {
+    out.push({
+      kind: 'do',
+      command: `repair, then sungen audit --screen ${s.unit}`,
+      because: `${repair.length} finding(s) name a specific repair: ${[...new Set(repair)].slice(0, 4).join(', ')}`,
+    });
+  }
+  if (s.audit.gateStatus === 'FAIL') {
+    out.push({
+      kind: 'blocked',
+      command: `repair the gate, then sungen audit --screen ${s.unit}`,
+      because: `the viewpoint gate is FAIL at ${s.audit.overall}/10 — running tests against a design that fails its own gate measures the wrong thing`,
+    });
+    return out;
+  }
+  if (s.kind !== 'api' && (!s.hasSelectors || s.selectorsArePlaceholder)) {
+    out.push({
+      kind: 'do',
+      command: `/sungen:run-test ${s.unit}`,
+      because: s.hasSelectors
+        ? 'the selector file is still a placeholder, so nothing resolves against a live page'
+        : 'no selectors exist yet — run-test generates them from the live page, compiles and auto-fixes',
+    });
+    return out;
+  }
+  if (!s.compiled) {
+    out.push({ kind: 'do', command: `sungen generate --${s.kind === 'flow' ? 'flow' : 'screen'} ${s.unit}`, because: 'the suite has not been compiled to a spec yet' });
+    return out;
+  }
+  if (!s.hasResults) {
+    out.push({ kind: 'do', command: `/sungen:run-test ${s.unit}`, because: 'the compiled spec has never been run, so every case is Pending' });
+    return out;
+  }
+  if (!s.hasDeliverable) {
+    out.push({ kind: 'do', command: `/sungen:delivery ${s.unit}`, because: 'results exist but have not been exported to the Test Case & Coverage Matrix' });
+  }
+  out.push({ kind: 'optional', command: `/sungen:create-test ${s.unit}`, because: 'extend coverage — the next tier, or the flows the inventory still lists as pending' });
+  return out;
+}

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

@@ -9,12 +9,20 @@ codex-trigger: "Run when the user asks to CREATE, generate, write, or author tes
 ---
 ## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
 
-A create-test run is NOT finished when the files are written or the audit prints. The final
-action of EVERY run — success, partial, or aborted — is the next-step hand-back
-({{#cap parallel-subagents}}an `AskUserQuestion` offering the next actions{{/cap}}{{^cap parallel-subagents}}a numbered list of next-action choices{{/cap}};
-see "Finish — always hand the next step back" at the end of this file). Ending with a prose
-summary and no choices is a broken run: the operator is left guessing. This holds no matter
-how long the generation/repair loop ran.
+A run is NOT finished when its files are written or its output prints. The final action of EVERY
+run — success, partial, or aborted — is the next-step hand-back.
+
+**Ask `sungen next <unit>` rather than deciding from memory.** It derives the answer from what the
+project actually holds (artifacts on disk, the audit report, the accepted viewpoint baseline, the
+compiled spec, the run results), so the hand-back stays correct even when the run ended somewhere
+unexpected — a failed install, a driver that turned out not to support this unit kind, an aborted
+repair loop. Every `sungen` command also prints `Next: sungen next …` as its own last line.
+
+This matters most exactly where it used to break. A run that ended on a command with no footer of
+its own — `sungen capability add`, a dead-end install — left the session with nothing to follow and
+it stopped mid-workflow. If a step turns out to be impossible, that is still a hand-back: say what
+blocked it, run `sungen next <unit>`, and offer what remains. Ending with a prose summary and no
+choices is a broken run.
 
 ---
 {{#cap parallel-subagents}}

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

@@ -27,6 +27,12 @@ inside the run, not reasons to stop and hand the work back.
   install command as the hand-back.
 - Ending this run follows the same law as create-test: the LAST action is the next-step
   hand-back (the AskUserQuestion in "After showing results"), no matter how the run went.
+  **Ask `sungen next <unit>` rather than deciding from memory** — it derives the answer from what
+  the project now holds, so the hand-back stays correct even when the run ended somewhere
+  unexpected (a failed install, a driver that does not support this unit kind, an aborted repair
+  loop). Every `sungen` command also prints `Next: sungen next …` as its own last line. A step
+  that turns out to be impossible is still a hand-back: say what blocked it, run
+  `sungen next <unit>`, and offer what remains.
 
 ---