feat: add cognitive substrate pre-action gate

.claude-plugin/plugin.json

@@ -3,12 +3,12 @@
   "name": "forgekit",
   "displayName": "Forge",
   "version": "0.3.1",
-  "description": "One config, every AI coding tool — tools, crew, guards, atlas, lean, recall from one source.",
+  "description": "One config, every AI coding tool — cognitive substrate, tools, crew, guards, atlas, lean, recall from one source.",
   "author": { "name": "CodeWithJuber" },
   "license": "MIT",
   "repository": "https://github.com/CodeWithJuber/forgekit",
   "homepage": "https://github.com/CodeWithJuber/forgekit#readme",
-  "keywords": ["config", "cross-tool", "agents-md", "ai-coding", "claude-code"],
+  "keywords": ["config", "cross-tool", "agents-md", "ai-coding", "claude-code", "cognitive-substrate"],
   "skills": "./global/tools",
   "agents": "./global/crew",
   "hooks": "./hooks/hooks.json"

.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "forgekit",
+  "version": "0.3.1",
+  "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",
+  "repository": "https://github.com/CodeWithJuber/forgekit",
+  "license": "MIT",
+  "keywords": ["codex", "mcp", "ai-coding", "agents-md", "cognitive-substrate"],
+  "skills": "skills",
+  "mcpServers": ".mcp.json",
+  "interface": {
+    "displayName": "Forge",
+    "shortDescription": "Cognitive substrate and one config for every AI coding tool.",
+    "longDescription": "Forge adds a pre-action cognitive substrate for coding agents: assumption gating, transparent model routing, impact prediction, scope decomposition, memory/learning context, and verification checklists. It also emits shared rules and MCP config for Codex, Claude Code, Cursor, Gemini, Aider, Copilot, Windsurf/Devin, Zed, Continue, and Roo.",
+    "developerName": "CodeWithJuber",
+    "category": "Productivity",
+    "capabilities": ["MCP", "Skills", "Code Review", "Verification"],
+    "websiteURL": "https://github.com/CodeWithJuber/forgekit",
+    "privacyPolicyURL": "https://github.com/CodeWithJuber/forgekit/blob/master/SECURITY.md",
+    "termsOfServiceURL": "https://github.com/CodeWithJuber/forgekit/blob/master/LICENSE",
+    "defaultPrompt": [
+      "Run Forge substrate before this edit.",
+      "Predict impact for this symbol.",
+      "Route this task to the right model tier."
+    ],
+    "brandColor": "#137A72"
+  }
+}

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,6 +9,7 @@
 - [ ] Conventional commit message (`feat:`/`fix:`/`docs:` …)
 - [ ] `CHANGELOG.md` updated under `## [Unreleased]`
 - [ ] No new runtime dependency (dev deps ok)
+- [ ] Substrate/docs updated if this changes `forge substrate`, `forge impact`, router/gate, or MCP substrate tools
 
 ## Risk & rollback
 - Risk level: low / medium / high

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "forge-cortex": {
+      "command": "forge",
+      "args": ["cortex-mcp"]
+    }
+  }
+}

ARCHITECTURE.md

@@ -9,6 +9,11 @@
 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.
 
+The cognitive-substrate paper bundle is committed under
+[`docs/cognitive-substrate/`](docs/cognitive-substrate/). It includes the full PDF/HTML
+paper, deliverable overview, evidence map, ecosystem map, and the original prototype
+packages; the production runtime remains Node-only and zero-dependency.
+
 ## Locked decisions
 - **Brand = `Forge`** — CLI `forge`; layer names: skills→**tools**, agents→**crew**,
   hooks→**guards**, code-graph→**atlas**, minimalism→**lean**, memory→**recall**.
@@ -58,6 +63,10 @@ Layers map onto the Claude Code substrate, brand-named, and are emitted cross-to
 Cross-cutting: **atlas** (code-graph), **lean** (shipped as *both* a tool and a
 Stop-guard, so it works whether or not the model invokes it), **recall** (memory).
 
+**cognitive substrate** (`forge substrate`, `forge impact`, and MCP tools
+`substrate_check` / `predict_impact` / `assumption_gate`) composes atlas, preflight,
+route, scope, cortex, and verify into one pre-action contract before mutating work.
+
 ## Component map — the reuse ledger (30 components)
 
 **Reuse (rename + swap brand token, logic unchanged):**

CHANGELOG.md

@@ -6,6 +6,13 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### 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
@@ -76,7 +83,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   check; coverage + type-checking (`tsc --checkJs`); 2026 production-standard rules;
   OWASP-LLM / NIST SSDF / SLSA control mapping.
 
-[Unreleased]: https://github.com/CodeWithJuber/forgekit/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/CodeWithJuber/forgekit/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/CodeWithJuber/forgekit/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/CodeWithJuber/forgekit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/CodeWithJuber/forgekit/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/CodeWithJuber/forgekit/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -41,6 +41,8 @@ npm run check     # Biome lint + format check
 - `source/` — the single rule + MCP source that `forge sync` compiles.
 - `global/` — what installs into `~/.forge`: `tools/` (skills), `crew/` (agents),
   `guards/` (hooks).
+- `docs/cognitive-substrate/` — the committed paper bundle, evidence maps, and prototype
+  artifacts that explain `forge substrate` and `forge impact`.
 - `test/` — `node --test` suites.
 
 ## Before you open a PR
@@ -55,6 +57,10 @@ diffs with no tests) will be closed. To get merged:
   header, or files under `.forge/`. Change the source (`source/`) instead.
 - **Include tests and pass CI.** A small green diff a maintainer can verify beats a large
   one they can't.
+- **Substrate changes need docs.** If you change `forge substrate`, `forge impact`,
+  router/gate rubrics, or MCP substrate tools, update
+  [docs/cognitive-substrate/README.md](./docs/cognitive-substrate/README.md) and
+  `CHANGELOG.md`.
 
 We'd rather give a clear "not now" than merge something that adds maintenance burden — see
 [GOVERNANCE.md](./GOVERNANCE.md).

ONBOARDING.md

@@ -28,7 +28,19 @@ Edit `source/rules.json` (or drop a per-repo `.forge/rules.json`), then:
 forge sync                 # recompiles into every tool; idempotent (only rewrites what changed)
 ```
 
-## 4. Use the extras
+## 4. Use the cognitive substrate
+
+```bash
+forge substrate "<task>"      # ask/route/impact/scope/memory/verify in one pass
+forge substrate "<task>" --json
+forge impact <symbol-or-file>
+```
+
+If `forge substrate` says `ASK FIRST`, ask the returned questions before editing. Read predicted impacted files before making mutating changes.
+
+Paper and evidence package: [docs/cognitive-substrate/](docs/cognitive-substrate/).
+
+## 5. Use the extras
 
 ```bash
 forge atlas build          # index this repo's symbols → .forge/atlas.json

README.md

@@ -21,6 +21,7 @@ Cursor, Gemini CLI, Aider, Copilot, Windsurf/Devin, and Zed**.
 # clone, then:
 bash install.sh          # symlinks into ~/.forge + ~/.claude, puts `forge` on PATH
 forge init               # in any repo: emit every tool's config from one source
+forge substrate "task"   # assumption gate + route + impact + scope + verify
 forge doctor             # verify everything is wired
 ```
 
@@ -91,6 +92,22 @@ On **Claude Code** it's fully ambient (hooks). Other tools read the lessons from
 and a zero-dependency MCP server (`forge cortex-mcp`). Everything lives in `.forge/lessons/`
 — git-committable and auditable. Try it: `node examples/cortex-demo.mjs`.
 
+## Forge Cognitive Substrate — one pre-action gate
+
+Forge now wraps the agent loop with the paper's cognitive-substrate controls. Run one command before ambiguous, expensive, or mutating work:
+
+```bash
+forge substrate "Fix the checkout bug in `src/payments.ts` and add tests"
+forge substrate "Refactor auth" --json
+forge impact computeTax
+```
+
+`substrate` returns the assumption gate, model route, impact radius, scope clusters, relevant Cortex lessons, minimality warnings, and a verification checklist. MCP-capable extensions get the same flow through `substrate_check`, `predict_impact`, and `assumption_gate`. Deterministic checks are asserted; memory relevance, routing fit, and minimality remain advisory where the research is not a hard guarantee.
+
+Full paper bundle and original artifacts live in
+[`docs/cognitive-substrate/`](docs/cognitive-substrate/): PDF, HTML, evidence map,
+ecosystem map, and the original router-gate / impact-oracle prototype packages.
+
 ## Forge Preflight — size the work before spending tokens
 
 An LLM is a fixed-capacity stochastic predictor. Most of the cost/quality bleed comes from
@@ -122,6 +139,8 @@ forge sync        recompile source/ → each tool's native files (idempotent)
 forge doctor      pass/fail health check (layers, install, drift, cortex)
 forge catalog     Start-Here index of every tool/crew/guard
 forge cortex      self-correcting memory — status / why <symbol>
+forge substrate   full pre-action cognitive-substrate check
+forge impact      predict blast radius for a symbol or file
 forge preflight   assumption check — what a task names that the repo doesn't define
 forge route       cheapest capable model for a task (+ gateway config)
 forge scope       decompose files into independent clusters

ROADMAP.md

@@ -5,10 +5,14 @@ Direction, not promises — shaped by the two field reports this project is grou
 
 ## 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`). See
-[CHANGELOG.md](./CHANGELOG.md) `[Unreleased]`.
+(`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]`.
 
 ## 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.
 - **Testing** — Playwright MCP/agents opt-in + a coverage Stop-hook gate.
 - **MCP hygiene** — enforce the ~6-server cap + a registry resolver in `forge doctor`.

SUPPORT.md

@@ -6,6 +6,9 @@ Thanks for using forgekit. Here's where to get help.
 - **Bugs** → open an issue with the bug template (include `forge doctor` output + `node --version`).
 - **Feature ideas** → the feature-request template; for larger changes, start a Discussion first.
 - **Security vulnerabilities** → **do not** open a public issue — see [SECURITY.md](./SECURITY.md).
+- **Cognitive substrate questions** → start with
+  [docs/cognitive-substrate/](./docs/cognitive-substrate/) and include
+  `forge substrate "<task>" --json` output when reporting a bad ask/route/impact decision.
 
 Before opening an issue: run `forge doctor`, search existing issues/discussions, and
 confirm you're on the latest version (`forge --version` vs `npm view forgekit version`).

docs/cognitive-substrate/README.md

@@ -0,0 +1,74 @@
+# Cognitive Substrate Paper Bundle
+
+This directory is the research-backed product map for Forge's cognitive-substrate system.
+It keeps the full paper, evidence maps, and original prototype packages next to the
+production Node implementation so users can install once and use the system from any
+Forge-supported agent.
+
+## Fastest Path
+
+```bash
+# one time, from this repo
+bash install.sh
+
+# one time, inside any project
+forge init
+
+# every day, before ambiguous or mutating work
+forge substrate "Fix the checkout bug and add tests"
+forge substrate "Refactor auth safely" --json
+forge impact computeTax
+```
+
+For MCP-capable tools, call the same flow through:
+
+- `substrate_check` — full pre-action gate.
+- `assumption_gate` — ask/proceed decision and clarifying questions.
+- `predict_impact` — blast-radius prediction for a symbol or file.
+
+## Install Choices
+
+| Path | Best For | Steps |
+| --- | --- | --- |
+| Claude/Codex plugin | Extension-style install | Install the plugin, then run `forge init` in each repo. |
+| Git clone | Lowest friction local setup | `bash install.sh`, then `forge init`. |
+| npm package | CI/devcontainer usage | `npx @codewithjuber/forgekit init`. |
+
+After `forge init`, Forge emits native config for Claude Code, Codex, Cursor, Gemini,
+Aider, Copilot/VS Code, Windsurf/Devin, Zed, Continue, and Roo where supported. Tools
+without hooks receive advisory context plus MCP config; Forge does not pretend it can
+force hooks into hosts that do not expose them.
+
+## Included Artifacts
+
+- [`cognitive_substrate_whitepaper.pdf`](./cognitive_substrate_whitepaper.pdf) — full paper.
+- [`cognitive_substrate_whitepaper.html`](./cognitive_substrate_whitepaper.html) — browser-readable paper.
+- [`deliverable-package.md`](./deliverable-package.md) — package overview and headline results.
+- [`evidence_map.md`](./evidence_map.md) — source/status map for load-bearing evidence.
+- [`ecosystem_map.md`](./ecosystem_map.md) — capability-vs-tooling map.
+- [`impact_oracle_src.zip`](./impact_oracle_src.zip) — original Prototype I package.
+- [`router_gate_src.zip`](./router_gate_src.zip) — original Prototype II package.
+- [`../../research/python-prototypes/`](../../research/python-prototypes/) — unzipped prototype source preserved for auditability.
+
+## Paper-To-Forge Map
+
+| Paper capability | Production Forge surface | Status |
+| --- | --- | --- |
+| Memory | `forge recall`, `forge cortex` | File-backed and auditable; relevance is advisory. |
+| Learning | `forge cortex` | Outcome-confirmed lessons; model weights do not change. |
+| Imagination | `forge impact`, `forge substrate` | Static graph blast-radius simulation. |
+| Self-correction | `forge verify`, doom-loop guard | External checks beat model claims. |
+| Impact-awareness | `forge atlas`, `forge impact` | Known symbols/files and likely dependents surfaced. |
+| M1 routing | `forge route`, `forge substrate` | Transparent cheapest-capable tier recommendation. |
+| M2 assumption gate | `forge preflight`, `forge substrate` | Under-specified tasks return questions. |
+| M3 decomposition | `forge scope`, `forge substrate` | Independent/coupled file clusters. |
+| M4 goal anchoring | `forge substrate` | One pre-action objective/risk/verification summary. |
+| M5 anti-over-engineering | `forge substrate`, `lean-guard` | Broad work gets minimality warnings. |
+| M6 inline verification | `forge verify` | Checklist and external verification discipline. |
+
+## Honest Boundary
+
+Deterministic parts are asserted: repo symbol/file grounding, graph traversal, emitted
+config, protected-file guards, and test/build commands. Research-edge judgments remain
+advisory: memory relevance, model fit, scope minimality, and whether a verification
+checklist is sufficient for a particular production environment.