@logicseek/hello-cc 0.1.3 → 0.1.4

package/lib/guidance.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function guidanceMarkdown() {
+  return `# hello-cc Coordination Rules
+
+This project may be edited by multiple Claude Code and Codex CLI sessions.
+
+Use \`hcc\` as the source of truth for cross-session coordination. If the user
+asks what other sessions are doing, do not answer from generic model knowledge.
+Run the project-local commands below and summarize the result.
+
+Each terminal session must use a stable peer id, for example codex-a,
+codex-b, claude-a, claude-b, or gpu-runner-a.
+
+Status checks:
+- \`hcc peers\` shows known Claude/Codex/shell sessions.
+- \`hcc task list\` shows all open tasks. Tasks stay visible until \`done\` or
+  \`abandoned\`; they are not read/unread items.
+- \`hcc msg inbox\` shows unread messages for this session.
+- \`hcc lock list\` shows active advisory locks.
+- \`hcc status\` summarizes peers, tasks, locks, inbox, and recent events.
+- \`hcc team status --task N\` summarizes explicit subtasks for a parent task.
+
+Read-only work:
+- Reading files, searching, inspecting \`git diff\` / \`git status\`, reviewing
+  uncommitted changes, and running non-mutating checks such as \`node --check\`
+  do not require locks.
+- For read-only review, do not acquire file locks. If another live peer already
+  holds write locks on changed files, report that the review is only a current
+  snapshot and not a final commit-ready verdict.
+- Use tasks, messages, events, or handoffs to make read-only review visible;
+  do not use advisory locks to reserve files you are only reading.
+
+Review and monitoring:
+- Reviewing another peer's work is a read-only activity. You may inspect current
+  diffs, task state, messages, handoffs, and non-mutating checks while that peer
+  keeps its write locks.
+- If you find a concrete issue in another peer's task, proactively send that
+  peer an \`hcc msg\` with the task id, affected file or behavior, why it is a
+  problem, and a suggested fix or verification step.
+- Continue monitoring until the peer fixes the issue, records a follow-up task,
+  or hands off. Do not silently treat a snapshot review as final approval.
+
+Before mutating work:
+- Register with hcc.
+- Read current status with \`hcc status\`, \`hcc state\`, \`hcc task list\`, and \`hcc msg inbox\`.
+- If \`hcc state\` shows a current task for this peer, continue that task until
+  handoff, done, or blocked instead of claiming a new task.
+- Claim one task before editing or mutating shared state when this peer has no
+  current task.
+- If work needs multiple peers, use \`hcc team plan\` and \`hcc team start\`
+  explicitly; do not create or claim hidden extra tasks.
+
+Before editing or mutating shared resources:
+- Acquire an advisory lock for the file, directory, module, or shared resource.
+- If another live peer holds the lock, message that peer instead of editing.
+- Acquire locks only before writes or shared-resource mutation, including file
+  edits, formatting, staging/committing through \`.git/index\`, intentional DB
+  data/schema changes, starting/stopping/restarting shared runtimes, or taking
+  over tmux/session/port resources.
+- Commit-readiness checks are read-only until staging begins. Do not lock source
+  files for review. Before committing, ensure no live peer holds write locks on
+  the files to be committed, then lock \`.git/index\` only while staging and
+  committing.
+
+During work:
+- Keep changes scoped to the claimed task.
+- Send progress messages when another session needs context.
+
+Before stopping:
+- Mark the task done or blocked.
+- Create a handoff with changed files, tests, and remaining risks.
+- Release locks you no longer need.
+`;
+}
+
+export function writeGuidance(root) {
+  const guidePath = path.join(root, '.hello-cc', 'HCC.md');
+  fs.mkdirSync(path.dirname(guidePath), { recursive: true });
+  const content = guidanceMarkdown();
+  fs.writeFileSync(guidePath, content);
+  const clause = `\n<!-- hello-cc:start -->\n\n${content}\n<!-- hello-cc:end -->\n`;
+  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+    const target = path.join(root, file);
+    if (!fs.existsSync(target)) {
+      fs.writeFileSync(target, clause.trimStart());
+      continue;
+    }
+    const existing = fs.readFileSync(target, 'utf8');
+    const updated = existing.includes('<!-- hello-cc:start -->')
+      ? existing.replace(/<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->/, clause.trim())
+      : `${existing.trimEnd()}\n${clause}`;
+    fs.writeFileSync(target, updated);
+  }
+  return guidePath;
+}
+
+export function removeGuidanceBlocks(root) {
+  const changed = [];
+  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+    const target = path.join(root, file);
+    if (!fs.existsSync(target)) continue;
+    const existing = fs.readFileSync(target, 'utf8');
+    const updated = existing
+      .replace(/\n?<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->\n?/g, '\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd();
+    if (updated !== existing) {
+      fs.writeFileSync(target, updated ? `${updated}\n` : '');
+      changed.push(target);
+    }
+  }
+  return changed;
+}

package/lib/package-meta.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function packageRoot(fromUrl = import.meta.url) {
+  return path.resolve(fileURLToPath(fromUrl), '..', '..');
+}
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function readPackageJson(root) {
+  return readJson(path.join(root, 'package.json'));
+}
+
+export function readPackageMeta(root) {
+  const pkg = readPackageJson(root);
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    packageJson: pkg
+  };
+}

package/lib/release-notes.mjs

@@ -0,0 +1,40 @@
+export function normalizeVersion(version) {
+  return String(version || '').replace(/^v/, '');
+}
+
+export function releaseSection(markdown, version) {
+  const lines = markdown.split(/\r?\n/);
+  const heading = `## ${version}`;
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').trimEnd();
+}
+
+export function validateReleaseSection(section, version) {
+  const problems = [];
+  if (!section) {
+    problems.push(`CHANGELOG.md is missing section ## ${version}`);
+    return problems;
+  }
+  if (!section.includes('### Summary')) problems.push(`## ${version} is missing ### Summary`);
+  if (!section.includes('### Highlights')) problems.push(`## ${version} is missing ### Highlights`);
+  if (section.includes('TODO') || section.includes('TBD')) problems.push(`## ${version} still contains TODO/TBD text`);
+  const bulletCount = (section.match(/^- /gm) || []).length;
+  if (bulletCount < 2) problems.push(`## ${version} should include at least two release-note bullets`);
+  return problems;
+}
+
+export function repoFromPackage(pkg) {
+  const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+  if (!repo) return null;
+  const match = repo.match(/github\.com[:/](.+?\/.+?)(?:\.git)?$/);
+  return match ? match[1] : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {

package/scripts/github-release.mjs

@@ -3,8 +3,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-
-const repoRoot = path.resolve(import.meta.dirname, '..');
+import { packageRoot, readPackageJson } from '../lib/package-meta.mjs';
+import {
+  normalizeVersion,
+  releaseSection,
+  repoFromPackage,
+  validateReleaseSection
+} from '../lib/release-notes.mjs';
+
+const repoRoot = packageRoot(import.meta.url);
 const githubApi = 'https://api.github.com';
 
 function usage() {
@@ -21,10 +28,6 @@ Authentication:
 `);
 }
 
-function readJson(file) {
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
-}
-
 function parseArgs(argv) {
   const opts = { dryRun: false, help: false, repo: null, version: null };
   for (let i = 0; i < argv.length; i += 1) {
@@ -50,47 +53,6 @@ function parseArgs(argv) {
   return opts;
 }
 
-function normalizeVersion(version) {
-  return String(version || '').replace(/^v/, '');
-}
-
-function releaseSection(markdown, version) {
-  const lines = markdown.split(/\r?\n/);
-  const heading = `## ${version}`;
-  const start = lines.findIndex((line) => line.trim() === heading);
-  if (start < 0) return null;
-
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i += 1) {
-    if (/^##\s+/.test(lines[i])) {
-      end = i;
-      break;
-    }
-  }
-  return lines.slice(start, end).join('\n').trimEnd();
-}
-
-function validateSection(section, version) {
-  const problems = [];
-  if (!section) {
-    problems.push(`CHANGELOG.md is missing section ## ${version}`);
-    return problems;
-  }
-  if (!section.includes('### Summary')) problems.push(`## ${version} is missing ### Summary`);
-  if (!section.includes('### Highlights')) problems.push(`## ${version} is missing ### Highlights`);
-  if (section.includes('TODO') || section.includes('TBD')) problems.push(`## ${version} still contains TODO/TBD text`);
-  const bulletCount = (section.match(/^- /gm) || []).length;
-  if (bulletCount < 2) problems.push(`## ${version} should include at least two release-note bullets`);
-  return problems;
-}
-
-function repoFromPackage(pkg) {
-  const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
-  if (!repo) return null;
-  const match = repo.match(/github\.com[:/](.+?\/.+?)(?:\.git)?$/);
-  return match ? match[1] : null;
-}
-
 function envToken() {
   return process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '';
 }
@@ -124,7 +86,7 @@ async function main() {
     return;
   }
 
-  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const pkg = readPackageJson(repoRoot);
   const version = normalizeVersion(opts.version || pkg.version);
   const tag = `v${version}`;
   const repo = opts.repo || process.env.GITHUB_REPOSITORY || repoFromPackage(pkg);
@@ -132,7 +94,7 @@ async function main() {
 
   const changelog = fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
   const body = releaseSection(changelog, version);
-  const problems = validateSection(body, version);
+  const problems = validateReleaseSection(body, version);
   if (problems.length) {
     console.error(problems.join('\n'));
     process.exitCode = 1;

package/scripts/regression.mjs

@@ -809,6 +809,39 @@ async function expectResizeReplaceSnapshot(peer, marker) {
   });
 }
 
+async function expectWebSocketInputVisible(peer, marker) {
+  await new Promise((resolve, reject) => {
+    let sawSnapshot = false;
+    let sent = false;
+    let sawMarkerAfterInput = false;
+    let sawFrameAfterInput = false;
+    const ws = new WebSocket(runtimeWsUrl(peer));
+    const timer = setTimeout(() => reject(new Error(`${peer} websocket input visibility timeout`)), 5000);
+    ws.on('message', (raw) => {
+      const msg = JSON.parse(String(raw));
+      const data = String(msg.data || '');
+      if (msg.type === 'snapshot') {
+        sawSnapshot = true;
+        if (!sent) {
+          sent = true;
+          ws.send(JSON.stringify({ type: 'input', data: `echo ${marker}\r` }));
+        }
+        return;
+      }
+      if (sent && ['data', 'replace'].includes(msg.type)) {
+        sawFrameAfterInput = true;
+        if (data.includes(marker)) sawMarkerAfterInput = true;
+      }
+      if (sawSnapshot && sawFrameAfterInput && sawMarkerAfterInput) {
+        clearTimeout(timer);
+        ws.close();
+        resolve();
+      }
+    });
+    ws.on('error', reject);
+  });
+}
+
 function tmuxStreamNodes() {
   const dir = path.join(root, '.hello-cc', 'bufs');
   if (!fs.existsSync(dir)) return [];
@@ -1436,13 +1469,56 @@ async function multiProjectWebWorkflow() {
   ]) {
     if (!html.includes(expected)) fail(`web layout missing resizable sidebar support: ${expected}`);
   }
-  if (!html.includes('state-card') || !html.includes('peerStateView') || !html.includes('savedCardScroll') || !html.includes('lastStateRoot') || !html.includes('data-section="peers"')) {
+  if (!html.includes('state-card') || !html.includes('peerStateView') || !html.includes('savedCardScroll') || !html.includes('lastStateRoot') || !html.includes("stateCardHtml('peers'")) {
     fail('web state panel missing scrollable peer state UI');
   }
-  if (!html.includes('data-section="timeline"') || !html.includes('renderTimelineItem') || !html.includes('bodyPinned') || !html.includes('refreshCurrentState')) {
+  for (const expected of [
+    'function stateCardCollapsed(section)',
+    "localStorage.getItem('hcc.stateCard.' + section + '.collapsed')",
+    'function stateCardHtml(section, title, count, bodyHtml)',
+    'state-card-toggle',
+    'aria-expanded=',
+    'state-card-collapsed',
+    'function bindStateCardToggles()',
+    "localStorage.setItem('hcc.stateCard.' + section + '.collapsed'",
+    "stateCardHtml('automation'",
+    "stateCardHtml('timeline'",
+    "stateCardHtml('messages'",
+    "stateCardHtml('peers'",
+    "stateCardHtml('tasks'",
+    "stateCardHtml('locks'",
+    'bindStateCardToggles();'
+  ]) {
+    if (!html.includes(expected)) fail(`web state panel missing collapsible card support: ${expected}`);
+  }
+  for (const expected of [
+    'id="actionResult"',
+    'data-action="state"',
+    'data-action="status"',
+    'data-action="inbox"',
+    'data-action="task-next"',
+    'data-action="heartbeat"',
+    'data-action="register"',
+    'data-terminal-action="status"',
+    'function runPeerAction(action)',
+    "'/api/peers/' + encodeURIComponent(info.peerId) + '/actions/' + encodeURIComponent(action)",
+    'showActionResult(result)'
+  ]) {
+    if (!html.includes(expected)) fail(`web actions missing API result UI: ${expected}`);
+  }
+  if (html.includes('data-send=') || html.includes("document.querySelectorAll('[data-send]')")) {
+    fail('web actions still use implicit terminal command injection');
+  }
+  for (const expected of [
+    'term.onData((data) => {',
+    "ws.send(JSON.stringify({ type: 'input', data }))"
+  ]) {
+    if (!html.includes(expected)) fail(`web terminal input forwarding missing: ${expected}`);
+  }
+  if (!html.includes("stateCardHtml('timeline'") || !html.includes('renderTimelineItem') || !html.includes('bodyPinned') || !html.includes('refreshCurrentState')) {
     fail('web state panel missing collaboration timeline or refresh routing');
   }
-  if (!html.includes('data-section="messages"') || !html.includes('messagesData.length')) {
+  if (!html.includes("stateCardHtml('messages'") || !html.includes('messagesData.length')) {
     fail('web state panel missing dedicated messages card');
   }
 
@@ -1463,6 +1539,40 @@ async function multiProjectWebWorkflow() {
     fail(`second project API did not see its session:\n${JSON.stringify(otherSessions)}`);
   }
 
+  hcc(['register', '--peer', 'web-action-peer', '--kind', 'codex', '--role', 'peer']);
+  hcc(['msg', 'send', '--from', 'human', '--to', 'web-action-peer', '--body', 'web action inbox ok']);
+  const actionStatus = await (await runtimeFetch('/api/peers/web-action-peer/actions/status', {}, { root })).json();
+  if (!actionStatus.ok || actionStatus.action !== 'status' || actionStatus.peer !== 'web-action-peer' || !actionStatus.data || typeof actionStatus.data.unread !== 'number') {
+    fail(`web status action did not return structured status:\n${JSON.stringify(actionStatus, null, 2)}`);
+  }
+  const actionInbox = await (await runtimeFetch('/api/peers/web-action-peer/actions/inbox', {}, { root })).json();
+  if (!actionInbox.ok || actionInbox.action !== 'inbox' || !(actionInbox.data?.messages || []).some((m) => m.body === 'web action inbox ok')) {
+    fail(`web inbox action did not return unread messages:\n${JSON.stringify(actionInbox, null, 2)}`);
+  }
+  const actionState = await (await runtimeFetch('/api/peers/web-action-peer/actions/state', {}, { root })).json();
+  if (!actionState.ok || actionState.action !== 'state' || actionState.data?.automation?.peer?.id !== 'web-action-peer') {
+    fail(`web state action did not return peer automation:\n${JSON.stringify(actionState, null, 2)}`);
+  }
+  const taskOutput = hcc(['task', 'create', '--title', 'web action task', '--body', 'claim through web action']);
+  const taskMatch = taskOutput.match(/created task #(\d+):/);
+  if (!taskMatch) fail(`cannot parse web action task id:\n${taskOutput}`);
+  const actionNext = await (await runtimeFetch('/api/peers/web-action-peer/actions/task-next', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: '{}'
+  }, { root })).json();
+  if (!actionNext.ok || actionNext.action !== 'task-next' || String(actionNext.data?.task?.id) !== taskMatch[1]) {
+    fail(`web task-next action did not claim pending task #${taskMatch[1]}:\n${JSON.stringify(actionNext, null, 2)}`);
+  }
+  const actionHeartbeat = await (await runtimeFetch('/api/peers/web-action-peer/actions/heartbeat', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ renew_locks: true })
+  }, { root })).json();
+  if (!actionHeartbeat.ok || actionHeartbeat.action !== 'heartbeat' || actionHeartbeat.data?.peer !== 'web-action-peer') {
+    fail(`web heartbeat action did not return structured result:\n${JSON.stringify(actionHeartbeat, null, 2)}`);
+  }
+
   const startProvider = async (payload) => {
     const response = await runtimeFetch('/api/sessions', {
       method: 'POST',
@@ -1599,6 +1709,7 @@ async function tmuxBackedStartWorkflow() {
   await waitForFile(file, 'PTY_OK', 'pty injection');
   await expectWebSocketMarker('shell-a', 'WS_PTY_OK');
   await expectResizeReplaceSnapshot('shell-a', 'WS_RESIZE_OK');
+  await expectWebSocketInputVisible('shell-a', 'WS_INPUT_VISIBLE_OK');
   await expectBoundedTmuxStream('tmux-backed FIFO stream');
 
   await stopRuntime();
@@ -1845,17 +1956,31 @@ async function downGcPackWorkflow() {
   hcc(['gc', '--older-than', '0', '--yes']);
   const pack = JSON.parse(run('npm', ['pack', '--dry-run', '--json']));
   const files = new Set(pack[0]?.files?.map((entry) => entry.path) || []);
-  for (const file of ['assets/logo.svg', 'CHANGELOG.md', 'docs/commands.md', 'docs/commands.zh-CN.md', 'scripts/github-release.mjs']) {
+  for (const file of [
+    'assets/logo.svg',
+    'CHANGELOG.md',
+    'docs/commands.md',
+    'docs/commands.zh-CN.md',
+    'lib/guidance.mjs',
+    'lib/package-meta.mjs',
+    'lib/release-notes.mjs',
+    'scripts/github-release.mjs'
+  ]) {
     if (!files.has(file)) fail(`npm package missing ${file}`);
   }
+  const packageVersion = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).version;
   const releaseCheck = run('npm', ['run', 'release:check']);
-  if (!releaseCheck.includes('release notes ok: 0.1.3')) fail(`release check output wrong:\n${releaseCheck}`);
+  if (!releaseCheck.includes(`release notes ok: ${packageVersion}`)) fail(`release check output wrong:\n${releaseCheck}`);
   const releaseNotes = run('npm', ['run', 'release:notes']);
-  if (!releaseNotes.includes('## 0.1.3') || !releaseNotes.includes('### Summary')) {
+  if (!releaseNotes.includes(`## ${packageVersion}`) || !releaseNotes.includes('### Summary')) {
     fail(`release notes output wrong:\n${releaseNotes}`);
   }
-  const githubRelease = JSON.parse(run(process.execPath, [path.join(repoRoot, 'scripts', 'github-release.mjs'), '--dry-run', '--version', '0.1.3']));
-  if (!githubRelease.ok || !githubRelease.dry_run || githubRelease.repo !== 'Dullne/hello-cc' || githubRelease.tag !== 'v0.1.3' || githubRelease.body_length < 100) {
+  const releaseNotesWithV = run(process.execPath, [path.join(repoRoot, 'scripts', 'release-notes.mjs'), '--version', `v${packageVersion}`]);
+  if (!releaseNotesWithV.includes(`## ${packageVersion}`) || releaseNotesWithV.includes(`## v${packageVersion}`)) {
+    fail(`release notes v-prefixed version output wrong:\n${releaseNotesWithV}`);
+  }
+  const githubRelease = JSON.parse(run(process.execPath, [path.join(repoRoot, 'scripts', 'github-release.mjs'), '--dry-run', '--version', packageVersion]));
+  if (!githubRelease.ok || !githubRelease.dry_run || githubRelease.repo !== 'Dullne/hello-cc' || githubRelease.tag !== `v${packageVersion}` || githubRelease.body_length < 100) {
     fail(`github release dry run output wrong:\n${JSON.stringify(githubRelease, null, 2)}`);
   }
   const docsIndex = fs.readFileSync(path.join(repoRoot, 'docs', 'README.md'), 'utf8');
@@ -1910,6 +2035,41 @@ function syntaxAndHelp() {
   run(process.execPath, ['--check', path.join(repoRoot, 'bin', 'hcc.mjs')]);
   run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'setup.mjs')]);
   run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'discover.mjs')]);
+  run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'guidance.mjs')]);
+  run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'package-meta.mjs')]);
+  run(process.execPath, ['--check', path.join(repoRoot, 'lib', 'release-notes.mjs')]);
+  const hccSource = fs.readFileSync(hccBin, 'utf8');
+  for (const expected of [
+    'function scheduleTmuxInputRefresh(session)',
+    "runTmux(['pipe-pane', '-t', session.pane]);",
+    'if (session.inputRefreshTimer) return;',
+    'session.inputRefreshTimer = setTimeout',
+    'scheduleTmuxInputRefresh(session)',
+    "if (session.inputRefreshTimer) { clearTimeout(session.inputRefreshTimer); session.inputRefreshTimer = null; }",
+    "broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });"
+  ]) {
+    if (!hccSource.includes(expected)) fail(`web terminal input refresh support missing: ${expected}`);
+  }
+  for (const expected of [
+    'function webPeerAction(projectCtx, peer, action, input = {})',
+    'function claimNextTaskForPeer(db, peer, force = false)',
+    'function statusSummary(ctx, peer = null, identity = null)',
+    'const peerActionMatch = url.pathname.match(/^\\/api\\/peers\\/([^/]+)\\/actions\\/([^/]+)$/)',
+    "const readOnly = ['status', 'state', 'inbox'].includes(action)",
+    "sendJson(res, 200, webPeerAction(reqCtx, peer, action, input));"
+  ]) {
+    if (!hccSource.includes(expected)) fail(`web peer action API support missing: ${expected}`);
+  }
+  const packageVersion = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).version;
+  const cliVersion = run(process.execPath, [hccBin, '--version']).trim();
+  if (cliVersion !== packageVersion) {
+    fail(`CLI version ${cliVersion} does not match package.json ${packageVersion}`);
+  }
+  if (!hccSource.includes("import { readPackageMeta } from '../lib/package-meta.mjs'") ||
+      !hccSource.includes('const VERSION = PACKAGE_META.version') ||
+      !hccSource.includes('writeGuidanceForRoot(ctx.root)')) {
+    fail('CLI still has duplicated package metadata or guidance wiring');
+  }
   const mainHelp = run(process.execPath, [hccBin, '--help']);
   if (mainHelp.includes('setup') || mainHelp.includes('--web-managed')) {
     fail(`public help exposes maintenance or removed commands:\n${mainHelp}`);

package/scripts/release-notes.mjs

@@ -3,8 +3,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { packageRoot, readPackageJson } from '../lib/package-meta.mjs';
+import { normalizeVersion, releaseSection, validateReleaseSection } from '../lib/release-notes.mjs';
 
-const repoRoot = path.resolve(import.meta.dirname, '..');
+const repoRoot = packageRoot(import.meta.url);
 
 function usage() {
   console.log(`release-notes
@@ -24,10 +26,6 @@ package release descriptions.
 `);
 }
 
-function readJson(file) {
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
-}
-
 function parseArgs(argv) {
   const opts = { check: false, help: false, version: null };
   for (let i = 0; i < argv.length; i += 1) {
@@ -48,36 +46,6 @@ function parseArgs(argv) {
   return opts;
 }
 
-function releaseSection(markdown, version) {
-  const lines = markdown.split(/\r?\n/);
-  const heading = `## ${version}`;
-  const start = lines.findIndex((line) => line.trim() === heading);
-  if (start < 0) return null;
-
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i += 1) {
-    if (/^##\s+/.test(lines[i])) {
-      end = i;
-      break;
-    }
-  }
-  return lines.slice(start, end).join('\n').trimEnd();
-}
-
-function validateSection(section, version) {
-  const problems = [];
-  if (!section) {
-    problems.push(`CHANGELOG.md is missing section ## ${version}`);
-    return problems;
-  }
-  if (!section.includes('### Summary')) problems.push(`## ${version} is missing ### Summary`);
-  if (!section.includes('### Highlights')) problems.push(`## ${version} is missing ### Highlights`);
-  if (section.includes('TODO') || section.includes('TBD')) problems.push(`## ${version} still contains TODO/TBD text`);
-  const bulletCount = (section.match(/^- /gm) || []).length;
-  if (bulletCount < 2) problems.push(`## ${version} should include at least two release-note bullets`);
-  return problems;
-}
-
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) {
@@ -85,11 +53,11 @@ function main() {
     return;
   }
 
-  const pkg = readJson(path.join(repoRoot, 'package.json'));
-  const version = opts.version || pkg.version;
+  const pkg = readPackageJson(repoRoot);
+  const version = normalizeVersion(opts.version || pkg.version);
   const changelog = fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
   const section = releaseSection(changelog, version);
-  const problems = validateSection(section, version);
+  const problems = validateReleaseSection(section, version);
 
   if (opts.check) {
     if (problems.length) {