geloforge 0.6.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,6 +11,12 @@ import { parseArgs } from "node:util";
11
11
  import { fileURLToPath } from "node:url";
12
12
  import { bootstrapProject, DEFAULT_INIT_LOCATION } from "./bootstrap-project.mjs";
13
13
  import { adoptProject } from "../core/adopt-project.mjs";
14
+ import { auditStagingFailure, readAutonomousMode, setAutonomousMode, stagingProgressPath } from "../core/autonomous-audit.mjs";
15
+ import { authorizeStagingWorker, watchStagingAudits } from "../core/staging-audit.mjs";
16
+ import { learnFromStagingAudits } from "../core/audit-learning.mjs";
17
+ import { manageWorktrees } from "../core/worktrees.mjs";
18
+ import { promoteProjectProposal } from "../core/promotion.mjs";
19
+ import { compileCachedContext } from "../core/context-cache.mjs";
14
20
  import { validateProject } from "../core/project-validator.mjs";
15
21
  import { compileContext } from "../core/context-compiler.mjs";
16
22
  import { getProjectStatus, getProjectRecommendations } from "../core/project-status.mjs";
@@ -30,10 +36,15 @@ import { verifyTask } from "../core/verify-task.mjs";
30
36
  import { createCheckpoint, getCheckpoint, listCheckpoints } from "../core/checkpoint.mjs";
31
37
  import { startMcpStdioServer } from "../core/mcp-server.mjs";
32
38
  import { initMcpClients } from "../core/mcp-init.mjs";
39
+ import { checkMcpLock, lockMcpServers } from "../core/mcp-lock.mjs";
40
+ import { runProjectDoctor } from "../core/doctor.mjs";
41
+ import { HOOK_TARGETS, initProjectHooks } from "../core/hooks-init.mjs";
42
+ import { getCodingLoopStatus, runCodingLoop } from "../core/coding-loop.mjs";
33
43
  import {
34
44
  discoverSkills,
35
45
  resolveProjectForSkills,
36
46
  } from "../core/skills.mjs";
47
+ import { suggestProjectSkills } from "../core/skills-advisor.mjs";
37
48
  import { STATIC_LINT_DISCLAIMER, lintDiscoveredSkills, lintSkill } from "../core/skills-lint.mjs";
38
49
  import {
39
50
  draftSkillFromExperience,
@@ -45,7 +56,8 @@ import {
45
56
  signSkillApproval,
46
57
  } from "../core/skills-lifecycle.mjs";
47
58
  import { atomicWriteFile, redactSecretContent, validateOutputFilePath } from "../core/path-safety.mjs";
48
- import { resolveProjectDir } from "../core/project-locator.mjs";
59
+ import { loadProjectManifestAndState, resolveProjectDir } from "../core/project-locator.mjs";
60
+ import { readRuntimeJson } from "../core/runtime-files.mjs";
49
61
 
50
62
  const __filename = fileURLToPath(import.meta.url);
51
63
  const __dirname = path.dirname(__filename);
@@ -74,8 +86,14 @@ Commands:
74
86
  handoff Create or inspect a cross-agent file-based handoff record (HANDOFF-NNNN)
75
87
  checkpoint Create, list, or inspect session recovery checkpoints (CHKPT-NNNN)
76
88
  recommend Show ranked Human-in-the-Loop Co-Pilot recommendations & approval inbox
89
+ autonomous Run opt-in staging audits, review progress, and learn from completed audits
90
+ loop Run bounded implement -> verify -> review -> fix coding loop for a task
91
+ proposal Review, sign, or promote a canonical-document proposal
92
+ worktree Add, list, or remove isolated local Git worktrees
77
93
  status Inspect project health, operational task state, leases, and Git status
78
- mcp Start the stdio MCP server or configure MCP clients with mcp init
94
+ doctor Run one-command diagnostics across setup, compatibility, MCP locks, skills, and hooks
95
+ hooks Install or preview opt-in Git pre-commit, Claude Code, and Gemini CLI hooks (hooks init)
96
+ mcp Start stdio MCP server, configure clients (mcp init), or pin tools (mcp lock)
79
97
 
80
98
  Global Options:
81
99
  -h, --help Show help (use "geloforge <command> --help" for command options)
@@ -85,6 +103,76 @@ Global Options:
85
103
 
86
104
  function printSubHelp(cmd) {
87
105
  switch (cmd) {
106
+ case "doctor":
107
+ console.log(`Usage: geloforge doctor [options]
108
+
109
+ Checks Node.js runtime, Second Brain validation, harness compatibility, Git status,
110
+ cooperative task leases, skill lint health, MCP tool lockfiles, and ambient hooks.
111
+
112
+ Options:
113
+ -p, --project <path> Target project directory (auto-detected from CWD if omitted)
114
+ --global-dir <path> Override global skills directory (default: GELOFORGE_SKILLS_DIR or ~/.geloforge/skills)
115
+ --include-drafts Include quarantined drafts when running skills lint
116
+ --skip-mcp-check Skip probing stdio MCP servers when .geloforge/mcp-lock.json exists
117
+ --timeout-ms <ms> MCP probe timeout in ms (500-30000)
118
+ --json Emit structured JSON output
119
+ -h, --help Show help
120
+ `);
121
+ break;
122
+ case "hooks":
123
+ console.log(`Usage: geloforge hooks init [options]
124
+
125
+ Installs or previews lightweight, opt-in local checks without background daemons:
126
+ git .git/hooks/pre-commit (runs geloforge validate + mcp lock --check if locked)
127
+ claude .claude/settings.json hooks.Stop (advisory doctor reminder)
128
+ gemini .gemini/settings.json hooks.AfterAgent (preserves existing mcpServers)
129
+
130
+ Options:
131
+ -p, --project <path> Target project directory (auto-detected from CWD if omitted)
132
+ --target <list> Targets: git, claude, gemini (comma-separated or repeatable; default: all)
133
+ --dry-run Preview file changes without writing disk
134
+ --json Emit structured JSON output
135
+ -h, --help Show help
136
+ `);
137
+ break;
138
+ case "autonomous":
139
+ console.log(`Usage: geloforge autonomous <status|on|off|audit|authorize|watch|progress|learn> [options]
140
+
141
+ status | on | off Inspect or set this project's switch (default OFF)
142
+ audit Verify one saved local failure with --event and --execution
143
+ authorize Sign a staging --config with --key (optional --expires-at)
144
+ watch Process staging deliveries using --config, --approval and --owner-key
145
+ Use --once to process the inbox and exit
146
+ progress Show the saved audit stage and remaining work with --task
147
+ learn List recurring failures, or draft with --pattern and --skill
148
+ Use --step to provide a reviewed checklist step
149
+
150
+ Paths for --event, --execution and --config are relative to the project.
151
+ Use --project <path> to select the project and --json for machine-readable output.
152
+ `);
153
+ break;
154
+ case "proposal":
155
+ console.log(`Usage: geloforge proposal <preview|sign|promote> --proposal <file.md> --target <file.md> --evidence EVID-NNNN [options]
156
+
157
+ sign Use --key <private PEM> and optional --expires-at <ISO timestamp>
158
+ promote Use --approval APPR-NNNN and --owner-key <pinned public PEM>
159
+ --project Project path (auto-detected when omitted)
160
+ --json Emit structured output
161
+
162
+ Paths are project-relative. Repeat --evidence to bind multiple verified records.
163
+ `);
164
+ break;
165
+ case "worktree":
166
+ console.log(`Usage: geloforge worktree <list|add|remove> [name] [options]
167
+
168
+ --project <path> Git project root (auto-detected when omitted)
169
+ --workspace <path> Workspace containing worktrees/ (defaults to project parent)
170
+ --ref <ref> Commit or ref for add (defaults to HEAD)
171
+ --json Emit structured output
172
+
173
+ Removal delegates to Git's clean-worktree check and preserves the branch.
174
+ `);
175
+ break;
88
176
  case "init":
89
177
  console.log(`Usage: geloforge init --name "<Project Name>" [options]
90
178
 
@@ -148,6 +236,7 @@ Options:
148
236
  --skill <name> Explicitly pin a trusted skill into Tier 1 (repeatable; implies --skills)
149
237
  --skills-budget <int> Override portable skills estimated-token budget (>= 100)
150
238
  --exclude-unverified Omit A5-A6, draft, and unverified records/skills completely
239
+ --cache Reuse an unchanged query packet from the project disk cache
151
240
  --format <type> Output format: markdown (default) or json
152
241
  -o, --out <file> Write output atomically to a safe file path
153
242
  --compiled-at <iso> ISO-8601 timestamp for deterministic manifest
@@ -174,12 +263,13 @@ Options:
174
263
  `);
175
264
  break;
176
265
  case "checkpoint":
177
- console.log(`Usage: geloforge checkpoint <create|list|show> [options]
266
+ console.log(`Usage: geloforge checkpoint <create|list|show|resume> [options]
178
267
 
179
268
  Subcommands:
180
269
  create Capture a CHKPT-NNNN session recovery checkpoint
181
270
  list List recovery checkpoints ordered newest first
182
- show Inspect a specific checkpoint (or latest if ID omitted)
271
+ show Inspect a specific checkpoint (or last project checkpoint)
272
+ resume Read a checkpoint, compare current state, and show the next action
183
273
 
184
274
  Options:
185
275
  -p, --project <path> Target project directory (auto-detected from CWD if omitted)
@@ -192,6 +282,7 @@ Options:
192
282
  --id <CHKPT-NNNN> Explicit checkpoint ID ('create' or 'show')
193
283
  --created-at <iso> ISO-8601 timestamp override ('create')
194
284
  --dry-run Preview checkpoint without writing disk ('create')
285
+ --local Save in local-runtime/checkpoints/ without updating project state ('create')
195
286
  --json Emit structured JSON output
196
287
  -h, --help Show help
197
288
  `);
@@ -199,6 +290,7 @@ Options:
199
290
  case "mcp":
200
291
  console.log(`Usage: geloforge mcp [serve] [--project <path>] [--read-only]
201
292
  geloforge mcp init [--project <path>] [--client <name>] [--read-only] [--dry-run] [--json]
293
+ geloforge mcp lock [--project <path>] [--client <name>] [--check] [--dry-run] [--timeout-ms <ms>] [--json]
202
294
 
203
295
  Runs GeloForge's zero-dependency JSON-RPC 2.0 MCP server on stdin/stdout.
204
296
  Pins operations to the configured/current project root (when present).
@@ -212,10 +304,30 @@ Options:
212
304
  --read-only Refuse all state-mutating MCP actions
213
305
  -h, --help Show help
214
306
 
215
- Init options:
216
- --client <name> cursor, vscode, claude, or gemini (repeatable, defaults to all four)
217
- --dry-run Preview project configuration and rule updates
218
- --json Emit the list of planned or written files
307
+ Init / Lock options:
308
+ --client <name> cursor, vscode, claude, gemini, or antigravity
309
+ --check Compare live stdio MCP tool definitions against .geloforge/mcp-lock.json
310
+ --timeout-ms <ms> Probe timeout per stdio server (100-60000, default: 8000)
311
+ --dry-run Preview changes without writing files
312
+ --json Emit structured JSON output
313
+ `);
314
+ break;
315
+ case "loop":
316
+ console.log(`Usage: geloforge loop run --config <relpath> [--task TASK-NNNN] [options]
317
+ geloforge loop status [--task TASK-NNNN] [--project <path>] [--json]
318
+
319
+ Run a bounded implement -> verify -> review -> fix loop for one open task.
320
+ Deterministic command verification gates task completion; LLM review never overrides a failing gate.
321
+
322
+ Options:
323
+ -p, --project <path> Target project directory (auto-detected from CWD if omitted)
324
+ --config <relpath> Project-relative JSON config file (required for 'run')
325
+ -t, --task <TASK-NNNN> Target task ID (defaults to sole active task)
326
+ --tool <name> Cooperative lease tool label
327
+ --session <id> Cooperative lease session label
328
+ --dry-run Validate config, executables, task, and context without running providers
329
+ --json Emit structured JSON output
330
+ -h, --help Show help
219
331
  `);
220
332
  break;
221
333
  case "handoff":
@@ -344,11 +456,12 @@ Safety & Accuracy Notes:
344
456
  case "skills":
345
457
  console.log(`Usage: geloforge skills <subcommand> [options]
346
458
 
347
- Discovery & Static Checks:
459
+ Discovery, Static Checks & Advisor:
348
460
  list List discovered portable skills across project (.agents/skills) and global dirs
349
461
  show Inspect one skill's metadata, supporting resources, and instructions
350
462
  validate Validate SKILL.md frontmatter, path/symlink/secret safety, and local links
351
463
  lint Run static security and quality lint checks across discovered skills
464
+ suggest Analyze project signals & goal to rank existing skills, detect gaps, or scaffold drafts
352
465
 
353
466
  Adaptive Skills Lifecycle (Evidence-Backed & Human-Authorized):
354
467
  draft Draft a quarantined skill in proposals/skills/ from verified EVID/HANDOFF records
@@ -359,6 +472,14 @@ Adaptive Skills Lifecycle (Evidence-Backed & Human-Authorized):
359
472
  history Inspect append-only revision ledger and snapshot integrity for a skill
360
473
  rollback Restore an authorized verified snapshot revision (never bypasses approval)
361
474
 
475
+ Advisor Options ('suggest'):
476
+ --goal <text> Target goal description to rank existing skills and detect gaps
477
+ --query <text> Alias for --goal
478
+ --task <TASK-NNNN> Analyze a specific task's scope and acceptance criteria
479
+ --limit <1..20> Max existing skills to recommend (default: 5)
480
+ --scaffold-draft Stage a quarantined SKILL.md draft under proposals/skills/ (never active)
481
+ --name <skill-slug> Custom skill slug when used with --scaffold-draft
482
+
362
483
  Authorization Options for 'promote' & 'rollback':
363
484
  --approval <APPR-NNNN> Verify cryptographic Ed25519 signature (recommended)
364
485
  --public-key <file> Verify signature against an external pinned SPKI public key PEM
@@ -526,6 +647,7 @@ function handleContext(args) {
526
647
  skill: { type: "string", multiple: true },
527
648
  "skills-budget": { type: "string" },
528
649
  "exclude-unverified": { type: "boolean", default: false },
650
+ cache: { type: "boolean" },
529
651
  "from-diff": { type: "boolean", default: false },
530
652
  "include-completed": { type: "boolean", default: false },
531
653
  format: { type: "string", default: "markdown" },
@@ -587,7 +709,8 @@ function handleContext(args) {
587
709
  }
588
710
 
589
711
  const { projectDir } = resolveProjectDir({ project: parsed.values.project, harnessDir: HARNESS_DIR });
590
- const result = compileContext({
712
+ const compile = parsed.values.cache ? compileCachedContext : compileContext;
713
+ const result = compile({
591
714
  projectDir,
592
715
  taskId: parsed.values.task,
593
716
  query: parsed.values.query,
@@ -636,6 +759,146 @@ function handleContext(args) {
636
759
  return 0;
637
760
  }
638
761
 
762
+ async function handleAutonomous(args) {
763
+ const [subcommand, ...rest] = args;
764
+ if (!subcommand || subcommand === "--help" || subcommand === "-h") {
765
+ printSubHelp("autonomous");
766
+ return 0;
767
+ }
768
+ const specific = {
769
+ status: {}, on: {}, off: {},
770
+ audit: { event: { type: "string" }, execution: { type: "string" } },
771
+ authorize: { config: { type: "string" }, key: { type: "string" }, "expires-at": { type: "string" } },
772
+ watch: { config: { type: "string" }, approval: { type: "string" }, "owner-key": { type: "string" }, once: { type: "boolean" } },
773
+ progress: { task: { type: "string" } },
774
+ learn: { pattern: { type: "string" }, skill: { type: "string" }, step: { type: "string" } },
775
+ };
776
+ if (!Object.hasOwn(specific, subcommand)) throw new Error("Unknown autonomous subcommand. See autonomous --help.");
777
+ const { values } = parseArgs({
778
+ args: rest,
779
+ options: {
780
+ ...specific[subcommand], project: { type: "string", short: "p" },
781
+ json: { type: "boolean" }, help: { type: "boolean", short: "h" },
782
+ },
783
+ });
784
+ if (values.help) {
785
+ printSubHelp("autonomous");
786
+ return 0;
787
+ }
788
+
789
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
790
+ const options = { projectDir, harnessDir: HARNESS_DIR };
791
+ let result;
792
+ if (subcommand === "audit") {
793
+ result = auditStagingFailure({ ...options, eventFile: values.event, executionFile: values.execution });
794
+ } else if (subcommand === "status") {
795
+ loadProjectManifestAndState(projectDir, HARNESS_DIR);
796
+ result = { mode: readAutonomousMode(projectDir) };
797
+ } else if (subcommand === "authorize") {
798
+ result = authorizeStagingWorker({ ...options, configFile: values.config, privateKeyPath: values.key,
799
+ expiresAt: values["expires-at"] });
800
+ } else if (subcommand === "watch") {
801
+ const controller = new AbortController();
802
+ const stop = () => controller.abort();
803
+ const signals = ["SIGINT", "SIGTERM"];
804
+ for (const signal of signals) process.on(signal, stop);
805
+ try {
806
+ result = await watchStagingAudits({
807
+ ...options, configFile: values.config, approvalId: values.approval, publicKeyPath: values["owner-key"],
808
+ once: values.once, signal: controller.signal,
809
+ onResult: values.once ? undefined : (outcome) => {
810
+ console.log(values.json ? JSON.stringify(outcome) :
811
+ `${outcome.taskId ?? outcome.file} ${outcome.status}. ${outcome.nextAction}`);
812
+ },
813
+ });
814
+ } finally {
815
+ for (const signal of signals) process.removeListener(signal, stop);
816
+ }
817
+ } else if (subcommand === "progress") {
818
+ loadProjectManifestAndState(projectDir, HARNESS_DIR);
819
+ const progress = readRuntimeJson(projectDir, stagingProgressPath(values.task));
820
+ if (!progress) throw new Error("No staging audit progress found for this task.");
821
+ const stepStatus = (step) => ({ attempts: step.attempts, saved: Boolean(step.result), issue: step.error ?? null });
822
+ const nextAction = progress.nextAction ?? progress.stopReason ?? "Resume the same inbox delivery with the audit worker. Completed steps will be reused.";
823
+ result = {
824
+ taskId: values.task, runs: progress.runs, repairRetries: progress.repairs,
825
+ specialists: progress.specialists.map(stepStatus), reviewer: progress.reviewer && stepStatus(progress.reviewer), nextAction,
826
+ };
827
+ } else if (subcommand === "learn") {
828
+ result = learnFromStagingAudits({ ...options, patternId: values.pattern, skillName: values.skill, step: values.step });
829
+ } else {
830
+ result = { mode: setAutonomousMode({ ...options, enabled: subcommand === "on" }) };
831
+ }
832
+
833
+ if (values.json) console.log(JSON.stringify({ projectDir, ...result }, null, 2));
834
+ else if (["status", "on", "off", "audit"].includes(subcommand)) {
835
+ console.log(`Autonomous mode: ${result.mode.toUpperCase()}`);
836
+ if (subcommand === "audit") {
837
+ console.log(`Audit ${result.status}: workflow ${result.workflowId}, execution ${result.executionId}${result.reused ? " (existing task)" : ""}`);
838
+ if (result.taskId) console.log(`Task: ${result.taskId}`);
839
+ if (result.checkpointId) console.log(`Checkpoint: ${result.checkpointId}`);
840
+ if (result.evidenceId) console.log(`Evidence: ${result.evidenceId}`);
841
+ console.log(`Next step: ${result.nextAction}`);
842
+ }
843
+ } else console.log(JSON.stringify(result, null, 2));
844
+ return 0;
845
+ }
846
+
847
+ function handleProposal(args) {
848
+ const [action, ...rest] = args;
849
+ if (!action || ["--help", "-h"].includes(action)) {
850
+ printSubHelp("proposal");
851
+ return 0;
852
+ }
853
+ if (!["preview", "sign", "promote"].includes(action)) throw new Error("Use proposal preview, sign, or promote.");
854
+ const { values } = parseArgs({
855
+ args: rest,
856
+ options: {
857
+ project: { type: "string", short: "p" }, proposal: { type: "string" }, target: { type: "string" },
858
+ evidence: { type: "string", multiple: true }, approval: { type: "string" }, key: { type: "string" },
859
+ "owner-key": { type: "string" }, "expires-at": { type: "string" }, json: { type: "boolean" },
860
+ help: { type: "boolean", short: "h" },
861
+ },
862
+ });
863
+ if (values.help) {
864
+ printSubHelp("proposal");
865
+ return 0;
866
+ }
867
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
868
+ const result = promoteProjectProposal({
869
+ projectDir, harnessDir: HARNESS_DIR, action, proposal: values.proposal, target: values.target,
870
+ evidenceIds: values.evidence, approvalId: values.approval, privateKeyPath: values.key,
871
+ publicKeyPath: values["owner-key"], expiresAt: values["expires-at"],
872
+ });
873
+ console.log(JSON.stringify(result, null, 2));
874
+ return 0;
875
+ }
876
+
877
+ function handleWorktree(args) {
878
+ const [action, ...rest] = args;
879
+ if (!action || ["--help", "-h"].includes(action)) {
880
+ printSubHelp("worktree");
881
+ return 0;
882
+ }
883
+ if (!["list", "add", "remove"].includes(action)) throw new Error("Use worktree list, add, or remove.");
884
+ const { values, positionals } = parseArgs({
885
+ args: rest, allowPositionals: true,
886
+ options: {
887
+ project: { type: "string", short: "p" }, workspace: { type: "string" }, ref: { type: "string" },
888
+ json: { type: "boolean" }, help: { type: "boolean", short: "h" },
889
+ },
890
+ });
891
+ if (values.help) {
892
+ printSubHelp("worktree");
893
+ return 0;
894
+ }
895
+ if (positionals.length !== (action === "list" ? 0 : 1)) throw new Error("Supply one worktree name for add or remove.");
896
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
897
+ const result = manageWorktrees({ projectDir, action, name: positionals[0], workspace: values.workspace, ref: values.ref });
898
+ console.log(JSON.stringify(result, null, 2));
899
+ return 0;
900
+ }
901
+
639
902
  function handleStatus(args) {
640
903
  const parsed = parseArgs({
641
904
  args,
@@ -670,6 +933,7 @@ function handleStatus(args) {
670
933
  `Operational : phase=${s.currentPhase} | active=${s.activeTasks.length} | blocked=${s.blockedTasks.length} | approvals=${s.pendingApprovals.length} | conflicts=${s.openConflicts.length}`
671
934
  );
672
935
  }
936
+ console.log(`Autonomous mode: ${status.autonomousMode.toUpperCase()}`);
673
937
  console.log(
674
938
  `Git : ${
675
939
  status.vcs.available
@@ -723,6 +987,7 @@ function handleRecommend(args) {
723
987
  return 0;
724
988
  }
725
989
  console.log(`Co-Pilot Recommend : ${rec.project ? `${rec.project.name} (${rec.project.id})` : rec.projectDir}`);
990
+ console.log(`Autonomous mode : ${rec.autonomousMode.toUpperCase()}`);
726
991
  console.log(
727
992
  `Approval Inbox : ${rec.pendingApprovalsInbox.length} pending item(s) | Active Leases: ${rec.activeLeases.length}`
728
993
  );
@@ -770,6 +1035,7 @@ function handleCheckpoint(args) {
770
1035
  id: { type: "string" },
771
1036
  "created-at": { type: "string" },
772
1037
  "dry-run": { type: "boolean", default: false },
1038
+ local: { type: "boolean" },
773
1039
  json: { type: "boolean", default: false },
774
1040
  help: { type: "boolean", short: "h", default: false },
775
1041
  },
@@ -793,6 +1059,7 @@ function handleCheckpoint(args) {
793
1059
  id: parsed.values.id,
794
1060
  createdAt: parsed.values["created-at"],
795
1061
  dryRun: parsed.values["dry-run"],
1062
+ local: parsed.values.local,
796
1063
  });
797
1064
  if (parsed.values.json) {
798
1065
  console.log(JSON.stringify(res, null, 2));
@@ -833,7 +1100,7 @@ function handleCheckpoint(args) {
833
1100
  return 0;
834
1101
  }
835
1102
 
836
- if (subcmd === "show") {
1103
+ if (subcmd === "show" || subcmd === "resume") {
837
1104
  const parsed = parseArgs({
838
1105
  args: rest,
839
1106
  options: {
@@ -851,7 +1118,22 @@ function handleCheckpoint(args) {
851
1118
  }
852
1119
  const targetId = parsed.values.id || parsed.positionals[0] || null;
853
1120
  const { projectDir } = resolveProjectDir({ project: parsed.values.project, harnessDir: HARNESS_DIR });
854
- const res = getCheckpoint({ projectDir, checkpointId: targetId, harnessDir: HARNESS_DIR });
1121
+ const res = getCheckpoint({ projectDir, checkpointId: targetId, harnessDir: HARNESS_DIR, newest: subcmd === "resume" });
1122
+ if (subcmd === "resume") {
1123
+ const { state } = loadProjectManifestAndState(projectDir, HARNESS_DIR);
1124
+ const advanced = state.state_revision !== res.record.state_revision;
1125
+ const unavailable = ["expired", "invalidated"].includes(res.record.status);
1126
+ const resume = {
1127
+ ...res, stateAdvanced: advanced,
1128
+ nextAction: unavailable ? "Use a current checkpoint or run geloforge recommend." : res.record.resume_instructions,
1129
+ reason: unavailable ? "This checkpoint is expired or invalidated." : advanced
1130
+ ? "Project state differs from the saved checkpoint. Confirm the current task before applying the saved instructions."
1131
+ : "The checkpoint matches the current project state revision.",
1132
+ };
1133
+ if (parsed.values.json) console.log(JSON.stringify(resume, null, 2));
1134
+ else console.log(`${res.checkpointId} — ${resume.reason}\n${resume.nextAction}`);
1135
+ return 0;
1136
+ }
855
1137
  if (parsed.values.json) {
856
1138
  console.log(JSON.stringify(res, null, 2));
857
1139
  return 0;
@@ -864,7 +1146,7 @@ function handleCheckpoint(args) {
864
1146
  return 0;
865
1147
  }
866
1148
 
867
- throw new Error(`Unknown checkpoint subcommand "${subcmd}". Expected: create, list, or show.`);
1149
+ throw new Error(`Unknown checkpoint subcommand "${subcmd}". Expected: create, list, show, or resume.`);
868
1150
  }
869
1151
 
870
1152
  function handleMcpInit(args) {
@@ -897,8 +1179,117 @@ function handleMcpInit(args) {
897
1179
  return 0;
898
1180
  }
899
1181
 
1182
+ async function handleMcpLock(args) {
1183
+ const { values } = parseArgs({
1184
+ args,
1185
+ options: {
1186
+ project: { type: "string", short: "p" },
1187
+ client: { type: "string", multiple: true },
1188
+ check: { type: "boolean", default: false },
1189
+ "dry-run": { type: "boolean", default: false },
1190
+ "timeout-ms": { type: "string" },
1191
+ json: { type: "boolean", default: false },
1192
+ help: { type: "boolean", short: "h", default: false },
1193
+ },
1194
+ strict: true,
1195
+ allowPositionals: false,
1196
+ });
1197
+ if (values.help) {
1198
+ printSubHelp("mcp");
1199
+ return 0;
1200
+ }
1201
+ if (values.check && values["dry-run"]) {
1202
+ throw new Error("--dry-run only applies when writing .geloforge/mcp-lock.json.");
1203
+ }
1204
+ const timeoutMs = values["timeout-ms"] !== undefined ? parseCheckTimeout(values["timeout-ms"]) : undefined;
1205
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
1206
+ const result = values.check
1207
+ ? await checkMcpLock({ projectDir, harnessDir: HARNESS_DIR, clients: values.client, timeoutMs })
1208
+ : await lockMcpServers({
1209
+ projectDir,
1210
+ harnessDir: HARNESS_DIR,
1211
+ clients: values.client,
1212
+ timeoutMs,
1213
+ dryRun: values["dry-run"],
1214
+ });
1215
+ if (values.json) {
1216
+ console.log(JSON.stringify(result, null, 2));
1217
+ } else if (values.check) {
1218
+ console.log(
1219
+ result.passed
1220
+ ? `MCP lock verified (${result.checkedCount} stdio server(s)): ${result.lockPath}`
1221
+ : `MCP lock check failed (${result.driftedServers.length} drifted, ${result.addedServers.length} added, ${result.removedServers.length} removed, ${result.errors.length} errors)`
1222
+ );
1223
+ } else {
1224
+ console.log(
1225
+ `${result.dryRun ? "DRY RUN — " : ""}Pinned ${result.serverCount} stdio MCP server(s) to ${result.lockPath} (${result.skippedCount} non-stdio skipped)`
1226
+ );
1227
+ }
1228
+ return values.check && !result.passed ? 1 : 0;
1229
+ }
1230
+
1231
+ async function handleLoop(args) {
1232
+ if (!args.length || args[0] === "-h" || args[0] === "--help") {
1233
+ printSubHelp("loop");
1234
+ return 0;
1235
+ }
1236
+ const [subcmd, ...rest] = args;
1237
+ if (!["run", "status"].includes(subcmd)) {
1238
+ throw new Error(`Unknown loop subcommand "${subcmd}". Expected: run or status.`);
1239
+ }
1240
+ const { values } = parseArgs({
1241
+ args: rest,
1242
+ options: {
1243
+ project: { type: "string", short: "p" },
1244
+ config: { type: "string" },
1245
+ task: { type: "string", short: "t" },
1246
+ tool: { type: "string" },
1247
+ session: { type: "string" },
1248
+ "dry-run": { type: "boolean", default: false },
1249
+ json: { type: "boolean", default: false },
1250
+ help: { type: "boolean", short: "h", default: false },
1251
+ },
1252
+ strict: true,
1253
+ allowPositionals: false,
1254
+ });
1255
+ if (values.help) {
1256
+ printSubHelp("loop");
1257
+ return 0;
1258
+ }
1259
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
1260
+ if (subcmd === "status") {
1261
+ const res = getCodingLoopStatus({ projectDir, harnessDir: HARNESS_DIR, taskId: values.task });
1262
+ if (values.json) console.log(JSON.stringify(res, null, 2));
1263
+ else console.log(`${res.taskId} loop status: ${res.status} (rounds=${res.roundsUsed}/${res.maxFixRounds}, attempts=${res.implementAttempts})`);
1264
+ return 0;
1265
+ }
1266
+ if (!values.config) {
1267
+ throw new Error("Missing required --config <relpath> for 'geloforge loop run'.");
1268
+ }
1269
+ const res = await runCodingLoop({
1270
+ projectDir,
1271
+ harnessDir: HARNESS_DIR,
1272
+ configFile: values.config,
1273
+ taskId: values.task,
1274
+ tool: values.tool,
1275
+ sessionId: values.session,
1276
+ dryRun: values["dry-run"],
1277
+ });
1278
+ if (values.json) {
1279
+ console.log(JSON.stringify(res, null, 2));
1280
+ } else if (res.status === "dry_run") {
1281
+ console.log(`DRY RUN — Loop ready for ${res.taskId} (maxFixRounds=${res.maxFixRounds}, verify=${res.verifyCommand.join(" ")})`);
1282
+ } else if (res.status === "completed") {
1283
+ console.log(`${res.taskId} completed (${res.evidenceId}, ${res.checkpointId}) in ${res.roundsUsed} fix round(s)`);
1284
+ } else {
1285
+ console.error(`${res.taskId} blocked (${res.reason}, ${res.checkpointId})`);
1286
+ }
1287
+ return ["completed", "dry_run"].includes(res.status) ? 0 : 1;
1288
+ }
1289
+
900
1290
  async function handleMcp(args) {
901
1291
  if (args[0] === "init") return handleMcpInit(args.slice(1));
1292
+ if (args[0] === "lock") return handleMcpLock(args.slice(1));
902
1293
  let effectiveArgs = args;
903
1294
  if (args.length > 0 && (args[0] === "-h" || args[0] === "--help")) {
904
1295
  printSubHelp("mcp");
@@ -2003,6 +2394,128 @@ async function handleSkillsLifecycle(subcmd, rest) {
2003
2394
  throw new Error(`Unknown skills subcommand "${subcmd}".`);
2004
2395
  }
2005
2396
 
2397
+ async function handleSkillsSuggest(rest) {
2398
+ const parsed = parseArgs({
2399
+ args: rest,
2400
+ options: {
2401
+ project: { type: "string", short: "p" },
2402
+ task: { type: "string" },
2403
+ goal: { type: "string" },
2404
+ query: { type: "string" },
2405
+ "global-dir": { type: "string" },
2406
+ "include-drafts": { type: "boolean", default: false },
2407
+ limit: { type: "string" },
2408
+ "scaffold-draft": { type: "boolean", default: false },
2409
+ name: { type: "string" },
2410
+ "dry-run": { type: "boolean", default: false },
2411
+ "created-at": { type: "string" },
2412
+ json: { type: "boolean", default: false },
2413
+ help: { type: "boolean", short: "h", default: false },
2414
+ },
2415
+ strict: true,
2416
+ allowPositionals: false,
2417
+ });
2418
+ if (parsed.values.help) {
2419
+ printSubHelp("skills");
2420
+ return 0;
2421
+ }
2422
+ let limit;
2423
+ if (parsed.values.limit !== undefined) {
2424
+ if (!/^\d+$/.test(parsed.values.limit.trim())) {
2425
+ throw new Error("--limit must be a positive integer (1..20).");
2426
+ }
2427
+ limit = Number(parsed.values.limit.trim());
2428
+ }
2429
+ const scaffoldDraft = Boolean(parsed.values["scaffold-draft"]);
2430
+ if (parsed.values.name && !scaffoldDraft) {
2431
+ throw new Error("--name is only supported with '--scaffold-draft' on 'geloforge skills suggest'.");
2432
+ }
2433
+ if (parsed.values["dry-run"] && !scaffoldDraft) {
2434
+ throw new Error("--dry-run is only supported with '--scaffold-draft' on 'geloforge skills suggest'.");
2435
+ }
2436
+
2437
+ const loc = resolveProjectForSkills({
2438
+ project: parsed.values.project,
2439
+ harnessDir: HARNESS_DIR,
2440
+ });
2441
+ if (!loc.projectDir) {
2442
+ throw new Error("'geloforge skills suggest' requires a GeloForge project directory (--project <path> or inside a project).");
2443
+ }
2444
+
2445
+ const res = suggestProjectSkills({
2446
+ projectDir: loc.projectDir,
2447
+ harnessDir: HARNESS_DIR,
2448
+ globalSkillsDir: parsed.values["global-dir"],
2449
+ taskId: parsed.values.task || null,
2450
+ goal: parsed.values.goal || null,
2451
+ query: parsed.values.query || null,
2452
+ includeDrafts: Boolean(parsed.values["include-drafts"]),
2453
+ limit,
2454
+ scaffoldDraft,
2455
+ skillName: parsed.values.name || null,
2456
+ dryRun: Boolean(parsed.values["dry-run"]),
2457
+ createdAt: parsed.values["created-at"],
2458
+ });
2459
+
2460
+ if (parsed.values.json) {
2461
+ console.log(JSON.stringify(res, null, 2));
2462
+ return 0;
2463
+ }
2464
+
2465
+ console.log(`Skills Advisor : ${res.projectDir} (${res.projectId || "project"})`);
2466
+ if (res.goal) console.log(`Goal : ${res.goal}`);
2467
+ if (res.taskId) console.log(`Task : ${res.taskId}`);
2468
+ console.log(`Detected Stack : ${res.detectedSignals.stacks.join(", ") || "(none)"}`);
2469
+ console.log(
2470
+ `Repo Commands : ${res.detectedSignals.commands.map((c) => c.command).join(" | ") || "(none detected)"}`
2471
+ );
2472
+ console.log(
2473
+ `Skill Pool : ${res.activeSkillCount} active | ${res.quarantinedDraftCount} quarantined draft(s) | ${res.detectedSignals.verifiedEvidenceIds.length} verified EVID-*`
2474
+ );
2475
+ console.log("");
2476
+ console.log("Recommended Existing Skills:");
2477
+ if (res.recommendedSkills.length === 0) {
2478
+ console.log(" (no matching active skills discovered for this project/goal)");
2479
+ } else {
2480
+ for (const item of res.recommendedSkills) {
2481
+ console.log(` - ${item.name} [${item.source}, score=${item.score}] — ${item.reasons.join("; ")}`);
2482
+ console.log(` Use: ${item.command}`);
2483
+ }
2484
+ }
2485
+ console.log("");
2486
+ console.log("Detected Skill Gaps:");
2487
+ if (res.skillGaps.length === 0) {
2488
+ console.log(" (none detected)");
2489
+ } else {
2490
+ for (const gap of res.skillGaps) {
2491
+ const draftTag = gap.existingQuarantinedDraft ? " [quarantined draft exists]" : "";
2492
+ const promoTag = gap.promotableAfterReview
2493
+ ? "evidence-backed (promotable after review)"
2494
+ : "repo/goal scaffold (needs EVID-* before promotion)";
2495
+ console.log(` - [${gap.kind}] ${gap.suggestedName}${draftTag} — ${promoTag}`);
2496
+ console.log(` Reason : ${gap.reason}`);
2497
+ console.log(` Action : ${gap.recommendedCommand}`);
2498
+ }
2499
+ }
2500
+ if (res.scaffoldResult) {
2501
+ const sr = res.scaffoldResult;
2502
+ console.log("");
2503
+ console.log(
2504
+ sr.dryRun
2505
+ ? `DRY RUN — Quarantined scaffold "${sr.skillName}" (${sr.mode}) not written.`
2506
+ : `Quarantined draft created (${sr.mode}): ${sr.proposalDir}/SKILL.md`
2507
+ );
2508
+ console.log(`Candidate SHA : ${sr.candidateDigest}`);
2509
+ console.log(
2510
+ `Promotable Now : ${sr.promotable ? "yes (after human approval/signature)" : "no (capture verified EVID-* first)"}`
2511
+ );
2512
+ for (const step of sr.nextSteps || []) {
2513
+ console.log(` - Next: ${step}`);
2514
+ }
2515
+ }
2516
+ return 0;
2517
+ }
2518
+
2006
2519
  async function handleSkills(args) {
2007
2520
  if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
2008
2521
  printSubHelp("skills");
@@ -2012,9 +2525,12 @@ async function handleSkills(args) {
2012
2525
  if (["draft", "propose-update", "keygen", "sign", "promote", "history", "rollback"].includes(subcmd)) {
2013
2526
  return handleSkillsLifecycle(subcmd, rest);
2014
2527
  }
2528
+ if (subcmd === "suggest") {
2529
+ return handleSkillsSuggest(rest);
2530
+ }
2015
2531
  if (!["list", "show", "validate", "lint"].includes(subcmd)) {
2016
2532
  throw new Error(
2017
- `Unknown skills subcommand "${subcmd}". Expected: list, show, validate, lint, draft, propose-update, keygen, sign, promote, history, or rollback.`
2533
+ `Unknown skills subcommand "${subcmd}". Expected: list, show, validate, lint, suggest, draft, propose-update, keygen, sign, promote, history, or rollback.`
2018
2534
  );
2019
2535
  }
2020
2536
 
@@ -2217,6 +2733,106 @@ async function handleSkills(args) {
2217
2733
  return report.passed ? 0 : 1;
2218
2734
  }
2219
2735
 
2736
+ async function handleDoctor(args) {
2737
+ const { values } = parseArgs({
2738
+ args,
2739
+ options: {
2740
+ project: { type: "string", short: "p" },
2741
+ "global-dir": { type: "string" },
2742
+ "include-drafts": { type: "boolean", default: false },
2743
+ "skip-mcp-check": { type: "boolean", default: false },
2744
+ "timeout-ms": { type: "string" },
2745
+ json: { type: "boolean", default: false },
2746
+ help: { type: "boolean", short: "h", default: false },
2747
+ },
2748
+ strict: true,
2749
+ allowPositionals: false,
2750
+ });
2751
+ if (values.help) {
2752
+ printSubHelp("doctor");
2753
+ return 0;
2754
+ }
2755
+ const timeoutMs = values["timeout-ms"] !== undefined ? parseCheckTimeout(values["timeout-ms"]) : undefined;
2756
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
2757
+ const res = await runProjectDoctor({
2758
+ projectDir,
2759
+ harnessDir: HARNESS_DIR,
2760
+ globalSkillsDir: values["global-dir"],
2761
+ includeDrafts: values["include-drafts"],
2762
+ checkMcp: !values["skip-mcp-check"],
2763
+ timeoutMs,
2764
+ });
2765
+ if (values.json) {
2766
+ console.log(JSON.stringify(res, null, 2));
2767
+ return res.healthy ? 0 : 1;
2768
+ }
2769
+ console.log(`GeloForge Doctor : ${res.projectDir} (${res.projectId || "project"}) | harness v${res.harnessVersion}`);
2770
+ console.log(`Health Status : ${res.healthy ? "HEALTHY" : "ISSUES FOUND"} (pass=${res.counts.pass} | warn=${res.counts.warn} | fail=${res.counts.fail})`);
2771
+ console.log("");
2772
+ for (const chk of res.checks) {
2773
+ const tag = chk.status === "pass" ? "[PASS]" : chk.status === "warn" ? "[WARN]" : "[FAIL]";
2774
+ console.log(` ${tag} ${chk.id}: ${chk.summary}`);
2775
+ for (const d of chk.details || []) {
2776
+ console.log(` - ${d}`);
2777
+ }
2778
+ if (chk.fix) {
2779
+ console.log(` Fix: ${chk.fix}`);
2780
+ }
2781
+ }
2782
+ if (res.nextActions.length > 0) {
2783
+ console.log("");
2784
+ console.log("Recommended Next Actions:");
2785
+ for (const cmd of res.nextActions) {
2786
+ console.log(` - ${cmd}`);
2787
+ }
2788
+ }
2789
+ return res.healthy ? 0 : 1;
2790
+ }
2791
+
2792
+ function handleHooks(args) {
2793
+ if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
2794
+ printSubHelp("hooks");
2795
+ return 0;
2796
+ }
2797
+ const [subcmd, ...rest] = args;
2798
+ if (subcmd !== "init") {
2799
+ throw new Error(`Unknown hooks subcommand "${subcmd}". Expected: init.`);
2800
+ }
2801
+ const { values } = parseArgs({
2802
+ args: rest,
2803
+ options: {
2804
+ project: { type: "string", short: "p" },
2805
+ target: { type: "string", multiple: true },
2806
+ "dry-run": { type: "boolean", default: false },
2807
+ json: { type: "boolean", default: false },
2808
+ help: { type: "boolean", short: "h", default: false },
2809
+ },
2810
+ strict: true,
2811
+ allowPositionals: false,
2812
+ });
2813
+ if (values.help) {
2814
+ printSubHelp("hooks");
2815
+ return 0;
2816
+ }
2817
+ const { projectDir } = resolveProjectDir({ project: values.project, harnessDir: HARNESS_DIR });
2818
+ const res = initProjectHooks({
2819
+ projectDir,
2820
+ harnessDir: HARNESS_DIR,
2821
+ targets: values.target?.length ? values.target : HOOK_TARGETS,
2822
+ dryRun: values["dry-run"],
2823
+ });
2824
+ if (values.json) {
2825
+ console.log(JSON.stringify(res, null, 2));
2826
+ return 0;
2827
+ }
2828
+ console.log(res.dryRun ? `Hooks setup preview for ${res.projectDir}` : `Hooks setup for ${res.projectDir}`);
2829
+ for (const file of res.files) {
2830
+ const extra = file.reason ? ` (${file.reason})` : "";
2831
+ console.log(` ${file.target.padEnd(7)} ${file.action.padEnd(10)} ${file.path}${extra}`);
2832
+ }
2833
+ return 0;
2834
+ }
2835
+
2220
2836
  async function main() {
2221
2837
  const argv = process.argv.slice(2);
2222
2838
  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
@@ -2265,6 +2881,24 @@ async function main() {
2265
2881
  case "recommend":
2266
2882
  code = handleRecommend(rest);
2267
2883
  break;
2884
+ case "doctor":
2885
+ code = await handleDoctor(rest);
2886
+ break;
2887
+ case "hooks":
2888
+ code = handleHooks(rest);
2889
+ break;
2890
+ case "autonomous":
2891
+ code = await handleAutonomous(rest);
2892
+ break;
2893
+ case "loop":
2894
+ code = await handleLoop(rest);
2895
+ break;
2896
+ case "proposal":
2897
+ code = handleProposal(rest);
2898
+ break;
2899
+ case "worktree":
2900
+ code = handleWorktree(rest);
2901
+ break;
2268
2902
  case "status":
2269
2903
  code = handleStatus(rest);
2270
2904
  break;