@hone-ai/cli 1.40.0 → 1.42.0

package/lib/run-report.js

@@ -18,7 +18,7 @@
 
 // HC-GF-234: the one wording for a step's unanswered question, shared with `--status`, `show
 // step` and the human-gate prompt. A pure leaf module, so this file stays pure.
-const { normalizeQuestion, questionLines, countPhrase } = require('./operator-question');
+const { normalizeQuestion, questionLines, countPhrase, scrub } = require('./operator-question');
 
 /** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
 const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
@@ -69,6 +69,28 @@ function durationOf(startedAt, endedAt) {
 const BLOCKING_REASON_CODES = Object.freeze(['MAX_RETRIES_EXCEEDED', 'MAX_TOTAL_STEPS_EXCEEDED']);
 const BLOCKING_REASON_RE = new RegExp(`^(${BLOCKING_REASON_CODES.join('|')})[^\\n]*`);
 
+/**
+ * HC-GF-030: the pause the architect-consult guard takes. NOT in BLOCKING_REASON_CODES, which is pinned equal to
+ * what orchestrator-guardrails.js emits (HC-GF-046b); this one is emitted by workflow-dag.js's
+ * validateStepPreConditions. Approving is refused for it too — by the route and by approveGate — so it is a decision
+ * and not a gate. The server package and this one cannot share a constant, so
+ * tests/regression/HC-GF-030-run-report.test.js pins this string equal to architect-consult.js CONSULT_REQUIRED_CODE.
+ */
+const CONSULT_REQUIRED_CODE = 'ARCHITECT_CONSULT_REQUIRED';
+const CONSULT_REQUIRED_RE = new RegExp(`^${CONSULT_REQUIRED_CODE}:[^\\n]*`);
+/** The start of the message a batch run pauses with when its consult failed the mechanical check (orchestrator.js). */
+const CONSULT_NEEDS_PERSON_RE = /^architect consult needs a person to read it[^\n]*/;
+/**
+ * HC-GF-379-followup-1: the PAUSE-ERA message. Before HC-GF-379, a consult whose OWN verdict was `checklist_b_completed: false`
+ * paused the run with this message. Since HC-GF-379 a false consult routes back to step_0 (workflow-dag.js
+ * FAILURE_ROUTING_TABLE.step_0b.step_0b_abort: a retry, at most twice, then the run ends failed), so no new run pauses with it;
+ * this regex is kept only for runs that paused under the old routing. Approving one is refused (an `_abort` needs an
+ * acknowledgement, and even then nothing records a false verdict), so offering `--approve` here is HC-GF-046 again: the line
+ * invites the one action the server has already decided to refuse.
+ * tests/regression/HC-GF-030-run-report.test.js pins this branch verbatim with a literal pause-era message.
+ */
+const CONSULT_ABORT_RE = /^step_0b: the architect consult did not complete Checklist B[^\n]*/;
+
 /**
  * HC-GF-046(b), corrected in review: a step that used up its format retries.
  *
@@ -82,6 +104,22 @@ const BLOCKING_REASON_RE = new RegExp(`^(${BLOCKING_REASON_CODES.join('|')})[^\\
  */
 const EXHAUSTED_RE = /^GARBAGE_OUTPUT at (step_[0-9a-z]+)/;
 
+/** HC-GF-036(b), HC-GF-379-followup-1: adverse verdicts in the agent's own vocabulary. Module scope so a test can pin
+ *  `step_0b_abort` to the kind failure-router.js's step_0b detector returns. */
+const ADVERSE_VERDICTS = Object.freeze({
+  review_reject: 'returned a FAIL review',
+  security_high: 'raised a HIGH security finding',
+  security_medium: 'raised a MEDIUM security finding',
+  test_fail: 'reported failing tests',
+  lint_fail: 'reported lint errors',
+  perf_finding: 'raised a performance finding',
+  validator_rejected: 'produced output the format validator rejected',
+  step_0b_abort: 'the architect consult answered false',
+});
+/** HC-GF-379: the run's error_message when the third false consult ends it (workflow-dag.js routeFailure's reason).
+ *  The packages cannot share it at runtime; tests/regression/HC-GF-030-run-report.test.js pins it to the producer. */
+const CONSULT_ROUTE_LIMIT_RE = /^max retries \((\d+)\) exceeded for step_0b:step_0b_abort$/;
+
 function buildReport(run, extra = {}) {
   const cfg = run.config || {};
   const steps = Array.isArray(run.steps) ? run.steps : [];
@@ -107,7 +145,28 @@ function buildReport(run, extra = {}) {
     // untrustworthy in the other direction.
     const blocked = String(run.errorMessage || '').match(BLOCKING_REASON_RE);
     const exhausted = String(run.errorMessage || '').match(EXHAUSTED_RE);
-    if (run.approvalRefusal) {
+    const consultRequired = String(run.errorMessage || '').match(CONSULT_REQUIRED_RE);
+    const consultNeedsPerson = String(run.errorMessage || '').match(CONSULT_NEEDS_PERSON_RE);
+    const consultAbort = String(run.errorMessage || '').match(CONSULT_ABORT_RE);
+    if (consultRequired) {
+      needsYou.push({
+        what: `run CANNOT proceed at ${run.currentStep} — ${scrub(consultRequired[0].slice(0, 400))}. There is no waiver and `
+          + 'approving is refused, so this is a decision, not a gate',
+        how: `hone run-story ${run.runId} --kill   (then re-run the story: step_0 is cached, so it costs one consult)`,
+      });
+    } else if (consultNeedsPerson) {
+      needsYou.push({
+        what: `the architect consult is waiting for a person to read it — ${scrub(consultNeedsPerson[0].slice(0, 400))}`,
+        how: `hone show step ${run.runId} step_0b   (then hone run-story ${run.runId} --approve step_0b once you have read it)`,
+      });
+    } else if (consultAbort) {
+      needsYou.push({
+        what: `the architect consult did not pass at ${run.currentStep} — ${scrub(consultAbort[0].slice(0, 400))}. Approving is refused, `
+          + 'so this is a decision, not a gate',
+        how: `hone show step ${run.runId} step_0b   (read what it flagged, change the story to answer it, `
+          + `then hone run-story ${run.runId} --kill and run the story again)`,
+      });
+    } else if (run.approvalRefusal) {
       // HC-GF-074: rendered from the server's own decision, never re-derived from verdict records here.
       needsYou.push({
         what: `run CANNOT be approved at ${run.currentStep} as it stands — ${String(run.approvalRefusal.message).slice(0, 300)}`,
@@ -136,10 +195,23 @@ function buildReport(run, extra = {}) {
     }
   }
   if (run.status === 'failed') {
-    needsYou.push({
-      what: `run FAILED${run.errorMessage ? `: ${String(run.errorMessage).slice(0, 160)}` : ''}`,
-      how: `hone show step ${run.runId} ${run.currentStep || '<stepKey>'}`,
-    });
+    // HC-GF-379-followup-1: a third false consult ends the run failed at step_0b. Both the row AND the route's own
+    // reason must say so: a guardrail or budget that failed step_0b after one false verdict keeps the generic line.
+    const consultRow = steps.find((x) => x && x.stepKey === 'step_0b');
+    const limit = run.currentStep === 'step_0b'
+      && (consultRow && consultRow.diagnostics && consultRow.diagnostics.failure_record || {}).failure_kind === 'step_0b_abort'
+      && String(run.errorMessage || '').match(CONSULT_ROUTE_LIMIT_RE);
+    if (limit && ADVERSE_VERDICTS.step_0b_abort) {
+      needsYou.push({
+        what: `run FAILED: ${ADVERSE_VERDICTS.step_0b_abort} ${Number(limit[1]) + 1} times, the route-back limit`,
+        how: `hone show step ${run.runId} step_0b   (every consult attempt's findings, newest first)`,
+      });
+    } else {
+      needsYou.push({
+        what: `run FAILED${run.errorMessage ? `: ${String(run.errorMessage).slice(0, 160)}` : ''}`,
+        how: `hone show step ${run.runId} ${run.currentStep || '<stepKey>'}`,
+      });
+    }
   }
   // HC-GF-065: a KILLED run needs you too.
   //
@@ -186,17 +258,9 @@ function buildReport(run, extra = {}) {
     // conflation that was inflating batch failure_rates — and it points the operator at
     // the wrong thing to fix. The verdict kinds name the agent's own vocabulary.
     const kind = (s.diagnostics && s.diagnostics.failure_record || {}).failure_kind;
-    const VERDICT = {
-      review_reject: 'returned a FAIL review',
-      security_high: 'raised a HIGH security finding',
-      security_medium: 'raised a MEDIUM security finding',
-      test_fail: 'reported failing tests',
-      lint_fail: 'reported lint errors',
-      perf_finding: 'raised a performance finding',
-      validator_rejected: 'produced output the format validator rejected',
-    };
-    const what = kind && VERDICT[kind]
-      ? `${s.stepKey} (${s.agent || 'agent'}) ${VERDICT[kind]}`
+    if (kind === 'step_0b_abort') continue; // HC-GF-379-followup-1: reported once, in 1b′ below
+    const what = kind && ADVERSE_VERDICTS[kind]
+      ? `${s.stepKey} (${s.agent || 'agent'}) ${ADVERSE_VERDICTS[kind]}`
       : `${s.stepKey} (${s.agent || 'agent'}) ${s.status === 'failed' ? 'FAILED' : 'was REJECTED'}`;
     needsYou.push({
       what: `${what} — the run is recorded ${run.status}, so nothing downstream will revisit it`,
@@ -205,6 +269,35 @@ function buildReport(run, extra = {}) {
     });
   }
 
+  // 1b′. HC-GF-379-followup-1: the latest step_0b row is a false consult. Steps carry only the latest attempt, so a
+  // consult that went false and then true raises nothing here. Named once: skipped when the run-failed item or the
+  // pause-era abort branch above already names it.
+  {
+    const em = String(run.errorMessage || '');
+    const row = steps.find((x) => x && x.stepKey === 'step_0b');
+    const rowKind = row && (row.diagnostics && row.diagnostics.failure_record || {}).failure_kind;
+    const namedAbove = (run.status === 'failed' && run.currentStep === 'step_0b')
+      || (run.status === 'paused' && run.currentStep && em.match(CONSULT_ABORT_RE));
+    if (rowKind === 'step_0b_abort' && !namedAbove) {
+      // "Paused at step_0" means the plain gate only: the final else of the paused branch above.
+      const plainGate = run.status === 'paused' && run.currentStep === 'step_0' && !run.approvalRefusal
+        && ![BLOCKING_REASON_RE, EXHAUSTED_RE, CONSULT_REQUIRED_RE, CONSULT_NEEDS_PERSON_RE, CONSULT_ABORT_RE].some((re) => em.match(re));
+      const regrooming = run.status === 'running' || plainGate;
+      const suffix = regrooming
+        ? 'the run is re-grooming with these findings'
+        : `the run is recorded ${run.status}${run.status === 'failed' && run.currentStep ? ` at ${run.currentStep}` : ''}, `
+          + 'so nothing downstream will revisit it';
+      needsYou.push({
+        what: `step_0b: ${ADVERSE_VERDICTS.step_0b_abort} — ${suffix}`,
+        how: `hone show step ${run.runId} step_0b`,
+        howLabel: 'inspect',
+        // A run inside the consult loop needs nobody: the pipeline is answering the findings itself. Shown, not counted
+        // toward the exit code (a paused run's own gate item, when there is one, still is).
+        ...(regrooming ? { advisory: true } : {}),
+      });
+    }
+  }
+
   // 1c. HC-GF-041: a retry that came back with LESS than the attempt it replaces.
   //
   // The newest attempt REPLACES the previous one for every downstream consumer, so this
@@ -430,6 +523,26 @@ function buildReport(run, extra = {}) {
       worthKnowing.push(`${s.stepKey} ran ${s.attempts} times`);
     }
   }
+  // HC-GF-030: a run that finished with an architect classified as needed and no consult recorded. The consult
+  // guard makes this unreachable for a run the server drove; it is said here because "no run records
+  // `architect_engaged: true` with no consult" is the acceptance, and a report is where that gets checked.
+  const arch = run.architect && typeof run.architect === 'object' ? run.architect : null;
+  // HC-GF-397-followup-1: `hone run-story --consult-architect` asks for a consult on a `not_engaged` grooming. Read the way
+  // the server reads it — the boolean `true` only — so a requested consult that is not approved is never "not needed".
+  const consultRequested = cfg.consult_architect === true;
+  if (arch && (arch.verdict !== 'not_engaged' || consultRequested) && !arch.consulted && run.status === 'completed') {
+    const why = arch.verdict === 'engaged' ? 'the architect classified as needed'
+      : arch.verdict === 'not_engaged' ? 'an architect consult REQUESTED with --consult-architect'
+      : 'the architect verdict unreadable';
+    needsYou.push({
+      what: `run COMPLETED with ${why} and NO approved consult`,
+      how: `hone show step ${run.runId} step_0b`,
+      // HC-026c: a new signal must not turn every run that finished BEFORE the consult step existed into a failing exit
+      // code (about 27 of 28 completed runs on the local server were engaged). Shown in full, counted in `needsYou`, and
+      // not gating: the consult guard is what stops a new run, and this line is for reading a run that predates it.
+      advisory: true,
+    });
+  }
   // The two "blind run" tells, both from HC-GF-006's preflight reasoning.
   const descChars = typeof cfg.story_description === 'string' ? cfg.story_description.length : 0;
   if (descChars === 0) {
@@ -459,9 +572,21 @@ function buildReport(run, extra = {}) {
     duration: durationOf(run.startedAt, run.completedAt),
     cost: extra.cost || null,
     architectConsulted: cfg.architect_consulted === true,
+    // HC-GF-030: derived server-side from the step rows, never from config. null on a server that predates it.
+    architect: arch ? {
+      verdict: arch.verdict, consulted: arch.consulted === true, requested: consultRequested,
+      // A number or nothing: this is printed, and it came off the network.
+      consultAttempt: Number.isFinite(Number(arch.consultAttempt)) && Number(arch.consultAttempt) > 0 ? Math.trunc(Number(arch.consultAttempt)) : null,
+      blockers: Number(arch.blockers) || 0,
+      // Agent-written text going to a terminal: the server scrubs it, and this CLI may be talking to an older or different
+      // server, so it scrubs again where it is stored for printing (the rule cli/lib/operator-question.js already keeps).
+      findings: (Array.isArray(arch.findings) ? arch.findings : []).map(f => scrub(String(f).slice(0, 400))),
+      callSiteGaps: (Array.isArray(arch.callSiteGaps) ? arch.callSiteGaps : []).map(g => scrub(String(g).slice(0, 400))),
+    } : null,
     storyDescriptionChars: descChars,
     bundledFiles: bundled,
-    classifierAxes: Array.isArray(cfg.classifier_axes) ? cfg.classifier_axes : [],
+    // The groomer's own words (the server harvests them from step_0's output), printed on a terminal: scrubbed, and strings only.
+    classifierAxes: Array.isArray(cfg.classifier_axes) ? cfg.classifier_axes.map(a => scrub(String(a).slice(0, 80))) : [],
     needsYou,
     worthKnowing,
     steps,
@@ -530,6 +655,21 @@ function renderReport(r) {
     L.push('');
   }
 
+  if (r.architect) {
+    const a = r.architect;
+    L.push('ARCHITECT');
+    L.push(`  ${a.verdict === 'engaged' ? 'engaged' : a.verdict === 'not_engaged' ? 'not engaged (step_0 said so, readably)' : 'verdict unreadable (the consult runs)'}`
+      + `${r.classifierAxes.length ? ` · axes: ${r.classifierAxes.join(', ')}` : ''}`
+      // HC-GF-397-followup-1: the request is named only where it changed the outcome — an engaged or unreadable verdict
+      // runs the consult anyway, so its line stays as it was.
+      + `${a.requested && a.verdict === 'not_engaged' ? ' · consult requested (--consult-architect)' : ''}`
+      + ` · consult ${a.consulted ? `approved${a.consultAttempt ? ` (step_0b attempt ${a.consultAttempt})` : ''}` : a.verdict === 'not_engaged' && !a.requested ? 'not needed' : 'NOT approved'}`);
+    if (a.blockers > 0) L.push(`  ${a.blockers} finding(s) marked BLOCKER`);
+    for (const f of a.findings) L.push(`  · ${f}`);
+    for (const g of a.callSiteGaps) L.push(`  ⚠ call sites the consult could not see: ${g}`);
+    L.push('');
+  }
+
   L.push('STEPS');
   for (const s of r.steps) {
     const mark = s.status === 'completed' ? '✓' : s.status === 'skipped' ? '○' : '·';
@@ -540,8 +680,11 @@ function renderReport(r) {
   L.push('');
 
   L.push('RUN FACTS');
+  // HC-GF-030: the consult state comes from the server's step rows when it reports them (`architect`); the config flag is
+  // only a mirror, cleared by a new grooming, and is what an older server still reports.
+  const consultedFact = r.architect ? r.architect.consulted : r.architectConsulted;
   L.push(`  mode ${r.mode || 'unknown'} · story text ${r.storyDescriptionChars} chars · `
-         + `${r.bundledFiles} file(s) bundled · architect_consulted ${r.architectConsulted}`);
+         + `${r.bundledFiles} file(s) bundled · architect_consulted ${consultedFact}`);
   if (r.classifierAxes.length) L.push(`  axes: ${r.classifierAxes.join(', ')}`);
   if (r.verifications.length) {
     for (const v of r.verifications) {
@@ -554,4 +697,6 @@ function renderReport(r) {
   return L.join('\n');
 }
 
-module.exports = { BLOCKING_REASON_CODES, buildReport, renderReport, durationOf, ACTIONABLE_GATE_VERDICTS };
+module.exports = {
+  BLOCKING_REASON_CODES, buildReport, renderReport, durationOf, ACTIONABLE_GATE_VERDICTS, ADVERSE_VERDICTS, CONSULT_ROUTE_LIMIT_RE,
+};