@hone-ai/cli 1.37.0 → 1.38.0

package/hone-cli.js

@@ -39,7 +39,8 @@ const { parseReviewJSON } = require('./lib/parse-review-json');
 const { resolveBaseRef, getMaxDiffChars } = require('./lib/release-review-config');
 const { gitEnv } = require('./lib/git-env');
 const { collectIncludePaths } = require('./lib/include-paths');
-const { runArgsError, orchestratePath } = require('./lib/run-target'); // HC-GF-270-followup-1
+const { runArgsError, orchestratePath, apiPath } = require('./lib/run-target'); // HC-GF-270-followup-1, -2
+const { normalizeQuestion, questionLines, gateQuestionLines, countPhrase } = require('./lib/operator-question'); // HC-GF-234
 const program = new Command();
 
 // HC-GF-331: spawnSync's default stdout/stderr buffer is 1 MiB. A verification suite over that
@@ -1754,7 +1755,7 @@ program
       await sleep(pollMs);
       process.stdout.write('.');
       try {
-        const r = await client.get(`/derive/${jobId}`);
+        const r = await client.get(apiPath('derive', [jobId]));
         if (r.data.status === 'complete') {
           result = r.data;
           break;
@@ -1991,6 +1992,10 @@ program
   .requiredOption('--job <jobId>', 'Job ID returned by "hone derive --refresh"')
   .option('--changes <mode>',     'Which changes to apply: all (default)', 'all')
   .action(async (opts) => {
+    // HC-GF-270-followup-2: this GETs the job named by `--job` and then POSTs its approval, so the id is
+    // checked before any config read or request: `drv_x/../../orchestrate/<run>/approve?` became a POST
+    // to another endpoint's approval.
+    refuseBadRunArgs([{ label: '--job', kind: 'deriveJobId', value: opts.job }]);
     const config = getConfig();
     const client = api(config);
 
@@ -1999,7 +2004,7 @@ program
     // Verify job is ready
     let jobData;
     try {
-      const r = await client.get(`/derive/${opts.job}`);
+      const r = await client.get(apiPath('derive', [opts.job]));
       jobData  = r.data;
     } catch (e) {
       console.error(`Failed to fetch job: ${e.response?.data?.error || e.message}`);
@@ -2017,7 +2022,7 @@ program
 
     // Apply changes
     try {
-      const r = await client.post(`/derive/${opts.job}/approve`, {
+      const r = await client.post(apiPath('derive', [opts.job, 'approve']), {
         approvedChanges: opts.changes,
       });
       console.log('✓ Changes approved and applied');
@@ -2513,6 +2518,7 @@ program
   .option('--with-learnings-report', 'Also fetch promoted-learnings report + update local YAML status (H-013)')
   .option('--force',           'Overwrite local edits (default: skip files with local changes — H-024)')
   .action(async (opts) => {
+    refuseBadRunArgs([{ label: '--repo', kind: 'pathName', value: opts.repo, optional: true }]); // HC-GF-270-followup-2
     const config   = getConfig();
     const client   = api(config);
     const repoName = opts.repo || path.basename(process.cwd());
@@ -2548,7 +2554,7 @@ program
     // ── 1. Sync derived skills ──────────────────────────────────────────────
     if (!opts.agentsOnly) {
       try {
-        const r = await client.get(`/skills/${repoName}/derived`);
+        const r = await client.get(apiPath('skills', [repoName, 'derived']));
         const { skills } = r.data;
         if (!skills.length) {
           console.log('No derived skills found. Run "hone derive" first.');
@@ -2628,7 +2634,7 @@ program
             content = editorStubContent(agent);
             console.log(`  → ${agent}: editor mode — syncing runtime stub (full prompt served ephemerally)`);
           } else {
-            const r = await client.get(`/prompts/${agent}`, {
+            const r = await client.get(apiPath('prompts', [agent]), {
               responseType: 'text',
               headers: { Accept: 'text/markdown' },
             });
@@ -2939,8 +2945,7 @@ program
       // The default request is byte-identical to the one that shipped — no query string at all —
       // so nothing that already calls this path shifts, including HC-GF-210's pin on it. The
       // parameter appears only when the operator asked for a status other than the default.
-      const qs = status === 'promoted' ? '' : `?status=${encodeURIComponent(status)}`;
-      const { data } = await client.get(`/learnings/promoted${qs}`);
+      const { data } = await client.get(apiPath('learnings', ['promoted'], { status: status === 'promoted' ? undefined : status }));
       const all = Array.isArray(data.learnings) ? data.learnings : [];
       // The two ways a promoted row reaches no run. `targetKind` is 'unrouted' when HC-GF-159a's
       // router found no target; a row promoted before that story carries neither field at all.
@@ -5958,11 +5963,7 @@ program
     const config = getConfig();
     const client = api(config);
     try {
-      const params = new URLSearchParams();
-      if (opts.status) params.set('status', opts.status);
-      if (opts.limit) params.set('limit', opts.limit);
-      const qs = params.toString();
-      const { data } = await client.get(`/orchestrate${qs ? `?${qs}` : ''}`);
+      const { data } = await client.get(apiPath('orchestrate', [], { status: opts.status, limit: opts.limit }));
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       if (!data.runs.length) { console.log('No workflow runs found.'); return; }
       const age = (ts) => {
@@ -6146,7 +6147,7 @@ function runContextIo(apiConfig) {
       }
     },
     fetchStoryContext: async (storyId) => {
-      const { data } = await api(apiConfig).get(`/stories/${encodeURIComponent(storyId)}/context`);
+      const { data } = await api(apiConfig).get(apiPath('stories', [storyId, 'context']));
       return data;
     },
     recentlyModifiedOverlap: (touched) =>
@@ -6419,6 +6420,16 @@ program
             console.log(`  (auto-verify skipped: ${e.message})`);
           }
 
+          // HC-GF-234: show what the step ASKED where the operator decides. Approving records
+          // `approved` and moves on — it does not answer the question, and until now nothing at
+          // this prompt said there was one. Printed last, right above the prompt (auto-verify's
+          // output above can run to pages), and in both the gate and the exhausted branch: the
+          // step's question rides on the attempt the operator is about to decide about.
+          // Never throws: a print must not end a poll loop.
+          try {
+            for (const line of gateQuestionLines(status, d.stepKey)) console.log(line);
+          } catch { /* a print must never end a poll loop */ }
+
           if (process.stdin.isTTY) {
             const readline = require('readline');
             const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -6481,6 +6492,14 @@ program
           // step says so instead of listing a stale failed row above a completed one.
           const tries = (s.attempts || 1) > 1 ? `  [attempt ${s.attempt} of ${s.attempts}]` : '';
           console.log(`  ${icon} ${s.stepKey}  (${s.agent})  ${s.status}${gate}${tries}`);
+          // HC-GF-234: `status: completed` / `gateResult: approved` alone cannot tell "did its
+          // work" apart from "asked a question nobody answered" — batch mode has no human gate
+          // on steps 0-3b, so this line is the only place that question ever surfaces here.
+          const asked = normalizeQuestion(s.operatorQuestion);
+          if (asked) {
+            console.log(`      asked ${countPhrase(asked.count)} nobody answered:`);
+            for (const l of questionLines(asked, { max: 120 })) console.log(`        ${l}`);
+          }
         }
         if (data.awaitingApproval && isEditorParked(data)) {
           console.log('');
@@ -7693,6 +7712,16 @@ showCmd
       console.log(`  startedAt:   ${s.startedAt || '(not started)'}`);
       console.log(`  completedAt: ${s.completedAt || '(not completed)'}`);
       if (s.tokenUsage) console.log(`  tokenUsage:  ${JSON.stringify(s.tokenUsage)}`);
+      // HC-GF-234: `status`/`gateResult` above read identically whether this step did its
+      // work or ended by asking the operator something nobody answered — surface it here so
+      // an operator does not have to read raw step output to find out.
+      const asked = normalizeQuestion(s.operatorQuestion);
+      if (asked) {
+        console.log(``);
+        console.log(`── operator question(s) — asked, not answered ──────────`);
+        console.log(`  asked ${asked.count} question(s):`);
+        for (const l of questionLines(asked)) console.log(`    ${l}`);
+      }
       if (s.errorContext) {
         console.log(``);
         console.log(`── error_context (retry feedback) ──────────────────────`);

package/lib/asset-fetch-list.js

@@ -11,6 +11,10 @@
  * network or a filesystem.
  */
 
+// HC-GF-270-followup-2: every path goes through the one builder. The derived set's repository is the
+// checkout's directory name, which can hold `?`, `#` or `%`; hand-built, `x?y` fetched `/skills/x`.
+const { apiPath } = require('./run-target');
+
 /**
  * @param {object} args
  * @param {string[]} args.agents      agent names
@@ -39,12 +43,12 @@ function assetFetchList({ agents = [], skills = [], derivedRepo = null, get, wri
   return [
     ...agents.map(agent => ({
       key: `${agent}.agent.md`,
-      promise: get(`/scripts/agent-stub/${agent}`),
+      promise: get(apiPath('scripts', ['agent-stub', agent])),
       write: (data) => writeAgent(agent, data),
     })),
     ...skills.map(skill => ({
       key: `skills/${skill}/SKILL.md`,
-      promise: get(`/skills/${skill}`),
+      promise: get(apiPath('skills', [skill])),
       write: (data) => writeSkill(skill, data),
     })),
     // ── HC-GF-184: the per-repo DERIVED set ────────────────────────────────────────────────────
@@ -59,7 +63,7 @@ function assetFetchList({ agents = [], skills = [], derivedRepo = null, get, wri
     // derived, so setup behaves exactly as before for them.
     ...(derivedRepo ? [{
       key: `skills/<derived for ${derivedRepo}>`,
-      promise: get(`/skills/${derivedRepo}/derived`),
+      promise: get(apiPath('skills', [derivedRepo, 'derived'])),
       // Tolerant by construction: this runs mid-setup, AFTER the baseline has landed, so a shape
       // change at the endpoint must not abort an adopter's install half-written.
       write: (data) => {

package/lib/operator-question.js

@@ -0,0 +1,94 @@
+/**
+ * operator-question.js — HC-GF-234: render the operator question(s) a step asked and nobody answered.
+ *
+ * A step that ends by asking the operator something used to be recorded exactly like a step that
+ * did its work (`status: completed`, `gateResult: approved`). The server now stores
+ * `{ count, questions }` on the step's attempt row and carries it as `operatorQuestion` on
+ * `GET /orchestrate/:runId` and `.../step/:stepKey`. Four CLI surfaces print it — `--status`,
+ * `show step`, the human-gate prompt, and the NEEDS YOU list — and they share this module so the
+ * wording and the two honesty rules below cannot drift apart.
+ *
+ * PURE: data in, strings out. No fs, no console, no process — a leaf, so run-report.js can keep
+ * its "derived, never narrated" contract and require it.
+ *
+ * TWO HONESTY RULES.
+ *   - `count` is the TRUE number of questions the step asked; `questions` holds at most the first
+ *     five. When count exceeds what is stored, the surfaces say "+N more not stored" instead of
+ *     letting a short list read as the whole of it.
+ *   - The text is AGENT-WRITTEN and goes to a terminal. The server scrubs control characters
+ *     before storing, but this CLI may talk to an older or different server, so it scrubs again
+ *     at the point of printing: C0/C1 controls, DEL, and the bidirectional controls that reorder
+ *     what a terminal draws.
+ *
+ * TOLERANT OF AN OLDER SERVER BY CONSTRUCTION: a missing key, null, or a payload of the wrong
+ * shape normalises to null, which is today's output (nothing printed).
+ */
+
+// U+061C ARABIC LETTER MARK is the third bidi mark beside LRM/RLM (review round 3 F3). Written as
+// \u escapes: a literal bidi character in this source would reorder how THIS file reads.
+// eslint-disable-next-line no-control-regex -- the whole point is to match control chars.
+const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+
+function scrub(text) {
+  return String(text == null ? '' : text).replace(TERMINAL_UNSAFE_RE, '');
+}
+
+/**
+ * @param {*} oq  a step's `operatorQuestion`, straight off the network (not trusted to have a shape)
+ * @returns {{count:number, questions:string[], more:number}|null}  null = the step did not ask
+ */
+function normalizeQuestion(oq) {
+  if (!oq || typeof oq !== 'object') return null;
+  const count = Math.floor(Number(oq.count));
+  if (!Number.isFinite(count) || count < 1) return null;
+  const questions = (Array.isArray(oq.questions) ? oq.questions : []).map(scrub);
+  return { count, questions, more: Math.max(0, count - questions.length) };
+}
+
+// Clips by CODE POINT, not UTF-16 unit (review round 3 F4): a `.slice(0, max)` that lands between
+// the halves of an emoji prints a lone surrogate, which a terminal draws as U+FFFD.
+function clip(text, max) {
+  if (!Number.isFinite(max)) return text;
+  const points = Array.from(text);
+  return points.length > max ? `${points.slice(0, max).join('')}...` : text;
+}
+
+/**
+ * One entry per stored question (`- <question>`, clipped to `max` chars) and, when the step asked
+ * more than was stored, a closing `+ N more not stored`. Callers add their own indentation.
+ */
+function questionLines(asked, { max = Infinity } = {}) {
+  if (!asked) return [];
+  const lines = asked.questions.map((q) => `- ${clip(q, max)}`);
+  if (asked.more > 0) lines.push(`+ ${asked.more} more not stored`);
+  return lines;
+}
+
+function countPhrase(count) {
+  return `${count} question${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * The block printed at the human gate, right before "Approve?" — the one place the operator
+ * decides, and where approving silently consumes the question without answering it.
+ *
+ * SCOPED TO THE STEP THE RUN IS PAUSED AT (`stepKey`), the same discipline as
+ * hard-pause-remedy.js's remedyFor: the column is durable, so a question step_3b asked must not
+ * be re-printed as if it belonged to an unrelated step_4 gate.
+ *
+ * @param {object} status  a GET /orchestrate/:runId payload
+ * @param {string} stepKey the step the gate is for
+ * @returns {string[]} lines to print (empty when that step asked nothing)
+ */
+function gateQuestionLines(status, stepKey) {
+  const steps = status && Array.isArray(status.steps) ? status.steps : [];
+  const step = steps.find((x) => x && typeof x === 'object' && x.stepKey === stepKey);
+  const asked = step ? normalizeQuestion(step.operatorQuestion) : null;
+  if (!asked) return [];
+  return [
+    `  ${stepKey} asked ${countPhrase(asked.count)} that nobody has answered — approving does not answer ${asked.count === 1 ? 'it' : 'them'}:`,
+    ...questionLines(asked, { max: 240 }).map((l) => `    ${l}`),
+  ];
+}
+
+module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase };

package/lib/run-report.js

@@ -16,6 +16,10 @@
  * Rendering is separate so both are testable without a server.
  */
 
+// 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');
+
 /** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
 const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
 
@@ -324,6 +328,31 @@ function buildReport(run, extra = {}) {
     }
   }
 
+  // 1e. HC-GF-234: a step that ended by asking the operator something.
+  //
+  // `status: completed` / `gateResult: approved` cannot say this: batch mode has no human gate on
+  // steps 0-3b, and approving a gate records `approved` whether or not the question was read. The
+  // step row carries the question on its own column; this is the only place a TERMINAL run's
+  // report can tell "did its work" from "asked, and nobody here answered".
+  //
+  // Says only what is MEASURED — the step asked, and the run has no answer to it. It does not say
+  // the step produced no deliverable or that the run proceeded on a guess: nothing checks either.
+  //
+  // ADVISORY (HC-026c: a new signal REPORTS before it GATES): `hone run-report` exits 1 on any
+  // non-advisory item, and an agent that asks one benign question must not turn an adopter's
+  // passing script red overnight. Visible in the report, absent from the exit code.
+  for (const s of steps) {
+    const asked = normalizeQuestion(s.operatorQuestion);
+    if (!asked) continue;
+    needsYou.push({
+      what: `${s.stepKey} (${s.agent || 'agent'}) asked ${countPhrase(asked.count)} that nothing in this run answered`,
+      detail: questionLines(asked, { max: 200 }),
+      how: `hone show step ${run.runId} ${s.stepKey}`,
+      howLabel: 'inspect',
+      advisory: true,
+    });
+  }
+
   // 2. The last verification is ONE event, so it becomes ONE item with sub-lines.
   //    Listing "verification failed" and "lint failed" separately gave two entries
   //    for one problem resolved by one fix — and NEEDS YOU is a list of DISTINCT

package/lib/run-target.js

@@ -104,17 +104,26 @@ async function resolveRunTarget({ client, idOrStory, repoName, flag }) {
 const isStepKey = (s) => typeof s === 'string' && /^step_[0-9a-z_]+$/i.test(s);
 const isAttempt = (s) => (typeof s === 'string' || typeof s === 'number') && /^[1-9]\d{0,8}$/.test(String(s));
 const isBatchId = isRunId;
+// HC-GF-270-followup-2: POST /derive is the only producer of a derive job id (server/src/routes/derive.js),
+// and it issues `drv_` + 12 lower-case hex characters into a TEXT key compared exactly, so no other shape
+// can name a job. `hone approve --job` GETs and then POSTs under that id.
+const isDeriveJobId = (s) => typeof s === 'string' && /^drv_[0-9a-f]{12}$/.test(s);
+// A name that becomes ONE path segment, such as a repository name. Encoding makes any other character
+// safe; these three it cannot, because `new URL()` resolves `.` and `..` as directory steps.
+const isPathName = (s) => typeof s === 'string' && s !== '' && s !== '.' && s !== '..';
 
 const KINDS = {
   runId: { ok: isRunId, why: 'must be a run ID (a UUID)', hint: ' — run IDs: hone workflows' },
   batchId: { ok: isBatchId, why: 'must be a batch ID (a UUID)', hint: ' — batch IDs: hone queue-stories --list' },
   stepKey: { ok: isStepKey, why: 'must name a step, like step_4', hint: '' },
   attempt: { ok: isAttempt, why: 'must be a whole number from 1, like 2', hint: '' },
+  deriveJobId: { ok: isDeriveJobId, why: 'must be a derive job ID, like drv_0123456789ab', hint: ' — the ID "hone derive --refresh" printed' },
+  pathName: { ok: isPathName, why: 'must be a name, not empty, "." or ".."', hint: '' },
 };
 
 /**
  * The first failed check's message, or null when every check passes.
- * @param {Array<{ label: string, kind: 'runId'|'batchId'|'stepKey'|'attempt', value: any, optional?: boolean }>} checks
+ * @param {Array<{ label: string, kind: 'runId'|'batchId'|'stepKey'|'attempt'|'deriveJobId'|'pathName', value: any, optional?: boolean }>} checks
  *   `label` is the flag or positional as the operator typed it. An `optional` check passes when the value
  *   is undefined (a flag that was not given); an empty string is always checked.
  */
@@ -130,23 +139,29 @@ function runArgsError(checks) {
 }
 
 /**
- * The one way a CLI verb builds an `/orchestrate/…` path. Each segment is encoded exactly once, and the
- * segments encoding cannot make safe (empty, `.`, `..`, null, undefined) throw: every caller-supplied value
- * has passed `runArgsError` first, so a throw here is a bug, not an input error. Query values that are
- * null, undefined, false or '' are dropped; the rest go through URLSearchParams.
+ * The one way the CLI builds a path on the Hone API: `/<prefix>/<segment>/…?<query>`. `prefix` is a
+ * literal resource name (`derive`, `skills`, …), never a value. Each segment is encoded exactly once, and
+ * the segments encoding cannot make safe (empty, `.`, `..`, null, undefined) throw: every caller-supplied
+ * value has passed `runArgsError` first, so a throw here is a bug, not an input error. Query values that
+ * are null, undefined, false or '' are dropped; the rest go through URLSearchParams.
  *
  * Callers pass raw values. A pre-encoded segment would be encoded twice (`%` becomes `%25`), and the
- * HC-GF-270-followup-1 scan fails on one.
+ * HC-GF-270-followup-2 scan fails on one.
+ *
+ * HC-GF-270-followup-2: generalized from orchestratePath. HC-GF-270-followup-1 closed the defect under
+ * `/orchestrate/`; `/derive/`, `/skills/`, `/prompts/`, `/scripts/` and `/stories/` were still built by
+ * hand, and `hone approve --job` POSTed under an id nothing checked.
  */
-function orchestratePath(segments, query) {
-  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+function apiPath(prefix, segments, query) {
+  if (typeof prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(prefix)) throw new TypeError(`apiPath: prefix must be a resource name, got ${JSON.stringify(prefix)}`);
+  if (!Array.isArray(segments)) throw new TypeError('apiPath: segments must be an array');
   const parts = segments.map((v, i) => {
-    if (v === null || v === undefined) throw new TypeError(`orchestratePath: segment ${i} is ${v}`);
+    if (v === null || v === undefined) throw new TypeError(`apiPath: segment ${i} is ${v}`);
     const s = String(v);
-    if (s === '' || s === '.' || s === '..') throw new TypeError(`orchestratePath: segment ${i} is ${JSON.stringify(s)}`);
+    if (s === '' || s === '.' || s === '..') throw new TypeError(`apiPath: segment ${i} is ${JSON.stringify(s)}`);
     return encodeURIComponent(s);
   });
-  const base = ['', 'orchestrate', ...parts].join('/');
+  const base = ['', prefix, ...parts].join('/');
   const qs = new URLSearchParams();
   for (const [k, v] of Object.entries(query || {})) {
     if (v === null || v === undefined || v === false || v === '') continue;
@@ -156,7 +171,13 @@ function orchestratePath(segments, query) {
   return q ? `${base}?${q}` : base;
 }
 
+/** An `/orchestrate/…` path: `apiPath('orchestrate', …)` with at least one segment (HC-GF-270-followup-1). */
+function orchestratePath(segments, query) {
+  if (!Array.isArray(segments) || segments.length === 0) throw new TypeError('orchestratePath: segments must be a non-empty array');
+  return apiPath('orchestrate', segments, query);
+}
+
 module.exports = {
   resolveRunTarget, isRunId, LOOKUP_LIMIT,
-  isStepKey, isAttempt, isBatchId, runArgsError, orchestratePath,
+  isStepKey, isAttempt, isBatchId, isDeriveJobId, isPathName, runArgsError, apiPath, orchestratePath,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {