@indigoai-us/hq-cli 5.81.0 → 5.82.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [5.82.0]
+
+### Added
+
+- `hq core checkpoint` reaches full `/checkpoint`-skill parity: new
+  `--insight`, `--commit`, `--initial-commit`, and `--worker*` options
+  (payload equivalents included), automatic caller-repo `remote_url`
+  capture, `commits_made` derivation from `--initial-commit`, and a
+  sibling prompt that executes the complete checkpoint flow — in-place
+  thread upgrade/rename, knowledge-repo scan, journal close, legacy
+  checkpoint, thread index refresh, document-release best-effort,
+  transcript-derived learnings — under explicit allow-list write
+  bounds. (#289)
+
 ## [5.81.0]
 
 ### Added

package/dist/commands/core-checkpoint.d.ts

@@ -11,7 +11,7 @@ import { Command } from "commander";
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.
  */
-export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, you may read\n   its tail for context (last ~200 lines); never quote secrets from it.\n2. Verify the checkpoint thread file named in the payload exists and is valid\n   JSON; repair or enrich it if needed (keep its shape).\n3. For each entry in \"learnings\": if it is a reusable rule, distill it into a\n   policy file under personal/policies/ (or companies/<company>/policies/ when\n   the payload names a company and the lesson is company-specific), following\n   core/knowledge/public/hq-core/policies-spec.md. Skip duplicates \u2014 search\n   existing policies first.\n4. For durable facts (not rules), update knowledge under personal/knowledge/\n   or companies/<company>/knowledge/.\n5. Hook or automation improvements go ONLY under personal/hooks/ as proposals.\n   You must never write into .claude/, core/, .agents/, .codex/, or repos/.\n6. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), what you skipped and why.\n7. If workspace/checkpoints/sibling/pending.jsonl is non-empty when you\n   finish, process those payloads the same way, then truncate the file.\n";
+export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   distill a non-duplicate policy file under personal/policies/ or, only when\n   the payload names a company and the rule is company-specific,\n   companies/<company>/policies/, following\n   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or\n   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md\n   when present, otherwise workspace/insights/. Durable facts (not rules) may\n   go under personal/knowledge/ or companies/<company>/knowledge/ only.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. If\n   workspace/checkpoints/sibling/pending.jsonl is non-empty when you finish,\n   process those payloads with this same flow, then truncate the file.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export declare function registerCoreCheckpointCommand(core: Command): void;

package/dist/commands/core-checkpoint.js

@@ -36,23 +36,47 @@ HQ install. Your parent session's state is in <payloadPath>. Work
 quietly and do not ask questions; if something is ambiguous, record it in the
 report instead of guessing.
 
-1. Read the payload. If it lists a transcript path that exists, you may read
-   its tail for context (last ~200 lines); never quote secrets from it.
-2. Verify the checkpoint thread file named in the payload exists and is valid
-   JSON; repair or enrich it if needed (keep its shape).
-3. For each entry in "learnings": if it is a reusable rule, distill it into a
-   policy file under personal/policies/ (or companies/<company>/policies/ when
-   the payload names a company and the lesson is company-specific), following
-   core/knowledge/public/hq-core/policies-spec.md. Skip duplicates — search
-   existing policies first.
-4. For durable facts (not rules), update knowledge under personal/knowledge/
-   or companies/<company>/knowledge/.
-5. Hook or automation improvements go ONLY under personal/hooks/ as proposals.
-   You must never write into .claude/, core/, .agents/, .codex/, or repos/.
-6. Write <runDir>/report.md — full prose: what you read, what you changed
-   (paths), what you skipped and why.
-7. If workspace/checkpoints/sibling/pending.jsonl is non-empty when you
-   finish, process those payloads the same way, then truncate the file.
+1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)
+   both for session context and to extract additional reusable learnings/insights
+   the parent did not pass explicitly. Never quote secrets
+   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists
+   under this HQ root, read it and follow it wherever it goes beyond these instructions;
+   the write bounds below always win over the skill text.
+2. Upgrade the thread file named in the payload IN PLACE: verify/repair its
+   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and
+   git.knowledge_repos by scanning core/knowledge/public/*,
+   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge
+   for symlinks or directories containing .git, recording dirty repositories
+   as {"<name>": {"commit": "<short>", "dirty": true}}. Fill worker,
+   next_steps, and insights; set type to "checkpoint"; then rename the file to
+   drop -auto- from its filename. Use the renamed path in every reference you
+   write afterwards.
+3. For every explicit or transcript-derived learning that is a reusable rule,
+   distill a non-duplicate policy file under personal/policies/ or, only when
+   the payload names a company and the rule is company-specific,
+   companies/<company>/policies/, following
+   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or
+   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md
+   when present, otherwise workspace/insights/. Durable facts (not rules) may
+   go under personal/knowledge/ or companies/<company>/knowledge/ only.
+4. Close an active session journal fail-soft with
+   bash .claude/skills/_shared/journal.sh close "<project_dir>" "<one-line synthesis>".
+   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with
+   id, created_at, summary, files, and next_steps for backward compatibility.
+5. Update workspace/threads/recent.md and regenerate
+   workspace/threads/INDEX.md. For each company whose knowledge path appears
+   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under
+   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation
+   is allowed for those companies, but knowledge/policy content writes remain
+   restricted to the payload's named company.
+6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;
+   skip silently on any failure. Hook or automation improvements go ONLY under
+   personal/hooks/ as proposals.
+7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.
+8. Write <runDir>/report.md — full prose: what you read, what you changed
+   (paths), and what you skipped and why. If
+   workspace/checkpoints/sibling/pending.jsonl is non-empty when you finish,
+   process those payloads with this same flow, then truncate the file.
 `;
 export function renderSiblingPrompt(runDir, payloadPath) {
     return SIBLING_PROMPT_TEMPLATE
@@ -105,6 +129,27 @@ function asStringList(value, field) {
     }
     return value;
 }
+function asWorker(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        usage("checkpoint: payload worker must be an object");
+    }
+    const worker = value;
+    return {
+        id: asOptionalString(worker.id, "worker.id"),
+        skill: asOptionalString(worker.skill, "worker.skill"),
+        state: asOptionalString(worker.state, "worker.state"),
+    };
+}
+function resolveWorker(options, command, payload) {
+    const payloadWorker = asWorker(payload.worker);
+    const id = wasPassed(command, "worker") ? options.worker : payloadWorker.id;
+    const skill = wasPassed(command, "workerSkill") ? options.workerSkill : payloadWorker.skill;
+    const suppliedState = wasPassed(command, "workerState") ? options.workerState : payloadWorker.state;
+    const state = suppliedState ?? (id ? "completed" : null);
+    return { id: id ?? null, skill: skill ?? null, state };
+}
 function wasPassed(command, option) {
     return command.getOptionValueSource(option) === "cli";
 }
@@ -129,6 +174,9 @@ function mergeInput(options, command, payload) {
     const learnings = wasPassed(command, "learning")
         ? options.learning
         : asStringList(payload.learnings, "learnings");
+    const insights = wasPassed(command, "insight")
+        ? options.insight
+        : asStringList(payload.insights, "insights");
     const decisions = wasPassed(command, "decision")
         ? options.decision
         : asStringList(payload.decisions, "decisions");
@@ -138,6 +186,12 @@ function mergeInput(options, command, payload) {
     const tags = wasPassed(command, "tag")
         ? options.tag
         : asStringList(payload.tags, "tags");
+    const commits = wasPassed(command, "commit")
+        ? options.commit
+        : asStringList(payload.commits, "commits");
+    const initialCommit = wasPassed(command, "initialCommit")
+        ? options.initialCommit
+        : asOptionalString(payload.initial_commit, "initial_commit");
     const trigger = (wasPassed(command, "trigger")
         ? options.trigger
         : asOptionalString(payload.trigger, "trigger")) ?? DEFAULT_TRIGGER;
@@ -152,9 +206,13 @@ function mergeInput(options, command, payload) {
         summary,
         files,
         learnings,
+        insights,
         decisions,
         nextSteps,
         tags,
+        commits,
+        initialCommit,
+        worker: resolveWorker(options, command, payload),
         trigger,
         company,
         sessionId,
@@ -190,19 +248,49 @@ function readGitState(repoDir) {
             branch: read(["rev-parse", "--abbrev-ref", "HEAD"]),
             current_commit: read(["rev-parse", "--short", "HEAD"]),
             dirty: read(["status", "--porcelain"]) !== "",
+            remote_url: (() => {
+                try {
+                    return read(["remote", "get-url", "origin"]);
+                }
+                catch {
+                    return null;
+                }
+            })(),
         };
     }
     catch {
         return null;
     }
 }
-function gitStateFor(cwd, liveRoot) {
-    return (readGitState(cwd) ??
+function commitsSince(repoDir, initialCommit) {
+    try {
+        const output = execFileSync("git", ["-C", repoDir, "log", "--no-decorate", "--pretty=format:%h: %s", `${initialCommit}..HEAD`], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return output ? output.split("\n") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function gitStateFor(cwd, liveRoot, initialCommit, explicitCommits) {
+    const callerState = readGitState(cwd);
+    const state = callerState ??
         readGitState(liveRoot) ?? {
         branch: "unknown",
         current_commit: "unknown",
         dirty: false,
-    });
+        remote_url: null,
+    };
+    return {
+        ...state,
+        // Remote URLs and derived history describe the caller's repository only.
+        remote_url: callerState?.remote_url ?? null,
+        initial_commit: initialCommit ?? null,
+        commits_made: explicitCommits.length > 0
+            ? explicitCommits
+            : initialCommit && callerState
+                ? commitsSince(cwd, initialCommit)
+                : [],
+    };
 }
 function writeStamps(liveRoot, sessionId) {
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
@@ -287,6 +375,7 @@ function siblingPayload(input, threadPath) {
         summary: input.summary ?? "",
         files: input.files,
         learnings: input.learnings,
+        insights: input.insights,
         decisions: input.decisions,
         next_steps: input.nextSteps,
         tags: input.tags,
@@ -294,6 +383,7 @@ function siblingPayload(input, threadPath) {
         company: input.company ?? null,
         session_id: input.sessionId ?? null,
         transcript: input.transcript ?? null,
+        worker: input.worker,
         thread_path: threadPath,
         pending_payloads: [],
     };
@@ -410,9 +500,15 @@ function hasGateProbeConflict(options, command) {
         "summary",
         "file",
         "learning",
+        "insight",
         "decision",
         "next",
         "tag",
+        "commit",
+        "initialCommit",
+        "worker",
+        "workerSkill",
+        "workerState",
         "trigger",
         "company",
         "sessionId",
@@ -456,6 +552,7 @@ function runCheckpoint(options, command, group) {
     const threadId = `T-${formatTimestamp(now)}-auto-${summarySlug(input.summary)}`;
     const threadPath = path.join(liveRoot, "workspace", "threads", `${threadId}.json`);
     const relativeThreadPath = path.relative(liveRoot, threadPath);
+    const git = gitStateFor(process.cwd(), liveRoot, input.initialCommit, input.commits);
     const stampPaths = [
         path.join(liveRoot, "workspace", "orchestrator", "hook-state", "checkpoint-cli-last"),
         path.join(liveRoot, "workspace", "orchestrator", "hook-state", `checkpoint-cli-last-${input.sessionId ? input.sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown" : "unknown"}`),
@@ -465,6 +562,11 @@ function runCheckpoint(options, command, group) {
             live_root: liveRoot,
             idle: false,
             thread: relativeThreadPath,
+            checkpoint: {
+                git,
+                insights: input.insights,
+                worker: input.worker,
+            },
             stamps: stampPaths.map((stampPath) => path.relative(liveRoot, stampPath)),
             sibling: options.agent === false ? null : { backend },
         });
@@ -478,12 +580,14 @@ function runCheckpoint(options, command, group) {
         updated_at: now.toISOString(),
         workspace_root: liveRoot,
         cwd: process.cwd(),
-        git: gitStateFor(process.cwd(), liveRoot),
+        git,
         conversation_summary: input.summary,
         files_touched: input.files,
         next_steps: input.nextSteps,
         learnings: input.learnings,
+        insights: input.insights,
         decisions: input.decisions,
+        worker: input.worker,
         session_id: input.sessionId ?? null,
         metadata: {
             title: titleFor(input.summary),
@@ -516,9 +620,15 @@ export function registerCoreCheckpointCommand(core) {
         .option("--summary <text>", "1–2 sentence outcome summary")
         .option("--file <path>", "file touched this turn", collect, [])
         .option("--learning <text>", "reusable lesson", collect, [])
+        .option("--insight <text>", "session insight", collect, [])
         .option("--decision <text>", "decision made", collect, [])
         .option("--next <text>", "remaining next step", collect, [])
         .option("--tag <tag>", "checkpoint tag", collect, [])
+        .option("--commit <entry>", "session commit (<hash>: <message>)", collect, [])
+        .option("--initial-commit <sha>", "commit at the start of this session")
+        .option("--worker <id>", "active worker identifier")
+        .option("--worker-skill <name>", "active worker skill")
+        .option("--worker-state <state>", "active worker state")
         .option("--trigger <name>", "checkpoint trigger", DEFAULT_TRIGGER)
         .option("--company <slug>", "active company scope")
         .option("--session-id <id>", "caller session id (default: $CLAUDE_CODE_SESSION_ID when set)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.81.0",
+  "version": "5.82.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {