diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 40ef460..1fd657e 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "forgekit", "displayName": "Forge", - "version": "0.3.1", + "version": "0.4.0", "description": "One config, every AI coding tool — cognitive substrate, tools, crew, guards, atlas, lean, recall from one source.", "author": { "name": "CodeWithJuber" }, "license": "MIT", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index ff0d99c..73b316e 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "forgekit", - "version": "0.3.1", + "version": "0.4.0", "description": "One config, every AI coding tool — cognitive substrate, MCP tools, guards, atlas, recall, and routing from one source.", "author": { "name": "CodeWithJuber", "url": "https://github.com/CodeWithJuber" }, "homepage": "https://github.com/CodeWithJuber/forgekit#readme", diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..a4167be --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,38 @@ +# Canonical issue/PR labels, synced by .github/workflows/labels.yml. +# Edit here (not in the GitHub UI) so the set stays reproducible. +- name: bug + color: d73a4a + description: Something isn't working +- name: enhancement + color: a2eeef + description: New feature or request +- name: documentation + color: 0075ca + description: Improvements or additions to docs +- name: question + color: d876e3 + description: Further information is requested +- name: good first issue + color: 7057ff + description: Good for newcomers +- name: help wanted + color: 008672 + description: Extra attention is wanted +- name: dependencies + color: 0366d6 + description: Dependency updates (Dependabot) +- name: github-actions + color: 000000 + description: CI / GitHub Actions changes +- name: security + color: b60205 + description: Security-sensitive report or fix +- name: accessibility + color: 5319e7 + description: Accessibility (a11y) report or fix +- name: stale + color: cccccc + description: Inactive; will be closed if it stays quiet +- name: pinned + color: fbca04 + description: Exempt from the stale bot diff --git a/.github/workflows/labels.yml b/.github/workflows/labels.yml new file mode 100644 index 0000000..63b7bc7 --- /dev/null +++ b/.github/workflows/labels.yml @@ -0,0 +1,24 @@ +# Sync repo labels from .github/labels.yml (the labels the templates, Dependabot, +# and the stale bot reference). Runs on change + on demand. Uses the default token +# (label management needs write, not admin). +name: Labels + +on: + push: + branches: [master] + paths: [".github/labels.yml", ".github/workflows/labels.yml"] + workflow_dispatch: + +permissions: + contents: read + issues: write + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: crazy-max/ghaction-github-labeler@v5 + with: + yaml-file: .github/labels.yml + skip-delete: true # never delete labels this file doesn't list diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8edf019..69a1f12 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,5 +1,5 @@ -# Tag v* -> test -> publish to GitHub Packages, then cut a GitHub release. -# GitHub Packages auth uses the built-in GITHUB_TOKEN (packages: write) — no external secret. +# Push a v* tag -> test -> publish to public npm (with provenance) -> cut a GitHub Release. +# Requires one repo secret: NPM_TOKEN (an npm "Automation" token). See docs/RELEASING.md. name: Release on: @@ -10,25 +10,29 @@ permissions: contents: read jobs: - publish: + release: runs-on: ubuntu-latest permissions: - contents: write # create the GitHub release - packages: write # publish to GitHub Packages (npm.pkg.github.com) + contents: write # create the GitHub Release + id-token: write # npm provenance (supply-chain attestation) steps: - uses: actions/checkout@v7 + with: + fetch-depth: 0 # full history so release notes can diff from the last tag - uses: actions/setup-node@v6 with: node-version: 22 - registry-url: "https://npm.pkg.github.com" + registry-url: "https://registry.npmjs.org" cache: npm - run: npm ci - run: npm test - - run: npm publish + - run: npm publish --provenance --access public env: - NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: Create GitHub release + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: Create GitHub Release env: GH_TOKEN: ${{ github.token }} TAG: ${{ github.ref_name }} - run: gh release create "$TAG" --notes-from-tag --verify-tag + # --generate-notes builds notes from merged PRs/commits since the previous tag, + # so it works with lightweight OR annotated tags (unlike --notes-from-tag). + run: gh release create "$TAG" --title "$TAG" --generate-notes --verify-tag diff --git a/.github/workflows/repo-settings.yml b/.github/workflows/repo-settings.yml new file mode 100644 index 0000000..8402fc2 --- /dev/null +++ b/.github/workflows/repo-settings.yml @@ -0,0 +1,41 @@ +# Repo "About" as code: description, homepage, topics, and Discussions. +# Run manually: Actions -> "Repo settings" -> Run workflow. +# +# NOTE: editing repo settings needs an ADMIN-scoped token. The default GITHUB_TOKEN +# cannot be granted `administration`, so add a fine-grained PAT (Administration: write, +# Metadata: read) as the repo secret ADMIN_TOKEN. Without it the job will 403 — in that +# case just run the two `gh` commands below locally once (they need no workflow): +# +# gh repo edit CodeWithJuber/forgekit \ +# --description "One config for every AI coding agent — cross-tool config + a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more." \ +# --homepage "https://github.com/CodeWithJuber/forgekit#readme" \ +# --add-topic claude-code --add-topic ai-coding --add-topic ai-agents --add-topic mcp \ +# --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate \ +# --add-topic developer-tools --add-topic cli --add-topic codex --add-topic cursor +# gh api --method PATCH /repos/CodeWithJuber/forgekit -F has_discussions=true +name: Repo settings + +on: + workflow_dispatch: + +permissions: + contents: read + +jobs: + settings: + runs-on: ubuntu-latest + steps: + - name: Apply About, topics, and Discussions + env: + GH_TOKEN: ${{ secrets.ADMIN_TOKEN || github.token }} + REPO: ${{ github.repository }} + run: | + set -e + gh repo edit "$REPO" \ + --description "One config for every AI coding agent — cross-tool config + a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more." \ + --homepage "https://github.com/CodeWithJuber/forgekit#readme" \ + --add-topic claude-code --add-topic ai-coding --add-topic ai-agents --add-topic mcp \ + --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate \ + --add-topic developer-tools --add-topic cli --add-topic codex --add-topic cursor + gh api --method PATCH "/repos/$REPO" -F has_discussions=true + echo "Applied About, topics, and Discussions for $REPO." diff --git a/.npmrc b/.npmrc index 430545e..c985ce6 100644 --- a/.npmrc +++ b/.npmrc @@ -1,6 +1,4 @@ -# Public deps (Biome, typescript) resolve from npmjs; only the @codewithjuber scope -# publishes/installs from GitHub Packages. Without the explicit default, setup-node's -# registry-url would point the default at GitHub Packages and break `npm ci`. +# Everything resolves from the public npm registry (devDeps and the published package). +# Without the explicit default, setup-node's registry-url could repoint npm and break `npm ci`. registry=https://registry.npmjs.org/ -@codewithjuber:registry=https://npm.pkg.github.com min-release-age=7 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ad0e530..67f549e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,10 +1,10 @@ -# Forge — architecture & production plan +# Forge — architecture > Cross-tool configuration layer for agentic AI coding assistants. One source of > truth, emitted natively into every tool; a small set of *enforced* guards; a > lean discipline; a code-graph (`atlas`); cross-session memory (`recall`); and a -> token-budget cost governor. Install once (Claude plugin **or** installer **or** -> `forgekit` npm CLI). Near-zero learning curve. +> token-budget cost governor. Install as a Claude Code plugin, from public npm +> (`@codewithjuber/forgekit`), or from source. Near-zero learning curve. Grounded in a verified multi-source research pass (Reddit/HN/dev.to, GitHub issue trackers, official vendor docs). Evidence + config-format verdicts in the appendix. @@ -116,6 +116,10 @@ only as the AST/chunking fallback for files with no language server. | **Copilot** | root `AGENTS.md` (since 2025-08-28) + `.github/copilot-instructions.md` | Rely on root `AGENTS.md`; optional generated `.github` pointer | | **Windsurf/Devin** | `AGENTS.md` auto-discovered; caps 6k/12k chars; mid-rebrand to Devin | Root `AGENTS.md` under caps; detect `.windsurf` vs `.devin` at init | | **Zed** | first match of a precedence list incl. `AGENTS.md` | Emit `AGENTS.md` + doctor flags any earlier-precedence legacy file shadowing it | +| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | Emit a rules file plus the Forge MCP server config | + +Roo Code and VS Code receive the Forge MCP server via `forge init` (`.roo/mcp.json`, +`.vscode/mcp.json`) rather than a rules file. ## Repo layout — one tree, three front doors ``` @@ -127,7 +131,7 @@ forgekit/ cli.js # init | sync | doctor | taste | learn-consolidate | brand sync.js # emitter (source → per-tool targets); hash + DO-NOT-EDIT doctor.js # health checks - emit/ # one module per tool (claude, codex, cursor, gemini, aider, copilot, windsurf, zed) + emit/ # one module per tool (claude, codex, cursor, gemini, aider, copilot, windsurf, zed, continue) + mcp source/ AGENTS.md # THE canonical source rules/ # git.md, testing.md, security.md, style.md → assembled @@ -142,18 +146,6 @@ plugin.json, install.sh, and the npm bin **all reference `global/` + `source/`** no duplication; each channel just runs `forge sync` at the end. A test asserts all three resolve to `global/`. -## Build phases (each = a shippable slice, with a runnable exit check) - -| Phase | Deliverables | Exit check | -|-------|-------------|------------| -| **0. Repo + brand spine** | git init; `brand.json` one-token; rename to `forgekit/`; `forge` bin stub | `forge --version` prints brand+version; grep proves brand defined once | -| **1. Emitter** | `source/AGENTS.md` from fragments; `sync.js` + all 8 emit modules; hash headers | `forge sync` in a fixture emits every target; idempotent re-run; golden-file tests pass | -| **2. Install + doctor** | hardened `install.sh`; `plugin.json`+`marketplace.json`; `forge doctor` | fresh-machine sim → doctor all-green; `npm pack` exposes `forge`; plugin loads w/o inflating skill count | -| **3. Guards** | rebranded protect-paths/format/recall-load; `cost-budget` w/ lock; `lean-guard`; session-learner gate | guard harness: blocks `.env` write; lock prevents re-entry; fires from subdir + worktree; settings validates | -| **4. lean + recall + crew** | `lean` tool; unified `recall`; rebranded crew | recall: write→new-session load→consolidate dedupes; secret write refused; verifier runs diff-scoped | -| **5. atlas** | serena/LSP-backed `atlas` build/query/update; portable artifact; hallucinated-symbol flag; lazy MCP | indexes a sample repo; nonexistent symbol → not-found; reuse-first consumes atlas; MCP responds | -| **6. Onboarding polish** | `forge init` wizard + active-summary; Start-Here catalog; docs | clean-env `forge init` → working in one command; catalog lists every item w/ one-line why; smoke test needs no external doc | - ## Risks & honest boundaries - **Enforcement ceiling** — guards enforce only what's expressible as a hook (paths, format, diff-size, budget). Semantic rules ("prefer functional") stay prose and @@ -169,17 +161,6 @@ three resolve to `global/`. the minimum graph that powers reuse + hallucination-flag, not a code-intel product. - **Three channels triple drift surface** — mitigated by "one tree" + the resolve test. -## Open decisions → recommended resolutions -| Decision | Recommendation | -|----------|----------------| -| atlas: existing indexer vs hand-roll | **serena/LSP** (resolved by tech-selector) | -| Gemini: 2nd copy vs settings opt-in | **settings `context.fileName` opt-in** | -| Windsurf `.windsurf` vs `.devin` | **detect at init + confirm** | -| recall consolidation cadence | **opt-in Stop-hook**, optional `forge learn-consolidate` cron | -| cost-budget: block vs warn | **warn** (blocking re-creates permission fatigue) | -| atlas MCP always-on vs lazy | **lazy-start** | -| convert semantic rules → guards | **incrementally**, only where a deterministic check is clean | - --- -*Appendix: config-format verdicts confirmed against vendor docs; single/secondhand -stats (Cursor "1/3 ignore", arXiv 42/96/48) flagged and not hardcoded into user copy.* +See [ROADMAP.md](ROADMAP.md) for direction and [`docs/adr/`](docs/adr/) for the recorded +architecture decisions (zero runtime deps, the SKILL.md standard, guard-over-prose). diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c89d96..913ad90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,33 +6,28 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +## [0.4.0] - 2026-07-06 + ### Added -- **M4 goal-anchoring (`forge anchor`)** — the one paper capability that was mapped in the docs but never implemented. A deterministic goal-drift check: it re-reads the stated objective against the files actually changed (`git diff HEAD` + untracked, minus forge's own generated config) and flags work that wandered off-goal. Reuses `referencedEntities` + the atlas; folded into `forge substrate` (quiet on a clean tree, speaks mid-session on drift). All 11 paper capabilities now ship a real mechanism. +- **Forge Cognitive Substrate** — one pre-action command (`forge substrate`) plus an MCP surface (`substrate_check`, `predict_impact`, `assumption_gate`, `route_task`, `scope_files`): assumption gate, transparent model routing, impact/blast-radius, scope decomposition, Cortex lessons, minimality, and a verification checklist. +- **M4 goal-anchoring (`forge anchor`)** — a deterministic goal-drift check that flags changed files off the stated goal. All 11 white-paper capabilities now ship a real mechanism. +- **Atlas v2 graph** — dependency nodes/edges + reverse-dependency impact traversal (the symbol-query API is preserved). +- **`docs/GUIDE.md`** (the complete command guide) and **`docs/RELEASING.md`** (release runbook). +- **Repo automation** — `repo-settings.yml` (About/topics/Discussions as code) and `labels.yml` (label sync) workflows; a Codex plugin manifest and `cognitive-substrate` skill; the paper bundle under `docs/cognitive-substrate/`. ### Changed -- **Substrate now auto-runs in Claude Code.** The `UserPromptSubmit` hook injects the full substrate advisory (assumption gate + model routing + blast radius + memory + verify) when it matters, silent otherwise. Load-only — never builds/writes `.forge/` from a hook, fail-safe, never blocks. -- **Cross-tool auto-use.** Added a `substrate` section to `source/rules.json` so `forge init` emits the "run substrate before risky work" rule into every tool's config (AGENTS.md, .cursor/rules, …). -- **Docs rewritten** — `docs/cognitive-substrate/README.md` is a professional, example-rich guide (real command output, auto-use setup, extension points); README/SKILL aligned. -- **README restructured** to a professional standard — clear value prop, an install matrix, quickstart, a "how it works" three-layer table, an auto-use section, a full command list, honest limits, and a docs index. -- **Install story fixed.** The recommended paths are now the **plugin** (Claude Code / Codex) and a token-free CLI install, `npm install -g github:CodeWithJuber/forgekit` — no `curl | bash`, no clone. `bash install.sh` is documented as the symlink/dev path and the GitHub Packages route as CI-only. Updated across README, ONBOARDING, `docs/cognitive-substrate/README.md`, and the landing page. -- **New `docs/GUIDE.md`** — the complete guide: every command with a worked example and its real output, the everyday workflow, auto-use inside an agent, recipes, and how to extend each layer (rules, tools, guards, crew, routing signals, emitters, rebrand). -- **Landing page** — install snippet uses the token-free CLI command; version string corrected to 0.3.1. +- **Publish to public npm.** `@codewithjuber/forgekit` now publishes to npmjs with provenance, so `npm install -g @codewithjuber/forgekit` needs no token (replacing the GitHub Packages route, which required auth even for public installs). The release workflow was fixed to trigger on a tag, publish, and cut a GitHub Release with generated notes. +- **Substrate auto-runs in Claude Code** via a `UserPromptSubmit` hook — it surfaces only when something needs attention and never blocks — and `forge init` emits a "run substrate before risky work" rule into every other tool's config. +- **Docs overhaul** — README rewritten (problem → solution → how, npm-first, SEO-friendly); the install, honest-limits, frozen-model, and substrate blocks are single-sourced instead of copied across files; the supported-tool list is reconciled everywhere. ### Fixed -- **Security (research prototype): removed pickle-based cache** in `impact_oracle/world_model.py` — it was an insecure-deserialization (RCE) vector on a caller-supplied `cache_dir`. Now JSON node-link only, with `cache_dir` containment inside `root`. -- **Smaller npm package** — stopped publishing `docs/cognitive-substrate` (a ~2 MB whitepaper + zips); tarball dropped to ~280 KB. Removed the redundant `*_src.zip` binaries (source lives unzipped in `research/`). +- **Security (research prototype):** removed the pickle-based cache in `impact_oracle/world_model.py` — an insecure-deserialization (RCE) vector on a caller-supplied `cache_dir`. Now JSON node-link only, with `cache_dir` contained inside `root`. +- **Smaller npm package** — stopped publishing the ~2 MB paper bundle and the redundant `*_src.zip` (source lives unzipped under `research/`). - **Perf** — `substrateCheck` no longer recomputes the assumption assessment. -### Added - -- **Forge Cognitive Substrate** — one pre-action command (`forge substrate`) and MCP surface (`substrate_check`, `predict_impact`, `assumption_gate`) that combines assumption gating, transparent model routing, impact prediction, scope decomposition, Cortex lessons, minimality warnings, and verification planning. -- **Atlas v2 graph** — dependency nodes/edges, file hashes, and reverse-dependency impact traversal while preserving the old symbol query API. -- Codex plugin manifest and `cognitive-substrate` skill so Forge can be installed/used from Codex-style extension surfaces as well as Claude/NPM. -- Cognitive-substrate paper bundle under `docs/cognitive-substrate/`: full PDF/HTML paper, deliverable overview, evidence map, ecosystem map, and original prototype packages. - ## [0.3.1] - 2026-07-05 ### Changed diff --git a/CITATION.cff b/CITATION.cff index a4d900a..5b769ad 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,10 +1,14 @@ cff-version: 1.2.0 message: "If you use forgekit, please cite it using this metadata." -title: forgekit +title: "Forge (forgekit)" +version: 0.4.0 +date-released: "2026-07-06" abstract: >- - One config, every AI coding tool — a cross-tool configuration layer for agentic - coding assistants with an independent verification gate, portable memory, a - security-vetting skill-gate, and a cost governor. + One config for every AI coding agent — a cross-tool configuration layer plus a + cognitive substrate that gives a frozen model the memory, blast-radius awareness, and + guardrails it structurally lacks: an independent verification gate, self-correcting + project memory, portable memory, a security-vetting skill-gate, and a cost governor, + emitted natively to Claude Code, Codex, Cursor, Gemini, Aider, and more. type: software authors: - name: CodeWithJuber @@ -15,4 +19,10 @@ keywords: - claude-code - agents-md - ai-coding + - ai-agents - cross-tool + - cognitive-substrate + - mcp + - codex + - cursor + - cli diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e58c167..5f32734 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,6 +65,11 @@ diffs with no tests) will be closed. To get merged: We'd rather give a clear "not now" than merge something that adds maintenance burden — see [GOVERNANCE.md](./GOVERNANCE.md). +## Releasing (maintainers) + +Cutting a release is one command plus a tag — the full runbook (and the one-time +`NPM_TOKEN` setup) is in [docs/RELEASING.md](./docs/RELEASING.md). + ## Sign your work (DCO) This project uses the [Developer Certificate of Origin](https://developercertificate.org/). diff --git a/ONBOARDING.md b/ONBOARDING.md index b17ff65..61d4c15 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -1,23 +1,26 @@ # Onboarding — five minutes to productive +> **Forge** is a cross-tool config layer plus a cognitive substrate for AI coding +> agents (Claude Code, Codex, Cursor, Gemini, Aider…). Author your rules once; it +> configures every tool and adds memory, blast-radius checks, and guardrails. + ## 1. Install (once) -Pick one — no `curl | bash`, no clone required for either: +The recommended paths need no token and no clone: ```bash -# A) Claude Code / Codex — the plugin (recommended; guards auto-wire, nothing to merge) +# Claude Code / Codex — the plugin (guards auto-wire, nothing to merge) /plugin marketplace add CodeWithJuber/forgekit /plugin install forgekit -# B) Any tool — the CLI (no token, no clone) -npm install -g github:CodeWithJuber/forgekit +# Any tool — the CLI, from public npm +npm install -g @codewithjuber/forgekit forge doctor # everything green? ``` -Hacking on Forge itself? Clone and `npm link`, or `bash install.sh` to symlink the -tree into `~/.claude` (idempotent, reversible, prints the hook block to merge). See -[README → Install](README.md#install) for the full matrix. +Full matrix (no-registry `github:` install, symlink dev setup) → +[README → Install](README.md#install). ## 2. Configure a repo (once per repo) @@ -26,8 +29,8 @@ cd ~/your-project forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … ``` -Now Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, and Zed all read -the **same** rules — each from its own native file. +Now Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, and Continue all +read the **same** rules — each from its own native file (plus MCP config for Roo and VS Code). ## 3. Change a rule @@ -62,7 +65,7 @@ forge catalog # the Start-Here index of everything --- -# Forge principles +## Forge principles Forge is opinionated. These are the ideas every part of it is built on — the "why" behind the mechanisms. @@ -116,9 +119,7 @@ originate here. Every deliberate simplification states its limit and upgrade path, in code and in docs. Forge would rather ship an honest subset with a clear boundary than a vague -claim. It reduces the "ignored my rules" problem; it does not eliminate it. It -flags likely-hallucinated symbols; it does not certify correctness. `recall` is -file memory, not weight-level learning. +claim — see [the honest limits](docs/GUIDE.md#honest-limits). --- diff --git a/README.md b/README.md index 755f281..745cbf7 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,131 @@ -# Forge +# Forge — one config for every AI coding agent [![CI](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/@codewithjuber/forgekit.svg)](https://www.npmjs.com/package/@codewithjuber/forgekit) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![node: >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](./package.json) [![runtime deps: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg)](./package.json) -**One config, every AI coding tool — plus the memory, foresight, and guardrails a -frozen model structurally lacks.** +**The memory, foresight, and guardrails a frozen model structurally lacks — wired into +every AI coding tool from one config.** -Forge is a cross-tool configuration layer for agentic coding assistants. You author -your rules **once**; Forge emits each tool's native config, enforces the -non-negotiables as deterministic guards, and adds a code-graph, cross-session memory, -a cost governor, and a **cognitive substrate** that runs a fast pre-action check -before an agent touches your code. Works with **Claude Code, Codex, Cursor, Gemini -CLI, Aider, Copilot, Windsurf/Devin, Zed, Continue, and Roo**. +## The problem -> **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `cortex`, guards) -> is tested and in daily use; some flags may still change before `1.0`. +You now juggle several AI coding assistants, and every one of them: + +- reads a **different** config file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `GEMINI.md`…), +- **acknowledges your rules, then ignores them** — especially after a context compaction, +- has **no memory** across sessions and re-learns your repo every time, +- **can't see what an edit breaks** beyond the handful of files in its window, and +- can quietly run up a surprise token bill. -- **New here?** → [Install](#install) then the [5-minute onboarding](ONBOARDING.md). -- **Want every command with worked examples?** → [`docs/GUIDE.md`](docs/GUIDE.md). -- **Want the theory?** → the [cognitive-substrate white paper](docs/cognitive-substrate/). +## The solution + +Author your rules **once**. Forge emits each tool's native config, enforces the +non-negotiables as deterministic **guards**, and adds cross-session memory, a code-graph, +a cost governor, and a **cognitive substrate** that checks a task *before* the agent +touches your code. Works with **Claude Code, Codex, Cursor, Gemini, Aider, Copilot, +Windsurf, Zed, and Continue** (plus MCP config for Roo and VS Code). + +> **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `cortex`, guards) +> is tested and in daily use; some flags may change before `1.0`. --- ## Install -Pick the row that matches how you work. **No `curl | bash`, no clone required** for -the two recommended paths. +`forge` is a zero-dependency Node CLI. Pick the row that fits — the recommended paths +need **no token and no clone**. | You use… | Run this | What you get | | --- | --- | --- | -| **Claude Code / Codex** *(recommended)* | `/plugin marketplace add CodeWithJuber/forgekit`
`/plugin install forgekit` | The full plugin — tools, crew, and **ambient guards** wired automatically. Zero setup. | -| **Any tool, from the CLI** | `npm install -g github:CodeWithJuber/forgekit` | The `forge` command on your `PATH`. No token, no clone. | +| **Claude Code / Codex** *(recommended)* | `/plugin marketplace add CodeWithJuber/forgekit`
`/plugin install forgekit` | The full plugin — tools, crew, and **ambient guards** wired automatically. | +| **Any tool, from the CLI** | `npm install -g @codewithjuber/forgekit` | The `forge` command on your `PATH`, from public npm. | | **Contributors / local dev** | `git clone https://github.com/CodeWithJuber/forgekit.git`
`cd forgekit && npm link` | An editable checkout with `forge` linked to your working copy. | -Verify any install with one command: - ```bash -forge doctor # health-check: tools, guards, MCP auth, config drift +forge doctor # verify any install: tools, guards, MCP, config drift ```
-Alternative installs (symlink dev setup · GitHub Packages · CI) - -**Symlink `global/` into `~/.claude` (dev setup).** From a clone, `bash install.sh` -symlinks the tree into `~/.forge` + `~/.claude` and prints the hook block to merge. -It is idempotent, reversible (`bash install.sh --uninstall`), offline, and never -edits your `settings.json` for you. Prefer the plugin unless you're hacking on Forge -itself. - -**GitHub Packages (`@codewithjuber/forgekit`).** Published to GitHub Packages, which -requires an auth token even for public installs — so it's only worth it in CI that -already authenticates: +Other ways in (no-registry install · symlink dev setup) -```bash -echo "@codewithjuber:registry=https://npm.pkg.github.com" >> ~/.npmrc -echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc # needs read:packages -npx @codewithjuber/forgekit init -``` +- **No registry at all:** `npm install -g github:CodeWithJuber/forgekit` installs `forge` + straight from the repo — no npm account, no token. +- **Symlink dev setup:** from a clone, `bash install.sh` symlinks `global/` into + `~/.forge` + `~/.claude` and prints the hook block to merge. Idempotent, reversible + (`bash install.sh --uninstall`), offline. Prefer the plugin unless you're hacking on Forge.
-All three front doors drive the **same** `global/` + `source/` tree — no duplication. - ---- - ## Quickstart ```bash cd your-project - forge init # emit every tool's native config from one shared source forge substrate "add rate limiting to the /login route" # pre-action check before you edit ``` -`forge init` configures Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Zed, -Continue, and Roo — each reads the **same** rules from its own native file. On Claude -Code the substrate then runs **on every prompt, automatically** (see [below](#it-runs-itself)). +`forge init` writes each agent's native config from one source. On **Claude Code** the +substrate then runs **on every prompt, automatically** — see [It runs itself](#it-runs-itself). --- -## Why Forge exists - -A single developer now juggles several AI coding tools, and each one: - -- reads a **different** config file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `GEMINI.md`…), -- **acknowledges your rules, then ignores them** — especially after context compaction, -- has **no memory** across sessions, re-learning your repo every time, -- **can't see what an edit breaks** beyond the files in its window, and -- can quietly run up a surprise token bill. - -Forge answers each with a specific mechanism, not a vibe. The mechanisms come straight -from a first-principles read of what a frozen language model *is* — a stateless -function `y = f(x)` with fixed weights and a bounded window — and what that shape -structurally prevents. The full argument, with evidence graded against primary -sources, is the [cognitive-substrate white paper](docs/cognitive-substrate/). - ## How it works — three layers -| Layer | Named | What it does | Enforcement | +| Layer | Is | What it does | Enforcement | | --- | --- | --- | --- | -| **tools** | model-invoked skills | know-how loaded on demand: `lean`, `reuse-first`, `atlas`, `recall`, `cognitive-substrate` | the model chooses to use them | +| **tools** | model-invoked skills | know-how loaded on demand: `lean`, `reuse-first`, `atlas`, `recall`, `cognitive-substrate` | the model opts in | | **crew** | isolated sub-agents | fresh-context specialists: `scout`, `verifier`, `frontend-verifier` | spawned per task | -| **guards** | deterministic hooks | the **only** layer that *enforces*: `protect-paths`, `cost-budget`, `doom-loop`, `cortex` | runs regardless of what the model "remembers" | +| **guards** | deterministic hooks | the **only** layer that *enforces*: `protect-paths`, `cost-budget`, `doom-loop`, `cortex` | runs no matter what the model "remembers" | -**The one idea that matters:** rules the model can drift from live in prose; rules it -must **never** break live in **guards**. A guard is a shell hook — it can't be -forgotten after a context compaction. So Forge demotes enforceable invariants (don't -touch `.env`, watch the token budget, keep diffs small) out of `CLAUDE.md` prose and -into guards, and keeps the prose thin and single-sourced. +**The one idea that matters:** rules a model can drift from live in prose; rules it must +**never** break live in **guards** — shell hooks that can't be forgotten after a context +compaction. So Forge moves enforceable invariants (don't touch `.env`, watch the budget, +keep diffs small) out of `CLAUDE.md` prose and into guards, and keeps the prose thin. Two subsystems build on those layers: -- **Forge Cortex — self-correcting memory.** An LLM relearns your repo every session - and repeats last week's correction. Cortex watches for a *genuine* recurring mistake - (a test that failed then passed, a `git revert`, an explicit "undo"), distills a - durable lesson, and re-confirms it against fresh outcomes. Injection never confirms a - lesson — only independent outcomes (tests, builds, a human) move its confidence, so a - wrong lesson decays out instead of ossifying. Advisory, never blocking. +- **Cortex — self-correcting memory.** A model relearns your repo every session and + repeats last week's correction. Cortex spots a *genuine* recurring mistake (a test that + failed then passed, a `git revert`, an explicit "undo"), distills a durable lesson, and + re-confirms it against fresh outcomes. Only independent outcomes (tests, builds, a human) + move a lesson's confidence — so a wrong one decays out instead of ossifying. Advisory. -- **Forge Cognitive Substrate — the check before every edit.** One fast, mostly- - deterministic command supplies the faculties a frozen model can't have: is the task - clear enough to start (**assumption gate**), which model is cheapest-but-capable - (**route**), what will this edit break (**impact / blast radius**), what can be split - into separate sessions (**scope**), and how do we prove it worked (**verify**) — all - from the repo you already have, with no extra LLM call. +- **Cognitive substrate — the check before every edit.** One fast, mostly-deterministic + command supplies what a frozen model can't: is the task clear enough to start + (**assumption gate**), which model is cheapest-but-capable (**route**), what an edit will + break (**impact / blast radius**), what to split into separate sessions (**scope**), + whether the work has drifted off-goal (**anchor**), and how to prove it worked + (**verify**) — from the repo you already have, with no extra LLM call. ```bash forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" ``` returns, in one pass: the assumption verdict, the cheapest capable model, the predicted -blast radius (including the coupled files you *didn't* name), scope clusters, relevant -Cortex lessons, and a verification checklist. +blast radius (**including the coupled files you didn't name**), scope clusters, matching +Cortex lessons, goal-drift, and a verification checklist. + +> **Why a "substrate"?** A language model at inference is a fixed function `y = f(x)` — +> frozen weights, a bounded window, no state between calls. Memory, foresight, and +> self-checking can't be prompted into that shape; they have to be supplied from outside. +> The full argument, with evidence graded against primary sources, is the +> [cognitive-substrate white paper](docs/cognitive-substrate/). ## It runs itself You don't have to remember to use any of this. -- **In Claude Code** — a `UserPromptSubmit` hook runs the substrate on **every prompt** - and adds a short advisory *only when something needs attention* (unclear task, big - blast radius, pricey model). It never blocks and never nags on a clean, simple task. -- **In other AI tools** (Codex, Cursor, Gemini, Aider…) — `forge init` writes a rule - into their native config telling the agent to run the check itself, and exposes it as - MCP tools any MCP-capable agent can call: `substrate_check`, `assumption_gate`, - `predict_impact`, `route_task`, `scope_files`. +- **In Claude Code** — a `UserPromptSubmit` hook runs the substrate on **every prompt** and + adds a short advisory *only when something needs attention* (unclear task, big blast + radius, pricey model). It never blocks and never nags on a clean task. +- **In every other tool** — `forge init` writes a rule into the tool's native config telling + the agent to run the check itself, and exposes it as MCP tools any agent can call + (`substrate_check`, `predict_impact`, `assumption_gate`, `route_task`, `scope_files`). -Forge never pretends it can force a hook into a tool that has none — it's **ambient on -Claude Code, agent-invoked everywhere else**, and says so plainly. +Ambient on Claude Code, agent-invoked everywhere else — and Forge says so plainly rather +than pretending it can force a hook into a tool that has none. --- @@ -179,28 +156,18 @@ forge harden wire gitleaks pre-commit + sandbox settings forge brand print the active brand token map ``` -**→ Every command with a worked example, expected output, and how to extend it: +**→ Every command with a worked example, real output, and how to extend it: [`docs/GUIDE.md`](docs/GUIDE.md).** ---- - -## What's honest about it - -Forge states its own ceiling everywhere — the same discipline the substrate applies to -your edits. +## Honest limits -- **Guards reduce, don't eliminate** the "ignored my rules" problem — semantic rules - still live in prose and can still be missed. -- **`recall` / `cortex` are file + prompt memory**, not weight-level learning. No RL, - no fine-tuning. Consolidation is deterministic, not a model call. -- **`atlas` / `impact` is a regex-approximate graph.** It flags likely-hallucinated - symbols and catches the obvious dependents; it is *conservative*, not a sound call - graph, and can miss dynamic dispatch or generated code. -- **The substrate's rubrics are heuristic, not benchmarked** — tuned on small - hand-labeled sets. What's *asserted* (safe to gate on): repo grounding, graph - traversal, scope decomposition, routing arithmetic, and the test/build commands. - What's *advisory* (flagged, never asserted): model fit, minimality, and memory - relevance. **Tests and human corrections always win.** +Forge states its own ceiling everywhere. In short: **guards reduce, don't eliminate** the +"ignored my rules" problem; `recall`/`cortex` are file memory, **not** weight-level +learning; the `atlas`/`impact` graph is regex-approximate (conservative, not a sound call +graph); and the substrate's rubrics are heuristic, not benchmarked. What's *asserted* is +safe to gate on (repo grounding, graph traversal, routing arithmetic, the test commands); +everything else is *advisory*. **Tests and human corrections always win.** Full list: +[docs/GUIDE.md → Honest limits](docs/GUIDE.md#honest-limits). ## Documentation @@ -209,21 +176,22 @@ your edits. | [`ONBOARDING.md`](ONBOARDING.md) | Five minutes to productive + the design principles. | | [`docs/GUIDE.md`](docs/GUIDE.md) | Every command, worked examples, all cases, how to extend. | | [`docs/cognitive-substrate/`](docs/cognitive-substrate/) | The white paper, evidence map, ecosystem map, and prototype sources. | -| [`ARCHITECTURE.md`](ARCHITECTURE.md) | The four-layer compiler, the pain-point evidence, and the cross-tool emit matrix. | +| [`ARCHITECTURE.md`](ARCHITECTURE.md) | The four-layer compiler and the cross-tool emit matrix. | +| [`docs/RELEASING.md`](docs/RELEASING.md) | How releases are cut (tag → npm + GitHub Release). | | [`CHANGELOG.md`](CHANGELOG.md) | What changed, per release. | ## Community & support -- **Get help / ask questions** → [SUPPORT.md](./SUPPORT.md) · [Discussions](https://github.com/CodeWithJuber/forgekit/discussions) +- **Get help** → [SUPPORT.md](./SUPPORT.md) · [Discussions](https://github.com/CodeWithJuber/forgekit/discussions) - **Contribute** → [CONTRIBUTING.md](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) -- **Direction & decisions** → [ROADMAP.md](./ROADMAP.md) · [GOVERNANCE.md](./GOVERNANCE.md) +- **Direction** → [ROADMAP.md](./ROADMAP.md) · [GOVERNANCE.md](./GOVERNANCE.md) - **Security** → [SECURITY.md](./SECURITY.md) (report privately) · **Accessibility** → [ACCESSIBILITY.md](./ACCESSIBILITY.md) ## Rebranding -The name lives in one place: `brand.json` (`FORGE_BRAND`). Change it there (plus the -`bin` key in `package.json` and `name` in `.claude-plugin/plugin.json`) and the whole -CLI, banner, and emitted headers follow. +The name lives in one place: `brand.json`. Change it there (plus the `bin` key in +`package.json` and `name` in `.claude-plugin/plugin.json`) and the whole CLI, banner, and +emitted headers follow. --- diff --git a/ROADMAP.md b/ROADMAP.md index cb7abc8..224af05 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -3,20 +3,23 @@ Direction, not promises — shaped by the two field reports this project is grounded in (the SDLC pain-point map and the ecosystem landscape). Open a Discussion to weigh in. -## Now (in `main`) -Cross-tool config + MCP emit (8 tools), verification layer (`forge verify`), security gate -(`forge scan`), portable memory (`forge brain`), cost governor (`forge cost`), and the -cognitive-substrate pre-action gate (`forge substrate`, `forge impact`). The full paper -and evidence bundle live in [docs/cognitive-substrate/](./docs/cognitive-substrate/). -See [CHANGELOG.md](./CHANGELOG.md) `[Unreleased]`. +## Now (`master`) +Cross-tool config for nine agents (Claude Code, Codex, Cursor, Gemini, Aider, Copilot, +Windsurf, Zed, Continue) plus MCP config for Roo & VS Code, verification layer +(`forge verify`), security gate (`forge scan`), portable memory (`forge brain`), cost +governor (`forge cost`), spec-as-contract drift (`forge spec`), goal-drift check +(`forge anchor`), and the cognitive-substrate pre-action gate (`forge substrate`, +`forge impact`). The full paper and evidence bundle live in +[docs/cognitive-substrate/](./docs/cognitive-substrate/). See +[CHANGELOG.md](./CHANGELOG.md) `[Unreleased]`. ## Next - **Substrate calibration fixtures** — expand assumption/routing/impact fixtures beyond the original paper prototypes while keeping research-edge claims advisory. -- **spec-lock** — spec-as-contract drift detection, reusing the `atlas` index. +- **AST-backed impact** — an optional exact call graph behind the regex-approximate atlas + (weighed against the zero-runtime-dependency constraint). - **Testing** — Playwright MCP/agents opt-in + a coverage Stop-hook gate. - **MCP hygiene** — enforce the ~6-server cap + a registry resolver in `forge doctor`. -- **VS Code / Windsurf MCP** — `.vscode/mcp.json` (`servers`) and Windsurf's global config. ## Later / exploring - Optional vector-memory backend (Hindsight / Mem0) wiring. diff --git a/SECURITY.md b/SECURITY.md index 42c0760..8db16b1 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,10 +4,10 @@ Only the latest release of forgekit receives security updates. -| Version | Supported | -| ------- | --------- | -| latest | ✅ | -| < latest | ❌ | +| Version | Supported | +| -------- | --------- | +| latest | ✅ Yes | +| < latest | ❌ No | ## Reporting a Vulnerability diff --git a/docs/RELEASING.md b/docs/RELEASING.md new file mode 100644 index 0000000..151d127 --- /dev/null +++ b/docs/RELEASING.md @@ -0,0 +1,46 @@ +# Releasing Forge + +Releases are automated by [`.github/workflows/release.yml`](../.github/workflows/release.yml): +**push a `v*` tag → it runs the tests, publishes to public npm (with provenance), and +cuts a GitHub Release** with auto-generated notes. + +## One-time setup (maintainer) + +The workflow needs a single secret to publish: + +1. Create an [npmjs.com](https://www.npmjs.com/) account and make sure it can publish to + the `@codewithjuber` scope. +2. Generate an **Automation** access token (npm → Access Tokens → Generate → *Automation*). +3. Add it to the repo: **Settings → Secrets and variables → Actions → New repository + secret**, name **`NPM_TOKEN`**. + +That's the only manual step. Without it the publish step fails; everything else still runs. + +## Cutting a release + +```bash +# 1. bump the version (updates package.json + package-lock.json, no tag yet) +npm version minor --no-git-tag-version # or: patch / major + +# 2. move the [Unreleased] notes into a new dated section in CHANGELOG.md, then commit +git add -A && git commit -m "chore(release): v$(node -p "require('./package.json').version")" + +# 3. tag and push — this is what triggers the release workflow +V="v$(node -p "require('./package.json').version")" +git tag -a "$V" -m "$V" +git push origin master "$V" +``` + +The workflow then publishes `@codewithjuber/forgekit@` to npm and creates the +matching GitHub Release. Verify: + +- npm: +- releases: + +## Notes + +- **Semver**: `patch` = fixes, `minor` = new commands/flags (backward compatible), + `major` = breaking changes. Pre-`1.0`, breaking changes may ship in a `minor`. +- Consumers install with no token: `npm install -g @codewithjuber/forgekit`. +- Re-running a failed release is safe — `npm publish` refuses to overwrite a version that + already exists, so only the missing steps take effect. diff --git a/docs/cognitive-substrate/README.md b/docs/cognitive-substrate/README.md index cfe7a38..ac1d548 100644 --- a/docs/cognitive-substrate/README.md +++ b/docs/cognitive-substrate/README.md @@ -14,26 +14,19 @@ In Claude Code it runs **automatically**. In other tools you (or the agent) run --- -## Install (about 2 minutes) +## Install -```bash -# Claude Code / Codex — the plugin (recommended; the check then runs on every prompt) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit - -# …or the CLI, any tool (no token, no clone) -npm install -g github:CodeWithJuber/forgekit -``` - -Then, inside any project: +Install Forge (plugin · npm · `github:`) per [README → Install](../../README.md#install), +then inside any project: ```bash forge init # writes each AI tool's native config from one source -forge atlas # builds the code graph (needed for blast-radius checks) +forge atlas # build the code graph (needed for blast-radius checks) ``` -That's it. `forge init` configures Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Zed, -Continue, and Roo where supported. +`forge init` configures Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, +and Continue (plus MCP config for Roo and VS Code). On Claude Code the check then runs on +every prompt automatically. --- @@ -173,57 +166,26 @@ Code, and agent-invoked everywhere else. --- -## Use it in a script - -```bash -forge substrate "update verifyToken in src/auth.js" --json -``` - -```jsonc -{ - "okToProceed": false, - "assumption": { "risk": "high", "shouldAsk": true, "questions": ["…"] }, - "route": { "tier": "simple", "model": { "name": "Haiku 4.5" } }, - "impact": { "impactedFiles": ["src/auth.js", "src/login.js"] }, - "verification": { "checklist": ["npm test", "npm run typecheck"] } -} -``` - -Gate your agent's next step on `okToProceed`; feed `route.tier` to your model picker; read -`impact.impactedFiles` before editing. - ---- - -## Extend it - -Small, pure functions — change the one piece you need, then run `npm test`. +## Use it in a script & extend it -| To change… | Edit | -| --- | --- | -| how often it asks | `source/substrate.json` → `defaults.askThreshold` (0.6) | -| blast-radius sensitivity | `source/substrate.json` → `defaults.impactThreshold` (0.1) | -| a routing signal | `src/route.js` → `rubricComplexity()` | -| an assumption question | `src/preflight.js` → `DIMENSIONS[]` | -| the verify checklist | `src/substrate.js` → `verificationChecklist()` | -| when the ambient hook speaks | `src/substrate.js` → `substrateContext()` | -| the cross-tool wording | `source/rules.json` → `substrate` section (then `forge init`) | +Add `--json` to any command for machine-readable output — gate your agent's next step on +`okToProceed`, feed `route.tier` to your model picker, read `impact.impactedFiles` before +editing. Every knob (ask threshold, blast-radius sensitivity, routing signals, assumption +questions, the verify checklist, the ambient hook wording) is a small pure function or a +JSON default. Full JSON shape and the extension table: +[docs/GUIDE.md → Use it in a script](../GUIDE.md#use-it-in-a-script) · +[Extending Forge](../GUIDE.md#extending-forge). --- ## Honest limits -- **Heuristic, not benchmarked.** Rubrics were tuned on small hand-labeled sets. Judge after - real use. -- **The graph is regex-approximate.** Dynamic dispatch / DI / generated code can be missed — - impact is *conservative* (catches the obvious dependents), not a sound call graph. -- **Assumption detection is lexical.** It catches unclear *names and wording*, not wrong - *intent*. -- **Auto-run needs a hook surface** — fully ambient on Claude Code; agent-invoked elsewhere. - -What's **asserted** (safe to gate on): repo symbol/file grounding, graph traversal, scope -decomposition, the routing arithmetic, and the test/build commands. What's **advisory** -(flagged, never asserted): whether the model is capable enough, whether a change is -over-engineered, and whether a past lesson is relevant. Tests and human corrections always win. +Heuristic, not benchmarked; the graph is regex-approximate (conservative, not a sound call +graph); assumption detection is lexical; auto-run needs a hook surface (ambient on Claude +Code, agent-invoked elsewhere). What's *asserted* is safe to gate on (repo grounding, graph +traversal, scope, routing arithmetic, test commands); everything else is *advisory*. Tests +and human corrections always win. Full list: +[docs/GUIDE.md → Honest limits](../GUIDE.md#honest-limits). --- diff --git a/docs/cognitive-substrate/deliverable-package.md b/docs/cognitive-substrate/deliverable-package.md index 89f9578..799961d 100644 --- a/docs/cognitive-substrate/deliverable-package.md +++ b/docs/cognitive-substrate/deliverable-package.md @@ -32,18 +32,14 @@ - [`research/python-prototypes/router_gate/`](../../research/python-prototypes/router_gate/) — the two mechanisms at the top of the build-map, composed as `gate → route → execute → verify → escalate`. Both are **transparent additive rubrics**, not opaque LLM calls; escalation is driven by an external check. `python demo.py`, `pytest` → **19 tests pass**, `python evaluate.py --live` reproduces the live numbers. (Shipped in production as `forge route` / `forge preflight`.) - **`eval_results.json`** — the live evaluation record (real measured tokens). -### 4. Evidence & ecosystem maps _(new)_ +### 4. Evidence & ecosystem maps -- **`evidence_map.json`** / **`evidence_map.md`** — every load-bearing statistic, its primary source, and its status. -- **`ecosystem_map.json`** / **`ecosystem_map.md`** — every faculty & mechanism vs. the real stack, with residual gap and proposed contribution. +- [`evidence_map.md`](./evidence_map.md) — every load-bearing statistic, its primary source, and its status (5 confirmed, 5 vendor-reported, 2 dropped). +- [`ecosystem_map.md`](./ecosystem_map.md) — every faculty & mechanism vs. the real 2026 stack, with the residual gap and the proposed contribution. -### 5. Figures & schematics +### 5. Figures & appendices -- **`schematic_loop.png`** (Fig 1) · **`schematic_system.png`** (Fig 2) · **`schematic_extended.png`** (Fig 3, _new_ — the six-mechanism control layer) · **`impact_graph.png`** (Fig 4) · **`eval_precision_recall.png`** (Fig 5) · **`schematic_router_loop.png`** (Fig 6, _new_) · **`router_eval.png`** (Fig 7, _new_). - -### 6. Supporting artifacts (from v1) - -- **`gap_map.json`/`.md`**, **`references.json`** (32 sources), **`quran_lens.json`/`.md`** (14-row concept→faculty→design-principle mapping). +The seven figures (the frozen loop; the substrate; the six-mechanism control layer; an impact blast-radius graph; the precision/recall evaluation; the router loop; the live router evaluation), the 32-source reference list, and the Qur'anic-lens table are all in the white paper itself ([PDF](./cognitive_substrate_whitepaper.pdf) · [HTML](./cognitive_substrate_whitepaper.html)). --- diff --git a/landing/index.html b/landing/index.html index 4a34639..0e0c4b3 100644 --- a/landing/index.html +++ b/landing/index.html @@ -747,11 +747,11 @@

$ npm install -g - github:CodeWithJuber/forgekit @@ -1097,7 +1097,7 @@

Give your agent a memory that gets better the more it's wrong.