@hone-ai/cli 1.23.0 → 1.25.0

package/hone-cli.js

@@ -2377,16 +2377,32 @@ program
         console.log('    Migrate any REPO-SPECIFIC edits then `rm -rf .github/agents/`');
       }
 
+      // HC-COMM-010 P3: in editor-mode repos, EDITOR-side agents sync as thin
+      // stubs — their instructions are composed server-side and delivered
+      // ephemerally at runtime, so the full prompt never persists to disk.
+      // Server-mode repos are UNTOUCHED (full sync — daily editor-chat use of
+      // these agents is a feature, not a leak to close).
+      const { isEditorStubbedAgent, editorStubContent } = require('./lib/editor-stub');
+      const { readExecutionMode } = require('./lib/pipeline-config');
+      const syncExecutionMode = readExecutionMode(process.cwd());
+
       let synced = 0;
       for (const agent of agents) {
         try {
-          const r = await client.get(`/prompts/${agent}`, {
-            responseType: 'text',
-            headers: { Accept: 'text/markdown' },
-          });
+          let content;
+          if (isEditorStubbedAgent(agent, syncExecutionMode)) {
+            content = editorStubContent(agent);
+            console.log(`  → ${agent}: editor mode — syncing runtime stub (full prompt served ephemerally)`);
+          } else {
+            const r = await client.get(`/prompts/${agent}`, {
+              responseType: 'text',
+              headers: { Accept: 'text/markdown' },
+            });
+            content = r.data;
+          }
           const dest = path.join(agentsDir, `${agent}.agent.md`);
           const rel = `.claude/agents/${agent}.agent.md`;
-          const result = safeWrite(dest, rel, r.data);
+          const result = safeWrite(dest, rel, content);
           if (result !== 'skipped') {
             console.log(`  ✓ ${rel}`);
             synced++;
@@ -4486,7 +4502,7 @@ program
 program
   .command('classify-story [issueId]')
   .description('Classify a GitHub issue by SDLC track. Extracts inputs from issue body/labels heuristically; reads other inputs from --input-file or interactive prompt. Outputs JSON.')
-  .option('--input-file <path>', 'YAML file with all 9 classifyStory inputs (skips GitHub fetch + interactive)')
+  .option('--input-file <path>', 'YAML file with all 10 classifyStory inputs (skips GitHub fetch + interactive)')
   .option('--interactive', 'prompt for the 5 judgment fields not heuristically extractable')
   .option('--pretty', 'human-readable output (default: --json)')
   .option('--repo-root <path>', 'repo root (default: process.cwd())')
@@ -5455,6 +5471,61 @@ program
     }
   });
 
+program
+  .command('step-instruction <runId>')
+  .description('Fetch the editor-mode instruction for a run parked awaiting_editor (HC-COMM-010 B3)')
+  .option('--format <fmt>', 'Output format: pretty | json', 'pretty')
+  .action(async (runId, opts) => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.get(`/orchestrate/${encodeURIComponent(runId)}/step-instruction`);
+      if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(`Step:      ${data.stepKey} (${data.agent})`);
+      console.log(`Contract:  ${data.contractVersion}`);
+      console.log('─'.repeat(60));
+      console.log(data.instruction);
+      console.log('─'.repeat(60));
+      console.log(`Submit with: hone submit-step ${runId} ${data.stepKey} --file <output.txt>`);
+    } catch (e) {
+      const st = e.response?.status;
+      if (st === 409) console.error(`No step awaiting the editor: ${e.response.data?.error || ''} (run status: ${e.response.data?.runStatus || '?'})`);
+      else if (st === 403) console.error(`${e.response.data?.error}: ${e.response.data?.remediation || ''}`);
+      else console.error(`Failed: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('submit-step <runId> <stepKey>')
+  .description('Submit editor-executed output for an awaiting_editor step (HC-COMM-010 B3)')
+  .option('--file <path>', 'Read the step output from this file')
+  .option('--contract <version>', 'Instruction contract version (from step-instruction)', '1')
+  .option('--format <fmt>', 'Output format: pretty | json', 'pretty')
+  .action(async (runId, stepKey, opts) => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      if (!opts.file) { console.error('Provide the output via --file <path> (the text your editor produced).'); process.exit(1); }
+      const fs = require('fs');
+      const output = fs.readFileSync(opts.file, 'utf8');
+      const { data } = await client.post(
+        `/orchestrate/${encodeURIComponent(runId)}/step/${encodeURIComponent(stepKey)}/editor-output`,
+        { contractVersion: opts.contract, output }
+      );
+      if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      console.log(`Step ${data.stepKey} completed (executed_by: ${data.executedBy}); gate: ${data.gateResult}.`);
+      console.log(`Approve when reviewed: hone run-story ${runId} --approve ${data.stepKey}`);
+      console.log('Verification is unchanged — check-patch/verify-patch judge this output, not trust.');
+    } catch (e) {
+      const st = e.response?.status;
+      if (st === 409) console.error(`Rejected: ${e.response.data?.error}`);
+      else if (st === 413) console.error(`Rejected: ${e.response.data?.error}`);
+      else console.error(`Failed: ${e.response?.data?.error || e.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('run-story <storyId>')
   .description('Run the SDLC pipeline for a story via the orchestrator')
@@ -5463,6 +5534,7 @@ program
   .option('--branch <name>', 'Git branch (default: current)')
   .option('--status', 'Show status of the latest workflow run for this story')
   .option('--kill', 'Kill the latest workflow run for this story')
+  .option('--axes <axes>', 'Comma-separated classifier axes for this run (e.g. shared-chokepoint) — composition input (HC-COMM-010 C0)')
   .option('--approve <step>', 'Approve a paused gate (e.g., --approve step_0)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .option('--poll-interval <s>', 'Poll interval in seconds', '5')
@@ -5823,6 +5895,48 @@ program
       orchestrateConfig.ci_local_command = 'make ci';
     }
 
+    // HC-COMM-010 B0.5 (memo §12 A3): stamp execution.mode into the run config
+    // at CREATION — the server reads it from run.config, making the mode
+    // immutable per run (a mid-flight .pipeline-config.yml flip cannot change
+    // a running run). Absent/old CLIs → the server defaults to 'server'.
+    // Inert until B1: the server ignores the key today.
+    try {
+      const { readExecutionMode, EDITOR_MODE_CONSENT_NOTE } = require('./lib/pipeline-config');
+      const executionMode = readExecutionMode(process.cwd());
+      orchestrateConfig.execution_mode = executionMode;
+      if (executionMode === 'editor') {
+        // §2a: the consent note is shown at the moment editor mode is USED.
+        console.log(`  → execution mode: editor (opt-in)`);
+        console.log(`     ${EDITOR_MODE_CONSENT_NOTE}`);
+      }
+    } catch (e) {
+      const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+      console.warn(`  ⚠ execution mode read failed (non-fatal, defaulting to server): ${msg}`);
+      orchestrateConfig.execution_mode = 'server';
+    }
+
+    // HC-COMM-010 C0: composition transports — INERT until C1 reads them.
+    // Overlays: .hone-local/ is adopter disk the server can never read
+    // (the cross-validation finding), so raw texts travel in run config —
+    // the codebaseFiles pattern, size/count-capped, degrade-to-empty.
+    // Axes: explicit --axes flag for now; automated wiring from classify
+    // runs is future work (documented in the sprint plan).
+    try {
+      const { readRuleOverlays } = require('./lib/overlay-transport');
+      const ov = readRuleOverlays(process.cwd());
+      if (ov.overlays.length > 0) {
+        orchestrateConfig.rule_overlays = ov.overlays;
+        console.log(`  → bundled ${ov.overlays.length} rule overlay(s) for server-side composition`);
+      }
+      for (const skip of ov.skipped) console.warn(`  ⚠ overlay skipped: ${skip}`);
+    } catch (e) {
+      console.warn(`  ⚠ overlay read failed (non-fatal): ${(e && e.message || String(e)).split('\n')[0]}`);
+    }
+    if (opts.axes) {
+      const axes = String(opts.axes).split(',').map(a => a.trim().toLowerCase()).filter(Boolean);
+      if (axes.length > 0) orchestrateConfig.classifier_axes = axes;
+    }
+
     // HC-019n-followup-28: resolve the E2E spec-generation mode (step_3b /
     // Playwright). Precedence mirrors ci.gate: per-run flag > .pipeline-config.yml
     // `e2e.spec_generation` > default `auto`. `auto` = the orchestrator runs

package/lib/editor-stub.js

@@ -0,0 +1,44 @@
+'use strict';
+/**
+ * editor-stub.js — HC-COMM-010 P3: thin-stub content for editor-side agents.
+ *
+ * When a repo opts into `execution.mode: editor`, the agents of the server's
+ * EDITOR_SIDE_STEPS are DELIVERED AT RUNTIME (ephemeral, via
+ * `hone step-instruction` / the hone_step_instruction MCP tool) — so `hone
+ * sync` ships a stub instead of persisting the full prompt to disk. This
+ * closes the dominant prompt-exposure leak for editor-mode repos (memo §5 /
+ * analysis G1) WITHOUT touching server-mode repos, whose adopters use the
+ * full synced prompts for daily editor-chat work.
+ *
+ * EDITOR_STUBBED_AGENTS must stay equal to the agents of the server's
+ * EDITOR_SIDE_STEPS (orchestrator.js) — pinned by a regression test that
+ * derives the truth from workflow-dag, since the two packages share no lib.
+ */
+
+const EDITOR_STUBBED_AGENTS = Object.freeze(['code-builder']);
+
+function isEditorStubbedAgent(agent, executionMode) {
+  return executionMode === 'editor' && EDITOR_STUBBED_AGENTS.includes(agent);
+}
+
+function editorStubContent(agent) {
+  return [
+    `# ${agent} — served at runtime by Hone (editor mode)`,
+    '',
+    'This repo runs with `execution.mode: editor`, so this agent\'s pipeline',
+    'instruction is COMPOSED SERVER-SIDE and delivered ephemerally at',
+    'invocation time — it is not stored on disk.',
+    '',
+    'To execute a parked step:',
+    '  1. `hone step-instruction <runId>`   (or the hone_step_instruction MCP tool)',
+    '  2. run the returned instruction in your editor',
+    '  3. `hone submit-step <runId> <stepKey> --file <output>`',
+    '',
+    'Output is judged by real verification (check-patch / verify-patch),',
+    'never taken on trust. Switch `execution.mode` back to `server` and',
+    're-run `hone sync` to restore the full local prompt.',
+    '',
+  ].join('\n');
+}
+
+module.exports = { EDITOR_STUBBED_AGENTS, isEditorStubbedAgent, editorStubContent };

package/lib/mcp-tools.js

@@ -131,6 +131,58 @@ async function killWorkflow({ runId, cwd } = {}) {
   };
 }
 
+// hone_step_instruction — fetch the editor-mode instruction for an
+// awaiting_editor run (HC-COMM-010 B3). THE ephemeral delivery: the composed
+// instruction lands in the editor's context via this tool result and is never
+// written to disk by any Hone code.
+async function stepInstruction({ runId, cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  const r = await runHone(['step-instruction', String(runId), '--format', 'json'], { cwd });
+  if (r.error) return { isError: true, detail: r.error };
+  const data = parseLastJson(r.stdout);
+  return {
+    isError: !data,
+    instruction: data ? data.instruction : null,
+    stepKey: data ? data.stepKey : null,
+    contractVersion: data ? data.contractVersion : null,
+    exitCode: r.exitCode,
+    detail: data
+      ? `instruction for ${data.stepKey} (contract ${data.contractVersion}) — execute it and call hone_submit_step with the complete output`
+      : (r.stderr || r.stdout || 'could not fetch instruction').slice(0, 500),
+  };
+}
+
+// hone_submit_step — submit editor-executed output (HC-COMM-010 B3). Output
+// travels via a temp file (1MB-class payloads must not ride argv); the file
+// is best-effort deleted after the shell-out.
+async function submitStep({ runId, stepKey, output, contractVersion = '1', cwd } = {}) {
+  if (!runId) return { isError: true, detail: 'runId is required' };
+  if (!stepKey) return { isError: true, detail: 'stepKey is required' };
+  if (typeof output !== 'string' || output.trim() === '') {
+    return { isError: true, detail: 'output is required (the complete step output text)' };
+  }
+  const tmp = path.join(os.tmpdir(), `hone-editor-output-${Date.now()}-${process.pid}.txt`);
+  try {
+    fsSync.writeFileSync(tmp, output, 'utf8');
+    const r = await runHone(
+      ['submit-step', String(runId), String(stepKey), '--file', tmp, '--contract', String(contractVersion), '--format', 'json'],
+      { cwd });
+    if (r.error) return { isError: true, detail: r.error };
+    const data = parseLastJson(r.stdout);
+    return {
+      isError: !r.ok,
+      submitted: r.ok,
+      gateResult: data ? data.gateResult : null,
+      exitCode: r.exitCode,
+      detail: data
+        ? `step ${data.stepKey} completed (executed_by: ${data.executedBy}); human gate is next`
+        : (r.stderr || r.stdout || 'submission failed').slice(0, 500),
+    };
+  } finally {
+    try { fsSync.unlinkSync(tmp); } catch { /* best-effort cleanup */ }
+  }
+}
+
 // hone_status — read run status (readOnly). GET /orchestrate/:id.
 async function status({ runId, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
@@ -343,6 +395,29 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: { runId: { type: 'string' } }, required: ['runId'] },
     handler: killWorkflow,
   },
+  {
+    name: 'hone_step_instruction',
+    description: 'Fetch the editor-mode instruction for a Hone run that is awaiting the editor (execution.mode: editor). Read-only. Execute the returned instruction in THIS session, then call hone_submit_step with the complete output.',
+    readOnly: true,
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } }, required: ['runId'] },
+    handler: stepInstruction,
+  },
+  {
+    name: 'hone_submit_step',
+    description: "Submit the editor-executed output for a Hone step that was fetched via hone_step_instruction. The output enters Hone's NORMAL gate + verification flow (judged by real test execution, not trust).",
+    readOnly: false,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        runId: { type: 'string' },
+        stepKey: { type: 'string' },
+        output: { type: 'string' },
+        contractVersion: { type: 'string', default: '1' },
+      },
+      required: ['runId', 'stepKey', 'output'],
+    },
+    handler: submitStep,
+  },
   {
     name: 'hone_doctor',
     description: 'Self-check the Hone setup (read-only): is a token configured, and is the `hone` CLI installed + reachable? Run this first if other tools fail.',
@@ -353,6 +428,8 @@ const TOOLS = [
 ];
 
 module.exports = {
+  stepInstruction,
+  submitStep,
   listWorkflows,
   killWorkflow,
   runStory, status, verifyPatch, checkPatch, showStep, approve, emitPr, verifyPr, agentEval, derive, sync, doctor,

package/lib/overlay-transport.js

@@ -0,0 +1,40 @@
+'use strict';
+/**
+ * overlay-transport.js — HC-COMM-010 C0: read adopter rule-overlays for
+ * transport to the server at run creation.
+ *
+ * `.hone-local/rule-overlays/*.md` lives on ADOPTER DISK — the server can
+ * never read it (the cross-validation finding that refuted "merge overlays
+ * server-side" as originally sketched). So the CLI bundles the raw overlay
+ * texts into orchestrateConfig, exactly the codebaseFiles/§12-A3 transport
+ * pattern. Parsing (front-matter, insertion targets) happens SERVER-side in
+ * C1 via the mergeOverlays machinery — this reader stays deliberately dumb:
+ * raw {name, content} pairs, size/count-capped, degrade-to-empty on every
+ * failure path.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_MAX_FILES = 10;
+const DEFAULT_MAX_TOTAL_BYTES = 50_000; // mirrors the codebaseFiles budget
+
+function readRuleOverlays(repoRoot, { maxFiles = DEFAULT_MAX_FILES, maxTotalBytes = DEFAULT_MAX_TOTAL_BYTES } = {}) {
+  const result = { overlays: [], skipped: [] };
+  if (!repoRoot || typeof repoRoot !== 'string') return result;
+  const dir = path.join(repoRoot, '.hone-local', 'rule-overlays');
+  let names;
+  try { names = fs.readdirSync(dir).filter(n => n.endsWith('.md')).sort(); } catch { return result; }
+  let total = 0;
+  for (const name of names) {
+    if (result.overlays.length >= maxFiles) { result.skipped.push(`${name} (file cap ${maxFiles})`); continue; }
+    let content;
+    try { content = fs.readFileSync(path.join(dir, name), 'utf8'); } catch { result.skipped.push(`${name} (unreadable)`); continue; }
+    const bytes = Buffer.byteLength(content, 'utf8');
+    if (total + bytes > maxTotalBytes) { result.skipped.push(`${name} (byte budget ${maxTotalBytes})`); continue; }
+    total += bytes;
+    result.overlays.push({ name, content });
+  }
+  return result;
+}
+
+module.exports = { readRuleOverlays, DEFAULT_MAX_FILES, DEFAULT_MAX_TOTAL_BYTES };

package/lib/pipeline-config.js

@@ -205,6 +205,63 @@ function readE2eSpecMode(repoRoot) {
   return DEFAULT_E2E_SPEC_MODE;
 }
 
+// ── HC-COMM-010 (Track B / B0): execution mode ────────────────────────────────
+// Which side EXECUTES the generation steps:
+//   server (default) → the Hone server runs every agent (BYO key / metered);
+//   editor           → (feature ships with B1-B4) generation steps run in the
+//                      adopter's editor AI via ephemeral server-composed
+//                      instructions. The knob is reserved NOW (memo §2a) so
+//                      adopters never migrate config to get editor mode later.
+// Default-safe: missing/malformed → 'server'.
+const EXECUTION_MODES = ['server', 'editor'];
+const DEFAULT_EXECUTION_MODE = 'server';
+
+// Memo §2a consent note — shown verbatim whenever `editor` is selected.
+// Neutral own-use consent; supports but does not replace the ToS position.
+const EDITOR_MODE_CONSENT_NOTE =
+  'Editor mode runs pipeline steps in your own editor AI on whatever plan ' +
+  "you've authorized there. By enabling it you confirm you are using your own " +
+  'authorized plan for your own development work, and that you are responsible ' +
+  'for ensuring your plan and usage comply with your agreement with your AI ' +
+  'provider. Hone does not select or provision your plan.';
+
+/** Normalize an execution.mode value, defaulting to server. */
+function normalizeExecutionMode(v) {
+  const s = String(v == null ? '' : v).toLowerCase().trim();
+  return EXECUTION_MODES.includes(s) ? s : DEFAULT_EXECUTION_MODE;
+}
+
+/**
+ * Read execution.mode from .pipeline-config.yml's `execution:` block.
+ * Same candidate order + graceful degradation as readE2eSpecMode.
+ *
+ * @param {string} repoRoot
+ * @returns {'server'|'editor'} default 'server' when config is missing/malformed.
+ */
+function readExecutionMode(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return DEFAULT_EXECUTION_MODE;
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.execution;
+    if (!block || typeof block !== 'object') continue;
+    if (block.mode === undefined) continue;
+    return normalizeExecutionMode(block.mode);
+  }
+  return DEFAULT_EXECUTION_MODE;
+}
+
 // ── HC-019n-followup-34: closed-loop verification gate ────────────────────────
 // The CLI verbs (verify-patch/verify-pr) EXECUTE and report a verdict to the
 // server. `verification.gate` controls what the server does with it:
@@ -360,6 +417,11 @@ function readAgentEvalConfig(repoRoot) {
 }
 
 module.exports = {
+  EXECUTION_MODES,
+  DEFAULT_EXECUTION_MODE,
+  EDITOR_MODE_CONSENT_NOTE,
+  normalizeExecutionMode,
+  readExecutionMode,
   readStoryClassifierConfig,
   KNOWN_THRESHOLD_KEYS,
   readCIGateConfig,

package/package.json

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