geloforge 0.9.0 → 0.9.1

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,8 +1,8 @@
1
1
  # GeloForge
2
2
 
3
- **Give your AI coding agents a shared memory — and make them prove their work.**
3
+ **Stop re-explaining your codebase — give every AI coding agent a shared, proof-verified memory.**
4
4
 
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.
5
+ Switch freely between **Cursor, Claude Code, VS Code, Codex CLI, Gemini CLI, and Antigravity** without losing architectural context, risking overlapping edits, or trusting hallucinated `"tests pass!"` claims. GeloForge is a local-first, **zero-dependency** CLI and MCP server that keeps project memory, scoped tasks, real test receipts, pinned MCP tools, and portable skills right inside your Git repo.
6
6
 
7
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
8
  [![npm version](https://img.shields.io/npm/v/geloforge?label=npm)](https://www.npmjs.com/package/geloforge)
@@ -10,7 +10,9 @@ Switch freely between **Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, and
10
10
  [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue)](./package.json)
11
11
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
12
12
 
13
- ![Two scripted MCP sessions demonstrating overlapping file leases, verified test evidence, and a signed skill approval.](./docs/media/geloforge-v06-demo.gif)
13
+ **Zero databases. Zero cloud lock-in. Zero external runtime packages.** Just plain Markdown, YAML, and JSON schemas checked into your repository.
14
+
15
+ ![Two scripted MCP sessions demonstrating overlapping file leases, verified test evidence, and a signed skill approval.](https://raw.githubusercontent.com/63L0/GeloForge/main/docs/media/geloforge-v06-demo.gif)
14
16
 
15
17
  *[Read the full multi-session case study & reproduction steps →](./docs/dogfooding-v06.md)*
16
18
 
@@ -18,121 +20,132 @@ Switch freely between **Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, and
18
20
 
19
21
  ## Why GeloForge?
20
22
 
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.
23
+ Every time you open a fresh AI chat or jump from one coding tool to another, hard-won decisions vanish. GeloForge gives your whole stack one deterministic **Second Brain**:
22
24
 
23
25
  | Without GeloForge | With GeloForge |
24
26
  | --- | --- |
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 |
27
+ | Re-explaining specs, architecture, and bugs in every chat | **Contextual BM25 & 3-Zone Packets:** Deterministic context (`brain/` + 15-lang symbol map + skills) in seconds |
28
+ | Agents claiming *"fixed!"* without running tests | **Evidence-Gated Tasks:** Real exit-code receipts (`verify` / `evidence capture`) block fake completion |
29
+ | Two AI tools silently overwriting each other's files | **Cooperative Leases & Worktrees:** Scope claims flag collisions early; Git worktrees isolate parallel work |
30
+ | Surprise MCP tool changes or unreviewed agent habits | **Pinned MCP Tools & Signed Skills:** `mcp lock --check` detects schema drift; skills stay quarantined until approved |
31
+ | Guesswork setup and unnoticed config drift | **Skill Advisor, Doctor & Hooks:** Analyze goals for skills, check health in one command, and run opt-in guardrails |
29
32
 
30
33
  ---
31
34
 
32
35
  ## Quick start
33
36
 
34
- **Prerequisites:** Node.js 20+ and Git installed. Pick whichever path feels easier:
37
+ **Prerequisites:** Node.js 20+ and Git installed (`npx geloforge` works immediately — no global install required).
35
38
 
36
39
  ### Option A — New to CLI? Paste this to your AI coding agent
37
40
 
38
- Copy this into **Cursor, Claude Code, Codex, Gemini CLI, or Antigravity** inside your project folder:
41
+ Open **Cursor, Claude Code, Codex, Gemini CLI, or Antigravity** inside your project folder and paste:
39
42
 
40
43
  ```text
41
44
  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
45
  ```
43
46
 
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
+ > Want ready-to-paste prompts for tasks, tests, checkpoints, and skill drafting? See **[Beginner AI Prompts](./docs/beginner-prompts.md)**.
47
48
 
48
- Run these from the root of any existing project:
49
+ ### Option B — Run the CLI yourself (30 seconds)
49
50
 
50
51
  ```bash
51
- # 1. Preview what files will be added (touches nothing)
52
+ # 1. Preview safely without touching existing code
52
53
  npx geloforge adopt --dry-run
53
54
 
54
- # 2. Add GeloForge Second Brain alongside your code + check health
55
+ # 2. Onboard your repo + run one-command health diagnostics
55
56
  npx geloforge adopt
56
57
  npx geloforge status
57
58
  npx geloforge doctor
58
- ```
59
59
 
60
- **Connect your AI editor and optional ambient hooks:**
61
-
62
- ```bash
60
+ # 3. Connect AI editors (Cursor, VS Code, Claude Code, Gemini CLI, or --client antigravity)
63
61
  npx geloforge mcp init
62
+
63
+ # 4. Preview optional ambient guardrails (Git pre-commit, Claude Stop, Gemini AfterAgent)
64
64
  npx geloforge hooks init --dry-run
65
65
  ```
66
66
 
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.
67
+ Starting from scratch instead? Scaffold an isolated project with one of 5 domain profiles (`web`, `desktop`, `mobile`, `automation`, `ai-system`):
68
68
 
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).
69
+ ```bash
70
+ npx geloforge init --name "My Web App" --profile web --git
71
+ ```
72
+
73
+ > Guides: [5-minute quickstart](./docs/quickstart-5min.md) · [Creating a new project](./docs/new-projects.md)
70
74
 
71
75
  ---
72
76
 
73
77
  ## See it in action
74
78
 
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:
79
+ Use one repeatable proof-backed workflow from goal discovery through verified completion:
76
80
 
77
81
  ```bash
78
- # 1. Define what you're working on and activate it
79
- npx geloforge task new --title "Check input validation" --activate
80
-
81
- # 2. Build a compact, budget-aware context packet (with symbol map)
82
- npx geloforge context --task TASK-0001 --map
82
+ # 1. Discover matching skills or stage a quarantined draft for your goal
83
+ npx geloforge skills suggest --goal "Harden checkout webhook validation"
83
84
 
84
- # 3. Run your test suite — saves verified evidence + checkpoint, then completes the task
85
- npx geloforge verify --task TASK-0001 -- node --test
86
- ```
87
-
88
- Want to record an intermediate check *without* closing the task yet? Run:
85
+ # 2. Create a scoped task and compile a budget-aware context packet + symbol map
86
+ npx geloforge task new --title "Harden checkout webhook validation" --activate
87
+ npx geloforge context --task TASK-0001 --map --skills
89
88
 
90
- ```bash
89
+ # 3. Capture intermediate test receipts (without closing the task yet)
91
90
  npx geloforge evidence capture --task TASK-0001 -- node --test
91
+
92
+ # 4. Verify & complete — fails closed as `draft` if tests fail; saves checkpoint on pass
93
+ npx geloforge verify --task TASK-0001 -- node --test
92
94
  ```
93
95
 
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.
96
+ If any check fails or times out, GeloForge records `draft` evidence (never `verified`) and refuses to mark the task verified until real checks pass.
95
97
 
96
98
  ---
97
99
 
98
100
  ## What you can do
99
101
 
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`.
102
+ ### Smart Memory & Token-Efficient Context
103
+ - **Contextual BM25 & 3-Zone Context Compiler:** `npx geloforge context` ranks Markdown headings and docs with zero-dependency BM25, anchors critical policies/conflicts at edge positions to fight context rot, and supports `quick`/`working`/`deep` budgets, `--from-diff`, `--exclude-unverified`, and opt-in `--cache`.
104
+ - **15+ Language Codebase Symbol Map:** Add `--map` to extract `.gitignore`-aware function/class outlines and 1-hop import boosts (JS/TS, Python, Go, Rust, Java, C#, Kotlin, C/C++, Shell, SQL, Markdown, JSON, YAML, TOML) while hard-blocking `.env*`, keys, binaries, and build folders.
105
+ - **Session Checkpoints & Verified Cross-Agent Handoffs:** Save `CHKPT-NNNN` resume notes (`checkpoint create|resume`) and inspect `HANDOFF-NNNN` packets (`handoff --inspect`) that separate audited `EVID-*` receipts from `unverified_claims` and flag Git HEAD drift.
106
+
107
+ ### Verification, Security & Governance
108
+ - **Command-Backed Evidence & Secret Redaction:** `verify` and `evidence capture` spawn checks directly (`shell: false`), redact detected secrets, and let `task done --require-evidence` block unverified completion.
109
+ - **MCP Tool-Surface Pinning (`mcp lock`):** Snapshot configured stdio MCP server tool schemas to `.geloforge/mcp-lock.json` via canonical SHA-256 digests and run `npx geloforge mcp lock --check` to catch silent tool poisoning or schema drift.
110
+ - **Signed Governance & Zero-Network Reliability:** Gate ADR/constraint edits (`proposal preview|sign|promote`) and skill promotions on pinned Ed25519 keys, transactional rollback journals, cross-process `.state.lock` protection, zero external network calls, and offline regression evals (`npm run eval`).
111
+
112
+ ### Skills, MCP & Multi-Agent Workflows
113
+ - **Project/Goal Skills Advisor (`skills suggest`):** Inspect project markers, active tasks, and `--goal` strings to recommend matching [agentskills.io](https://agentskills.io)-compatible `SKILL.md` workflows, stage quarantined drafts (`--scaffold-draft`), statically security-lint (`skills lint`), and promote/rollback safely (`skills promote|rollback`) with progressive Tier 0/1/2 token loading.
114
+ - **Zero-Dependency MCP Server (`geloforge mcp`):** 6 project-confined MCP tools (`geloforge_status`, `geloforge_recommend`, `geloforge_context`, `geloforge_task`, `geloforge_checkpoint`, `geloforge_skills`) with `--read-only` support, `input_examples`, and self-correcting error hints.
115
+ - **Bounded Coding Loops & Opt-In Staging Audits:** Run capped `implement → verify → review → fix` cycles (`loop run`) gated by fail-closed `policy_checks`, or automate staging error audits (`autonomous watch|learn`) with n8n failure delivery and multi-provider adapters (`codex`, `gemini`, `antigravity`).
116
+ - **Cooperative File Leases & Git Worktrees:** Claim scopes (`task claim --scope src/`) so parallel editors warn on overlapping work automatically, and manage isolated checkouts with `worktree add|remove`.
117
+
118
+ ### Diagnostics & Ambient Guardrails
119
+ - **One-Command Diagnostics (`geloforge doctor`):** Audit Node version, Second Brain schemas (`12` strict JSON schemas), Git state, peer leases, skill lint, MCP lock drift, and hook status with actionable fix commands.
120
+ - **Opt-In Ambient Hooks (`geloforge hooks init`):** Add lightweight Git `pre-commit` validation/lock checks plus Claude Code (`hooks.Stop`) and Gemini CLI (`hooks.AfterAgent`) reminders while preserving existing settings — zero background daemons.
121
+ - **Human-in-the-Loop Co-Pilot (`geloforge recommend`):** Surface ranked next actions, pending skill drafts, open conflicts (`CONF-NNNN`), and active peer leases without auto-executing destructive edits.
107
122
 
108
123
  ---
109
124
 
110
125
  ## How it fits your project
111
126
 
112
- Everything GeloForge adds lives in clear, human-readable folders — never touching your existing source code:
127
+ Everything GeloForge creates lives in readable project folders — never modifying your application source code:
113
128
 
114
- | Folder | What lives here (in plain English) |
129
+ | Folder | Purpose |
115
130
  | --- | --- |
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 |
131
+ | `brain/` | Source of truth: PRD, constraints, architecture decisions (`ADR-*`), and `state/current.yaml` |
132
+ | `tasks/` | Scoped `TASK-NNNN` contracts with objectives, file scope, and acceptance criteria |
133
+ | `evidence/` | Tamper-evident `EVID-NNNN` logs of real commands, exit codes, and redacted outputs |
134
+ | `handoffs/` | Recovery checkpoints (`CHKPT-NNNN`) and structured cross-agent `HANDOFF-NNNN` records |
135
+ | `.agents/skills/` | Reviewed reusable workflows unlocked on demand (`proposals/skills/` isolates unapproved drafts) |
121
136
 
122
137
  ---
123
138
 
124
139
  ## Documentation
125
140
 
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
141
+ - [Beginner AI prompts](./docs/beginner-prompts.md) — ready-to-paste prompts so any AI agent can run GeloForge for you
142
+ - [5-minute quickstart](./docs/quickstart-5min.md) — fastest hands-on CLI walkthrough
143
+ - [CLI and MCP guide](./docs/advanced-usage.md) — full command flags, `mcp lock`, `loop run`, worktrees, and staging audits
144
+ - [Portable Agent Skills](./docs/portable-skills.md) — progressive disclosure, static security lint, and Ed25519 promotion
145
+ - [Creating a new project](./docs/new-projects.md) — greenfield starter templates and 5 domain profiles
146
+ - [Known limitations](./docs/known-limitations.md) & [Security policy](./SECURITY.md) — trust boundaries and offline safety model
132
147
  - [Changelog](./CHANGELOG.md) & [GitHub releases](https://github.com/63L0/GeloForge/releases)
133
148
 
134
149
  ## Contributing
135
150
 
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).
137
-
138
- For local test setup and pull request checks, read the [contribution guide](./CONTRIBUTING.md).
151
+ Issues, bug reports, and pull requests are welcome! Share your OS, Node.js version, and command output via [GitHub Issues](https://github.com/63L0/GeloForge/issues). For local tests and PR checks, read [CONTRIBUTING.md](./CONTRIBUTING.md).
package/VERSION CHANGED
@@ -1 +1 @@
1
- 0.9.0
1
+ 0.9.1
@@ -1,5 +1,5 @@
1
1
  {
2
- "harness_version": "0.9.0",
2
+ "harness_version": "0.9.1",
3
3
  "template_version": "1.0.0",
4
4
  "default_schema_version": "1.1",
5
5
  "supported_schema_versions": ["1.0", "1.1"],
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "geloforge",
3
- "version": "0.9.0",
4
- "description": "Local, provider-neutral CLI for AI coding project memory, command-backed evidence, portable skills, and cross-agent handoffs.",
3
+ "version": "0.9.1",
4
+ "description": "Zero-dependency local CLI & MCP server for AI coding agents — shared project memory, verified test evidence, skill advisor, MCP tool pinning, and cross-agent handoffs.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "repository": {
@@ -15,10 +15,18 @@
15
15
  "keywords": [
16
16
  "ai-coding",
17
17
  "ai-harness",
18
+ "mcp",
19
+ "mcp-server",
18
20
  "agent-skills",
21
+ "coding-agent",
22
+ "claude-code",
23
+ "cursor",
24
+ "codex",
25
+ "gemini-cli",
19
26
  "context-engineering",
20
27
  "project-memory",
21
28
  "cross-agent-handoff",
29
+ "zero-dependency",
22
30
  "developer-tools"
23
31
  ],
24
32
  "engines": {