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.
package/README.md CHANGED
@@ -1,141 +1,138 @@
1
1
  # GeloForge
2
2
 
3
- **Keep your AI coding work understandable, portable, and verifiable.**
3
+ **Give your AI coding agents a shared memory — and make them prove their work.**
4
4
 
5
- [![CI](https://github.com/63L0/GeloForge/actions/workflows/ci.yml/badge.svg)](https://github.com/63L0/GeloForge/actions/workflows/ci.yml)
6
- [![Latest release](https://img.shields.io/github/v/release/63L0/GeloForge?label=release)](https://github.com/63L0/GeloForge/releases/latest)
7
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
8
-
9
- ![15-second GeloForge terminal replay showing MCP setup, an overlapping lease blocked, verified evidence, and a signed skill approval](./docs/media/geloforge-v06-demo.gif)
5
+ Switch freely between **Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, and Antigravity** without re-explaining your codebase or trusting unverified `"tests pass"` claims. GeloForge is a local-first, **zero-dependency** CLI + MCP server that stores decisions, scoped tasks, real command evidence, and clean handoffs right inside your repo.
10
6
 
11
- [Read and replay the GeloForge worktree case study](./docs/dogfooding-v06.md).
12
-
13
- When an AI coding session ends, important decisions, unfinished work, and test results are easy to lose. **GeloForge keeps that knowledge in your repository**, not trapped inside one assistant's chat.
7
+ [![CI on main](https://github.com/63L0/GeloForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/63L0/GeloForge/actions/workflows/ci.yml)
8
+ [![npm version](https://img.shields.io/npm/v/geloforge?label=npm)](https://www.npmjs.com/package/geloforge)
9
+ [![Node 20+](https://img.shields.io/badge/node-20%2B-brightgreen)](https://nodejs.org/)
10
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue)](./package.json)
11
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
14
12
 
15
- It's a small, open-source **command-line toolkit** for project memory, task tracking, verified command results, reusable agent skills, and handoffs between coding assistants. Built with Node.js, with **no paid API, hosted service, or third-party runtime dependencies**.
13
+ ![Two scripted MCP sessions demonstrating overlapping file leases, verified test evidence, and a signed skill approval.](./docs/media/geloforge-v06-demo.gif)
16
14
 
17
- **[Get started](#quick-start)** · **[See a workflow](#see-it-in-action)** · **[Read the docs](#documentation)** · **[Contribute](#contributing)**
15
+ *[Read the full multi-session case study & reproduction steps →](./docs/dogfooding-v06.md)*
18
16
 
19
- > **What GeloForge is not:** An AI model, autonomous coding agent, or automatic connection to your IDE. It prepares and validates files that you and your preferred AI coding tools can use.
17
+ ---
20
18
 
21
19
  ## Why GeloForge?
22
20
 
23
- | Without a shared record | With GeloForge |
21
+ When you start a fresh AI chat or switch tools, yesterday’s context disappears. **GeloForge fixes that with plain Markdown/YAML files in your repo** — zero databases, zero cloud lock-in, and zero third-party runtime packages.
22
+
23
+ | Without GeloForge | With GeloForge |
24
24
  | --- | --- |
25
- | A new chat has to relearn the project. | Build a focused context packet from project files. |
26
- | "Tests passed" is just something an agent said. | Capture the actual command, exit status, and evidence. |
27
- | Switching coding assistants loses the thread. | Hand over the task, verified results, and next actions. |
28
- | Useful fixes stay buried in old conversations. | Draft portable `SKILL.md` workflows, review them, and reuse them. |
25
+ | Re-explaining architecture & constraints in every new chat | **Compiled Context:** One deterministic packet (`brain/` + codebase map + skills) in seconds |
26
+ | Agents claiming *"fixed!"* without running tests | **Verified Evidence:** Real exit-code command checks (`verify` / `evidence capture`) gate task completion |
27
+ | Two AI tools overwriting each other's files | **Cooperative Leases:** Scope locks flag overlapping edits before files collide |
28
+ | Surprise MCP tool changes or unreviewed agent habits | **Pinned Tools & Signed Skills:** `mcp lock --check` catches tool drift; skills require owner approval |
29
29
 
30
- You stay in control of changes and approvals. GeloForge helps organize the work; it does **not** silently run or authorize AI-generated instructions.
30
+ ---
31
31
 
32
32
  ## Quick start
33
33
 
34
- **Requires:** Node.js **20+** and Git. Works on Windows, macOS, and Linux.
34
+ **Prerequisites:** Node.js 20+ and Git installed. Pick whichever path feels easier:
35
35
 
36
- Once v0.6 is available on npm, run these commands inside your existing project:
36
+ ### Option A — New to CLI? Paste this to your AI coding agent
37
37
 
38
- ```bash
39
- npx geloforge adopt --dry-run
40
- npx geloforge adopt
41
- npx geloforge status
38
+ Copy this into **Cursor, Claude Code, Codex, Gemini CLI, or Antigravity** inside your project folder:
39
+
40
+ ```text
41
+ Set up GeloForge in this repository safely. First run `npx geloforge adopt --dry-run` and explain what files will be added without modifying my existing code. After I confirm, run `npx geloforge adopt`, `npx geloforge mcp init`, `npx geloforge hooks init --dry-run`, and `npx geloforge doctor`. Then run `npx geloforge skills suggest` to recommend matching skills and ask what my first goal is. Do NOT edit my app code or auto-promote skills.
42
42
  ```
43
43
 
44
- For the current GitHub release, clone GeloForge and link the CLI:
44
+ > Want ready-to-paste prompts for daily tasks, tests, and checkpoints? See **[Beginner AI Prompts](./docs/beginner-prompts.md)**.
45
+
46
+ ### Option B — Run the CLI yourself
47
+
48
+ Run these from the root of any existing project:
45
49
 
46
50
  ```bash
47
- git clone https://github.com/63L0/GeloForge.git
48
- cd GeloForge
49
- npm link
50
- geloforge --version
51
+ # 1. Preview what files will be added (touches nothing)
52
+ npx geloforge adopt --dry-run
53
+
54
+ # 2. Add GeloForge Second Brain alongside your code + check health
55
+ npx geloforge adopt
56
+ npx geloforge status
57
+ npx geloforge doctor
51
58
  ```
52
59
 
53
- Then go to **your existing project**:
60
+ **Connect your AI editor and optional ambient hooks:**
54
61
 
55
62
  ```bash
56
- cd /path/to/your-project
57
- geloforge adopt --dry-run # Preview changes first
58
- geloforge adopt # Add project memory without overwriting your code
59
- geloforge status
63
+ npx geloforge mcp init
64
+ npx geloforge hooks init --dry-run
60
65
  ```
61
66
 
62
- That's it. Your project now has its own file-based starting point. GeloForge's CLI works from the project root or a nested directory.
67
+ This configures **Cursor, VS Code, Claude Code, and Gemini CLI** (add `--client antigravity` for Antigravity) and previews opt-in Git/agent hooks. Open your project, approve the folder's MCP prompt, and your agents can read tasks, context, and evidence automatically.
63
68
 
64
- You can also run `node scripts/geloforge.mjs --help` from the GeloForge checkout, or invoke the script by its full path from any directory.
69
+ > Starting a brand-new project instead? See [Creating a new project](./docs/new-projects.md) or try the [5-minute quickstart](./docs/quickstart-5min.md).
65
70
 
66
- [Follow the 5-minute walkthrough →](./docs/quickstart-5min.md)
71
+ ---
67
72
 
68
73
  ## See it in action
69
74
 
70
- Here's a typical workflow after adopting a project:
75
+ Here is the everyday 3-step loop — create a scoped task, hand your AI focused context, and require a passing test before marking it done:
71
76
 
72
77
  ```bash
73
- # 1. Give the next coding session a clear task.
74
- geloforge task new --title "Fix login validation" --activate
78
+ # 1. Define what you're working on and activate it
79
+ npx geloforge task new --title "Check input validation" --activate
75
80
 
76
- # 2. Build a focused packet with relevant files and reusable skills.
77
- geloforge context --task TASK-0001 --map --skills
81
+ # 2. Build a compact, budget-aware context packet (with symbol map)
82
+ npx geloforge context --task TASK-0001 --map
78
83
 
79
- # 3. Run your check, save a checkpoint, and complete the task if it passes.
80
- geloforge verify -- node --test
84
+ # 3. Run your test suite — saves verified evidence + checkpoint, then completes the task
85
+ npx geloforge verify --task TASK-0001 -- node --test
81
86
  ```
82
87
 
83
- Replace `node --test` with your project's test command. To record a check while keeping a task open, run `geloforge evidence capture --task TASK-0001 -- node --test`.
88
+ Want to record an intermediate check *without* closing the task yet? Run:
84
89
 
85
- When you're done, use `geloforge handoff` to record what changed, what was verified, and what the next developer or assistant should do. [See the handoff examples →](./docs/advanced-usage.md)
90
+ ```bash
91
+ npx geloforge evidence capture --task TASK-0001 -- node --test
92
+ ```
86
93
 
87
- ## What you can do
94
+ If a check fails or times out, GeloForge marks the evidence as `draft` (never `verified`) and keeps the task open until the real test passes.
88
95
 
89
- | Capability | What it means for you |
90
- | --- | --- |
91
- | **Project memory** | Keep decisions, requirements, and current state in Markdown/YAML inside your repository. |
92
- | **Safe onboarding** | Add GeloForge to an existing codebase with `adopt` or scaffold a new one with `init`. |
93
- | **Tasks + evidence** | Create scoped tasks and capture real command results instead of relying on AI claims. |
94
- | **Context + code map** | Send a smaller, more relevant project summary to your chosen AI assistant. |
95
- | **Cross-agent handoff** | Pass structured, checkable work between sessions or tools. |
96
- | **Portable Agent Skills** | Use open-format `SKILL.md` packages, with validation and progressive loading. |
97
- | **Reviewed skill improvements** | Draft improvements from evidence, require explicit authorization, track versions, and roll back. |
98
- | **Co-Pilot & checkpoints** | Get ranked next steps, human approval reminders, and resumable session notes. |
99
- | **Cooperative multi-IDE work** | Claim tasks and scopes, see peer collision warnings, and avoid accidental overlapping work. |
100
- | **Local MCP interface** | Run `geloforge mcp init` to set up Cursor, VS Code, Claude Code, or Gemini CLI with project-scoped tools. |
101
-
102
- **Compatible workflow:** Codex, Claude Code, Gemini CLI, Antigravity, or any assistant that can read text you provide. GeloForge does not automatically operate or connect to those tools.
96
+ ---
103
97
 
104
- ## How it fits your project
98
+ ## What you can do
105
99
 
106
- GeloForge stores its records **alongside your code**, so you can inspect, version, and share them through Git:
100
+ - **Coordinate across AI tools** — Claim a file scope (`task claim --scope src/`) so parallel Cursor, Codex, or Claude sessions warn each other before editing the same files.
101
+ - **Pause and resume without losing context** — Save lightweight checkpoints (`checkpoint create`) or structured handoffs (`handoff`) carrying exact evidence IDs and next actions.
102
+ - **Pin MCP tool definitions** — Lock configured stdio MCP servers to `.geloforge/mcp-lock.json` and run `npx geloforge mcp lock --check` to catch added, removed, or silently altered tool schemas.
103
+ - **Run bounded coding loops** — Use `npx geloforge loop run --config <file>` for a capped `implement → verify → review → fix` cycle where failing tests always block completion.
104
+ - **Analyze & suggest skills** — Run `npx geloforge skills suggest` (or `--scaffold-draft`) to match existing skills and stage quarantined drafts for owner review and Ed25519 approval.
105
+ - **Check setup health in one command** — Run `npx geloforge doctor` for pass/warn/fail diagnostics with exact fixes, or `npx geloforge hooks init` to add lightweight Git, Claude Code, or Gemini CLI checks.
106
+ - **Isolate parallel work cleanly** — Manage clean-checked Git worktrees under `worktrees/` with `npx geloforge worktree add`.
107
107
 
108
- ```text
109
- your-project/
110
- ├── brain/ # Decisions, constraints, and project state
111
- ├── tasks/ # What needs to be done
112
- ├── evidence/ # Recorded checks (created when needed)
113
- ├── handoffs/ # Session/agent transfers (created when needed)
114
- └── .agents/skills/ # Optional reusable SKILL.md packages
115
- ```
108
+ ---
116
109
 
117
- You can use one AI assistant or switch between several. **No new backend, database, or model subscription is required.**
110
+ ## How it fits your project
118
111
 
119
- ## Documentation
112
+ Everything GeloForge adds lives in clear, human-readable folders — never touching your existing source code:
120
113
 
121
- | Start here | For |
114
+ | Folder | What lives here (in plain English) |
122
115
  | --- | --- |
123
- | [5-minute quickstart](./docs/quickstart-5min.md) | Your first working project |
124
- | [Detailed CLI & technical guide](./docs/advanced-usage.md) | Every major workflow and command |
125
- | [Portable Skills guide](./docs/portable-skills.md) | `SKILL.md`, validation, approvals, and rollback |
126
- | [Creating a new project](./docs/new-projects.md) | Profiles and project scaffolding |
127
- | [Known limitations](./docs/known-limitations.md) | What is and is not guaranteed |
128
- | [Security policy](./SECURITY.md) | Risks, trust boundaries, and reporting |
129
- | [Changelog](./CHANGELOG.md) | What's changed in each release |
116
+ | `brain/` | Your project's source of truth: architecture, constraints, decisions, and `current.yaml` state |
117
+ | `tasks/` | Scoped `TASK-NNNN` contracts with clear objectives, file scope, and acceptance criteria |
118
+ | `evidence/` | Tamper-evident `EVID-NNNN` logs of actual commands, exit codes, and outputs |
119
+ | `handoffs/` | Recovery checkpoints (`CHKPT-NNNN`) and cross-agent `HANDOFF-NNNN` notes |
120
+ | `.agents/skills/` | Reviewed, reusable agent workflows unlocked on demand to save tokens |
130
121
 
131
- **Security note:** A local AI agent with unrestricted filesystem access can still bypass local file-level controls. Signing a skill does not prove an *independent human* approved it unless keys and enforcement are outside that agent's control. Skills linting is not a sandbox.
122
+ ---
132
123
 
133
- ## Contributing
124
+ ## Documentation
134
125
 
135
- GeloForge is **MIT-licensed** and built to be useful beyond one person's workflow.
126
+ - [Beginner AI prompts](./docs/beginner-prompts.md) — ready-to-paste prompts to let your AI agent set up and run GeloForge
127
+ - [5-minute quickstart](./docs/quickstart-5min.md) — fastest hands-on walkthrough for beginners
128
+ - [CLI and MCP guide](./docs/advanced-usage.md) — full command reference, MCP init/lock, worktrees, and coding loops
129
+ - [Portable Agent Skills](./docs/portable-skills.md) — progressive disclosure, linting, and Ed25519 skill promotion
130
+ - [Creating a new project](./docs/new-projects.md) — templates and domain profiles (`web`, `automation`, `desktop`, etc.)
131
+ - [Known limitations](./docs/known-limitations.md) & [Security policy](./SECURITY.md) — threat model, zero-network guarantees, and secret redaction
132
+ - [Changelog](./CHANGELOG.md) & [GitHub releases](https://github.com/63L0/GeloForge/releases)
136
133
 
137
- Have an idea, find a confusing command, or hit a bug? [Open an issue](https://github.com/63L0/GeloForge/issues) or read [CONTRIBUTING.md](./CONTRIBUTING.md) to submit a pull request.
134
+ ## Contributing
138
135
 
139
- If this helps your AI-assisted development workflow, consider **[starring the repository](https://github.com/63L0/GeloForge)** so you can find it again.
136
+ Issues, bug reports, and pull requests are welcome! When reporting an issue, please share your OS, Node.js version, and the exact command you ran via [GitHub Issues](https://github.com/63L0/GeloForge/issues).
140
137
 
141
- **Latest published release:** [GitHub Releases](https://github.com/63L0/GeloForge/releases/latest) · [MIT License](./LICENSE)
138
+ For local test setup and pull request checks, read the [contribution guide](./CONTRIBUTING.md).
package/VERSION CHANGED
@@ -1 +1 @@
1
- 0.6.0
1
+ 0.9.0
@@ -0,0 +1,132 @@
1
+ {
2
+ "name": "GeloForge Staging Failure Delivery",
3
+ "active": false,
4
+ "nodes": [
5
+ {
6
+ "id": "11c36462-4033-40dd-8557-7f4f9c7ad010",
7
+ "name": "Staging Error Trigger",
8
+ "type": "n8n-nodes-base.errorTrigger",
9
+ "typeVersion": 1,
10
+ "position": [
11
+ 0,
12
+ 280
13
+ ],
14
+ "parameters": {}
15
+ },
16
+ {
17
+ "id": "11c36462-4033-40dd-8557-7f4f9c7ad011",
18
+ "name": "Select staging failure IDs",
19
+ "type": "n8n-nodes-base.code",
20
+ "typeVersion": 2,
21
+ "position": [
22
+ 230,
23
+ 280
24
+ ],
25
+ "parameters": {
26
+ "jsCode": "const valid = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);\nconst event = $input.first().json;\nconst workflowId = String(event.workflow?.id ?? '');\nconst executionId = String(event.execution?.id ?? '');\nif (!valid(workflowId) || !valid(executionId)) return [];\nreturn [{ json: { workflowId, executionId } }];"
27
+ }
28
+ },
29
+ {
30
+ "id": "11c36462-4033-40dd-8557-7f4f9c7ad012",
31
+ "name": "Get saved staging execution",
32
+ "type": "n8n-nodes-base.n8n",
33
+ "typeVersion": 1,
34
+ "position": [
35
+ 460,
36
+ 280
37
+ ],
38
+ "parameters": {
39
+ "resource": "execution",
40
+ "operation": "get",
41
+ "executionId": "={{ $json.executionId }}",
42
+ "options": {
43
+ "activeWorkflows": true
44
+ }
45
+ },
46
+ "onError": "continueRegularOutput"
47
+ },
48
+ {
49
+ "id": "11c36462-4033-40dd-8557-7f4f9c7ad013",
50
+ "name": "Project audit evidence",
51
+ "type": "n8n-nodes-base.code",
52
+ "typeVersion": 2,
53
+ "position": [
54
+ 690,
55
+ 280
56
+ ],
57
+ "parameters": {
58
+ "jsCode": "const ids = $('Select staging failure IDs').first().json;\nconst raw = $input.first().json;\nconst revision = raw.workflowVersionId ?? raw.workflowData?.versionId;\nconst result = raw.data?.resultData;\nconst runData = result?.runData;\nconst workflowNodes = raw.workflowData?.nodes;\nconst nodes = Array.isArray(workflowNodes) ? workflowNodes.map(node => node?.name ?? null) : null;\nconst matches = String(raw.id ?? '') === ids.executionId &&\n String(raw.workflowId ?? '') === ids.workflowId && raw.status === 'error';\nconst delivery = {\n environment: 'staging',\n ...ids,\n execution: matches ? {\n id: ids.executionId,\n workflowId: ids.workflowId,\n revision,\n status: raw.status,\n nodes,\n executed: runData && typeof runData === 'object' && !Array.isArray(runData) ? Object.keys(runData) : null,\n failedNode: result?.lastNodeExecuted ?? null,\n } : null,\n};\nconst deliveryId = String($execution.id ?? '');\nif (!/^[A-Za-z0-9_-]{1,64}$/.test(deliveryId)) throw new Error('Expected a saved delivery ID.');\nconst fileName = `failure-${ids.workflowId}-${ids.executionId}-${deliveryId}.json`;\nreturn [{\n json: { fileName },\n binary: { data: {\n data: Buffer.from(JSON.stringify(delivery), 'utf8').toString('base64'),\n mimeType: 'application/json',\n fileName,\n } },\n}];"
59
+ }
60
+ },
61
+ {
62
+ "id": "11c36462-4033-40dd-8557-7f4f9c7ad014",
63
+ "name": "Write audit delivery",
64
+ "type": "n8n-nodes-base.readWriteFile",
65
+ "typeVersion": 1,
66
+ "position": [
67
+ 920,
68
+ 280
69
+ ],
70
+ "parameters": {
71
+ "operation": "write",
72
+ "dataPropertyName": "data",
73
+ "fileName": "={{ '/files/geloforge-inbox/' + $json.fileName }}",
74
+ "options": {}
75
+ }
76
+ }
77
+ ],
78
+ "pinData": {},
79
+ "connections": {
80
+ "Staging Error Trigger": {
81
+ "main": [
82
+ [
83
+ {
84
+ "node": "Select staging failure IDs",
85
+ "type": "main",
86
+ "index": 0
87
+ }
88
+ ]
89
+ ]
90
+ },
91
+ "Select staging failure IDs": {
92
+ "main": [
93
+ [
94
+ {
95
+ "node": "Get saved staging execution",
96
+ "type": "main",
97
+ "index": 0
98
+ }
99
+ ]
100
+ ]
101
+ },
102
+ "Get saved staging execution": {
103
+ "main": [
104
+ [
105
+ {
106
+ "node": "Project audit evidence",
107
+ "type": "main",
108
+ "index": 0
109
+ }
110
+ ]
111
+ ]
112
+ },
113
+ "Project audit evidence": {
114
+ "main": [
115
+ [
116
+ {
117
+ "node": "Write audit delivery",
118
+ "type": "main",
119
+ "index": 0
120
+ }
121
+ ]
122
+ ]
123
+ }
124
+ },
125
+ "settings": {
126
+ "executionOrder": "v1",
127
+ "saveDataErrorExecution": "none",
128
+ "saveDataSuccessExecution": "none",
129
+ "saveManualExecutions": false,
130
+ "saveExecutionProgress": false
131
+ }
132
+ }
@@ -0,0 +1,68 @@
1
+ import fs from "node:fs";
2
+ import { AUDIT_CREATOR } from "./autonomous-audit.mjs";
3
+ import { assertSafeWithinRoot, validateSlug } from "./path-safety.mjs";
4
+ import { loadProjectManifestAndState } from "./project-locator.mjs";
5
+ import { withProjectLock } from "./project-lock.mjs";
6
+ import { readRuntimeJson, sha256 } from "./runtime-files.mjs";
7
+ import { draftSkillFromExperience, loadVerifiedSourceBundle, proposeSkillUpdate } from "./skills-lifecycle.mjs";
8
+ import { reportArtifactPath } from "./staging-audit.mjs";
9
+ import { verifyStagingReport } from "./staging-evidence.mjs";
10
+ import { getTask, listTasks } from "./task-manager.mjs";
11
+
12
+ export function learnFromStagingAudits({ projectDir, harnessDir, patternId, skillName, step }) {
13
+ const read = () => {
14
+ const project = loadProjectManifestAndState(projectDir, harnessDir);
15
+ const patterns = new Map();
16
+ const warnings = [];
17
+ for (const { id } of listTasks({ ...project, harnessDir, status: "completed" }).tasks) {
18
+ const { record } = getTask({ ...project, harnessDir, taskId: id });
19
+ if (record.created_by !== AUDIT_CREATOR) continue;
20
+ const artifact = reportArtifactPath(project.projectPaths, id);
21
+ try {
22
+ const source = readRuntimeJson(projectDir, artifact);
23
+ if (!source) continue;
24
+ const report = verifyStagingReport(source, id);
25
+ const { evidenceList } = loadVerifiedSourceBundle({ projectDir, harnessDir, evidenceIds: record.evidence_refs });
26
+ const evidence = evidenceList.find(({ data }) => data.task_id === id && data.verified_by === "geloforge-staging-report" &&
27
+ data.artifacts.some(({ path, sha256: digest }) => path === artifact && digest));
28
+ if (!evidence) throw new Error("Missing evidence binding.");
29
+ for (const { workflowId, node, pattern, reference } of report.findings) {
30
+ // A node definition gives useful context, but it does not show a recurring failure.
31
+ if (!node || reference !== "failed-at") continue;
32
+ const key = sha256(JSON.stringify([workflowId, node, pattern])).slice(0, 16);
33
+ if (!patterns.has(key)) patterns.set(key, { id: key, workflowId, node, pattern, executions: new Map() });
34
+ patterns.get(key).executions.set(report.executionId, {
35
+ executionId: report.executionId, evidenceId: evidence.data.id, revision: report.execution.revision,
36
+ });
37
+ }
38
+ } catch {
39
+ warnings.push(`Excluded ${id} because its report or evidence could not be verified.`);
40
+ }
41
+ }
42
+ const recurring = [...patterns.values()].filter((pattern) => pattern.executions.size >= 2)
43
+ .map(({ executions, ...pattern }) => ({ ...pattern, executions: [...executions.values()] }));
44
+ return { patterns: recurring, warnings };
45
+ };
46
+ if (!patternId) {
47
+ if (skillName || step) throw new Error("Use --pattern before drafting a skill.");
48
+ return read();
49
+ }
50
+ return withProjectLock(projectDir, () => {
51
+ validateSlug(skillName);
52
+ const result = read();
53
+ const pattern = result.patterns.find(({ id }) => id === patternId);
54
+ if (!pattern) throw new Error("Recurring pattern is missing or its evidence is no longer verified.");
55
+ const evidenceIds = pattern.executions.map(({ evidenceId }) => evidenceId);
56
+ const note = step ?? `For ${pattern.pattern} failures in workflow ${pattern.workflowId}, check whether ${pattern.node} is the failing node and confirm the saved execution and revision before recommending a fix.`;
57
+ const options = { projectDir, harnessDir, evidenceIds, skillName };
58
+ const active = assertSafeWithinRoot(projectDir, `.agents/skills/${skillName}/SKILL.md`);
59
+ const proposal = fs.existsSync(active)
60
+ ? proposeSkillUpdate({ ...options, reason: "Review a recurring staging failure pattern.", appendNote: note })
61
+ : draftSkillFromExperience({
62
+ ...options, title: "Investigate recurring n8n staging failures",
63
+ description: "Review the saved n8n staging execution and confirm recurring failures against linked evidence.",
64
+ steps: [note], tags: ["n8n", "staging", pattern.pattern], triggers: ["n8n", "audit", pattern.pattern],
65
+ });
66
+ return { pattern, proposalDir: proposal.proposalDir, nextAction: "Review the draft, then use the existing skill signing and promotion commands." };
67
+ });
68
+ }
@@ -0,0 +1,157 @@
1
+ /** Headless audit adapters run outside the project and receive a bounded context packet. */
2
+ import fs from "node:fs";
3
+ import os from "node:os";
4
+ import path from "node:path";
5
+ import { execFile } from "node:child_process";
6
+ import { hasSecretContent, isForbiddenSecretPath, isSameOrInside } from "./path-safety.mjs";
7
+ import { readRegularFile, sha256 } from "./runtime-files.mjs";
8
+
9
+ const ENV_KEYS = new Set([
10
+ "PATH", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "SYSTEMROOT", "WINDIR",
11
+ "TMP", "TEMP", "TMPDIR", "LANG", "LC_ALL",
12
+ ]);
13
+
14
+ export function executableIdentity(executable) {
15
+ const stat = fs.lstatSync(executable);
16
+ if (!stat.isFile()) throw new Error("Audit provider must be a regular executable file.");
17
+ return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
18
+ }
19
+
20
+ export function buildProviderEnv(provider, extraEnv = null) {
21
+ const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => ENV_KEYS.has(key.toUpperCase())));
22
+ if (provider === "gemini") env.GEMINI_CLI_TRUST_WORKSPACE = "true";
23
+ if (extraEnv && typeof extraEnv === "object") {
24
+ for (const [k, v] of Object.entries(extraEnv)) {
25
+ if (typeof v === "string") env[k] = v;
26
+ }
27
+ }
28
+ return env;
29
+ }
30
+
31
+ export function resolveAuditProvider(spec, projectDir) {
32
+ if (!spec || !["codex", "gemini", "antigravity"].includes(spec.provider) ||
33
+ typeof spec.executable !== "string" || !path.isAbsolute(spec.executable) ||
34
+ hasSecretContent(spec.executable) || isForbiddenSecretPath(spec.executable)) {
35
+ throw new Error("Supply a provider and absolute CLI executable path.");
36
+ }
37
+ const executable = fs.realpathSync(spec.executable);
38
+ if (isSameOrInside(executable, fs.realpathSync(projectDir)) || /\.(cmd|bat|ps1)$/i.test(executable)) {
39
+ throw new Error("Use a native provider executable or Node.js entry point outside the project.");
40
+ }
41
+ const identity = executableIdentity(executable);
42
+ const bytes = readRegularFile(executable, 384 * 1024 * 1024);
43
+ if (!bytes || executableIdentity(executable) !== identity) {
44
+ throw new Error("Configured provider executable is unavailable or changed during authorization.");
45
+ }
46
+ const runner = { provider: spec.provider, executable, digest: sha256(bytes) };
47
+ return { runner, identity };
48
+ }
49
+
50
+ /**
51
+ * Spawns an approved provider CLI executable with filtered environment, closed stdin payload,
52
+ * and automatic private temp-dir cleanup.
53
+ */
54
+ export function runProviderProcess({
55
+ runner: { provider, executable },
56
+ identity,
57
+ prompt,
58
+ cwd = null,
59
+ inputFile = "audit-input.txt",
60
+ buildArgs,
61
+ timeoutMs,
62
+ signal,
63
+ requireJson = true,
64
+ }) {
65
+ if (signal?.aborted) throw new Error("Audit worker is stopping.");
66
+ if (executableIdentity(executable) !== identity) {
67
+ throw new Error("Audit provider executable changed. Restart with the approved executable.");
68
+ }
69
+ if (hasSecretContent(prompt)) throw new Error("Audit inputs contain credential-like content.");
70
+ const tempDir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "geloforge-audit-"));
71
+ const finalPath = path.join(tempDir, "response.json");
72
+ const promptPath = path.join(tempDir, inputFile);
73
+ const workCwd = cwd ? fs.realpathSync(cwd) : tempDir;
74
+ let child;
75
+ const args = buildArgs({ finalPath, promptPath, provider });
76
+ const env = buildProviderEnv(provider);
77
+ const stop = () => child?.kill("SIGKILL");
78
+ const promise = new Promise((resolve, reject) => {
79
+ try {
80
+ fs.writeFileSync(promptPath, prompt, { mode: 0o600, flag: "wx" });
81
+ const isNodeEntry = /\.[cm]?js$/i.test(executable);
82
+ child = execFile(isNodeEntry ? process.execPath : executable, isNodeEntry ? [executable, ...args] : args, {
83
+ cwd: workCwd, env, timeout: timeoutMs, maxBuffer: 512 * 1024, killSignal: "SIGKILL", windowsHide: true,
84
+ }, (err, stdout) => {
85
+ try {
86
+ if (err) {
87
+ throw new Error(err.killed ? "Audit provider stopped or exceeded its timeout." :
88
+ "Audit provider failed to start or returned an unsuccessful response.");
89
+ }
90
+ const text = provider === "codex" ? (readRegularFile(finalPath)?.toString("utf8") ?? "") : String(stdout ?? "");
91
+ if (provider === "codex") {
92
+ let parsed = null;
93
+ try {
94
+ parsed = JSON.parse(text);
95
+ } catch {
96
+ if (requireJson) throw new Error("Audit provider returned invalid JSON.");
97
+ resolve({ parsed: null, rawText: text });
98
+ return;
99
+ }
100
+ if (parsed?.error) throw new Error("Unsuccessful response envelope.");
101
+ resolve(requireJson ? parsed : { parsed, rawText: text });
102
+ return;
103
+ }
104
+ let envelope = null;
105
+ try {
106
+ envelope = JSON.parse(text);
107
+ } catch {
108
+ if (requireJson) throw new Error("Audit provider returned invalid JSON.");
109
+ resolve({ parsed: null, rawText: text });
110
+ return;
111
+ }
112
+ if (envelope?.error || (provider === "antigravity" && envelope?.status !== "SUCCESS")) {
113
+ throw new Error("Unsuccessful response envelope.");
114
+ }
115
+ const innerRaw = typeof envelope.response === "string" ? envelope.response : JSON.stringify(envelope.response ?? "");
116
+ try {
117
+ const innerParsed = JSON.parse(innerRaw);
118
+ resolve(requireJson ? innerParsed : { parsed: innerParsed, rawText: innerRaw });
119
+ } catch {
120
+ if (requireJson) throw new Error("Audit provider returned invalid JSON.");
121
+ resolve({ parsed: null, rawText: innerRaw });
122
+ }
123
+ } catch (error) {
124
+ reject(err ? error : error);
125
+ }
126
+ });
127
+ child.stdin?.on("error", () => {});
128
+ child.stdin?.end(prompt, "utf8");
129
+ signal?.addEventListener("abort", stop, { once: true });
130
+ } catch (err) {
131
+ reject(err);
132
+ }
133
+ }).finally(() => {
134
+ signal?.removeEventListener("abort", stop);
135
+ fs.rmSync(tempDir, { recursive: true, force: true, maxRetries: 2 });
136
+ });
137
+ return { pid: child?.pid, promise, stop };
138
+ }
139
+
140
+ export function startAuditProvider(resolvedProvider, prompt, { timeoutMs, signal } = {}) {
141
+ const request = "Follow the reporting format in the audit input provided on stdin (also saved in audit-input.txt) and return only the requested JSON. Do not run shell commands or modify files.";
142
+ return runProviderProcess({
143
+ ...resolvedProvider,
144
+ prompt,
145
+ cwd: null,
146
+ inputFile: "audit-input.txt",
147
+ timeoutMs,
148
+ signal,
149
+ requireJson: true,
150
+ buildArgs: ({ finalPath, provider }) => ({
151
+ codex: ["--ask-for-approval", "never", "exec", "--sandbox", "read-only", "--skip-git-repo-check",
152
+ "--ephemeral", "--ignore-user-config", "--output-last-message", finalPath, request],
153
+ gemini: ["--approval-mode=plan", "--output-format=json", "--prompt", request],
154
+ antigravity: ["--mode=plan", "--sandbox", "--output-format=json", "--print", request],
155
+ }[provider]),
156
+ });
157
+ }