@sun-asterisk/sungen 3.3.0-alpha.4 → 3.3.0-alpha.6

package/src/harness/next-step.ts

@@ -27,6 +27,7 @@ import {
   countFailedResults, countScenarios, hasDeliverableFor, hasResolvedSelector, isCompiled, readIfExists, unitResultFiles,
 } from '../graph/unit-artifact-probes';
 import { AuditNotCounted, ContractFacts, ContractSummary, readContractFacts, readTrustedAudit } from '../graph/unit-state-facts';
+import { ResultsFreshness, resultsFreshness } from '../graph/unit-results-freshness';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -89,6 +90,8 @@ export interface UnitState {
   contract?: ContractSummary;
   /** Per-test-case state (DOS-11.1); absent when not read from disk or unreadable. */
   testCases?: TestCaseState[];
+  /** Which run the results come from and what they are older than (#942); absent without results. Advisory, decides no step. */
+  results?: ResultsFreshness;
   steps: NextStep[];
 }
 
@@ -162,6 +165,10 @@ export function readUnitState(
     state.testCases = testCaseStates(projectRoot, unit, { unitDir, auditFindings: state.audit?.findings ?? [] })
       .map((tc) => (contract?.cases.has(tc.id) ? { ...tc, contract: contract.cases.get(tc.id) } : tc));
   } catch { /* an unparseable .feature — the unit-level nodes still answer, as before test-case state */ }
+  try {
+    const results = resultsFreshness(projectRoot, unitDir, unit);
+    if (results) state.results = results;
+  } catch { /* advisory: results that cannot be dated add nothing */ }
   state.steps = deriveSteps(state);
   return state;
 }

package/src/harness/triage-manual-classification.ts

@@ -0,0 +1,76 @@
+/**
+ * `sungen triage --screen <u> --case <id> --as product|test-defect|environment --reason "…"` (#928):
+ * classify one red by hand — the one `sungen triage` left unclassified, or one it got wrong — as a
+ * `triage-classification` decision in the unit's `decisions/` (read back by graph/manual-triage-decisions.ts).
+ *
+ *   validated first   the class, a reason, a case that exists, is red and is not exempt — before any
+ *                     prompt, so a human never confirms something that is then rejected
+ *   product           stricter than any automatic class (it leads to a QA decision): anyone may record it
+ *   test-defect,      can hide a product defect behind "fix the test" / "re-run": a human types a
+ *   environment       confirmation on a terminal (DOS-13.4); without one it is refused, nothing is
+ *                     written and the exact command is printed. Only after the typed phrase does the
+ *                     entry carry `humanConfirmed: true`, and a reader ignores one without it
+ *   bound             evidence_hash = the case's red as it reads now; a re-run voids the classification
+ */
+import type { AppendResult } from '../decisions/append-decision';
+import { appendDecision } from '../decisions/append-decision';
+import type { DecisionDraft } from '../decisions/decision-schema';
+import { gitUserName } from '../decisions/decision-source';
+import { ConfirmationIO, formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { HUMAN_ONLY_TRIAGE, MANUAL_TRIAGE_AS, ManualTriageClass, TRIAGE_DECISION_KIND } from '../graph/manual-triage-decisions';
+import { exemptionOf } from '../graph/test-case-satisfied';
+import { testCaseStates } from '../graph/test-case-states';
+import { unitScopeOfDir } from './gates/unit-gate-overrides';
+
+export interface ClassifyRedCaseInput {
+  projectRoot: string;
+  unit: string;
+  caseId: string;
+  /** product | test-defect | environment */
+  as: string;
+  reason?: string;
+  io: ConfirmationIO;
+}
+
+export interface ClassifyRedCaseResult extends AppendResult { caseId: string; class: ManualTriageClass }
+
+export async function classifyRedCase(i: ClassifyRedCaseInput): Promise<ClassifyRedCaseResult> {
+  const cls = Object.prototype.hasOwnProperty.call(MANUAL_TRIAGE_AS, i.as) ? MANUAL_TRIAGE_AS[i.as] : undefined;
+  if (!cls) throw new Error(`--as must be one of ${Object.keys(MANUAL_TRIAGE_AS).join(', ')} (got "${i.as}")`);
+  const reason = (i.reason ?? '').trim();
+  if (!reason) throw new Error('--reason is required: a classification records WHY this red is what you say it is');
+  const found = resolveUnitCandidates(i.unit, i.projectRoot);
+  if (found.length !== 1) throw new Error(`"${i.unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api`);
+  const unitDir = found[0].dir;
+  const scope = unitScopeOfDir(i.projectRoot, unitDir);
+  if (!scope) throw new Error(`"${i.unit}" has no decisions scope`);
+  const cases = testCaseStates(i.projectRoot, i.unit, { unitDir, auditFindings: [] });
+  const tc = cases.find((c) => c.id === i.caseId);
+  if (!tc) {
+    const known = cases.slice(0, 8).map((c) => c.id).join(', ');
+    throw new Error(`no test case "${i.caseId}" in ${i.unit}${known ? ` — known: ${known}${cases.length > 8 ? ', …' : ''}` : ''}`);
+  }
+  if (tc.result !== 'failed' || !tc.evidence) throw new Error(`${tc.id} has no red result to classify (result: ${tc.result})`);
+  const exempt = exemptionOf(tc);
+  if (exempt) throw new Error(`${tc.id} is exempt (${exempt}) — it needs no classification`);
+
+  const human = HUMAN_ONLY_TRIAGE.has(cls);
+  if (human) {
+    await requireTypedConfirmation({
+      what: `classify the red ${tc.id} of ${i.unit} as ${cls}`,
+      phrase: tc.id,
+      command: formatCommand(['sungen', 'triage', found[0].kind === 'api' ? '--api' : '--screen', i.unit, '--case', tc.id, '--as', i.as, '--reason', reason]),
+      summary: [`case: ${tc.title}`, `automatic triage: ${tc.triage ? `${tc.triage.class} (${tc.triage.ruleId})` : 'none current'}`, `reason: ${reason}`,
+        `recorded by: ${gitUserName(i.projectRoot)}`, `as ${cls} it leaves the product-defect path — confirm only after reading its evidence (trace, error)`,
+        'it stops counting as soon as the case runs again'],
+      io: i.io,
+    });
+  }
+  const draft: DecisionDraft = {
+    kind: TRIAGE_DECISION_KIND, anchors: [], text: `${tc.id} is ${cls}: ${tc.title}`, reason,
+    payload: { case: tc.id, class: cls, ...(human ? { humanConfirmed: true } : {}) },
+    source: { by: gitUserName(i.projectRoot), where: 'cli' }, valid_from: new Date().toISOString(), visibility: 'internal', evidence_hash: tc.evidence,
+  };
+  return { ...appendDecision(i.projectRoot, scope, draft), caseId: tc.id, class: cls };
+}

package/src/harness/unit-paths.ts

@@ -49,3 +49,22 @@ export function featureFilesFor(unitDir: string, unit: string): string[] {
     ...names.filter((n) => n !== canonicalName),
   ].map((n) => path.join(dir, n));
 }
+
+/**
+ * The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> ·
+ * api/flows/<flow>; a bare screen is its basename. Shared by the audit, which scores and links the
+ * unit under this id, and its inputsHash, which reads what the audit reads under the same id.
+ */
+export function catalogIdFromScreenDir(screenDir: string): string {
+  const parts = screenDir.split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0) {
+    if (parts[qa + 1] === 'api' && parts[qa + 2] === 'flows' && parts[qa + 3]) return `api/flows/${parts[qa + 3]}`;
+    if (parts[qa + 1] === 'api' && parts[qa + 2]) return `api/${parts[qa + 2]}`;
+    if (parts[qa + 1] === 'flows' && parts[qa + 2]) return `flows/${parts[qa + 2]}`;
+  }
+  return path.basename(screenDir);
+}
+
+/** A screen unit — the only kind a sibling flow credits (TQ-4); flows and api units are not. */
+export const isScreenUnitId = (catalogId: string): boolean => !/^(flows|api)\//.test(catalogId);

package/src/hooks/guard-tty-spoof-rule.ts

@@ -2,7 +2,8 @@
  * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
  * through a terminal emulator.
  *
- * `contract approve`, `journey --waive`, `journey --decide` and `journey --signoff` refuse without a TTY (DOS-13.4), and
+ * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff` and `triage --as test-defect|environment`
+ * (#928: a red classified away from the product-defect path) refuse without a TTY (DOS-13.4), and
  * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
  * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
  * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
@@ -13,7 +14,7 @@
 import type { GuardRule } from './guard-rules';
 
 const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
-const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b)/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b)/i;
 
 export const ttySpoof: GuardRule = {
   id: 'tty-spoof',
@@ -23,7 +24,8 @@ export const ttySpoof: GuardRule = {
     if (!cmd || !TTY_EMULATOR.test(cmd) || !HUMAN_GATED.test(cmd)) return null;
     return {
       status: 'ask',
-      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff`) through a terminal '
+      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff` / '
+        + '`triage --as test-defect|environment`) through a terminal '
         + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
         + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
     };