diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6f9166f..58d6893 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -43,9 +43,9 @@ You author the substrate once. `forge sync` compiles that source into each tool' native config. The four layers are how the brain is expressed; the compiler is how it is delivered. -[![forgekit's architecture: forge sync compiles source/ into native configs for ten tools and configures the four layers (tools, crew, guards, mcp); local events write content-addressed claims to the PCM ledger, independent oracles move their confidence, and teammate ledgers merge through git union-merge](docs/diagrams/system.svg)](https://codewithjuber.github.io/forgekit/diagrams/system.html) +[![forgekit's architecture: forge sync compiles source/ into native configs for ten tools and configures the four layers (tools, crew, guards, mcp); local events write content-addressed claims to the PCM ledger, independent oracles move their confidence, and teammate ledgers merge through git union-merge](docs/diagrams/system.svg)](https://jubershaikh.com/forgekit/diagrams/system.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/system.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/system.html): pan, zoom, search, and trace any node. The four layers, brand-named and emitted cross-tool: @@ -73,9 +73,9 @@ checks and returns a single verdict. It composes the individually-callable stage (`preflight`, `route`, `atlas`, `impact`, `reuse`, `context`, `scope`, `lean`, `anchor`, `verify`) into one pre-action contract. -[![The pre-action gate: referenced entities pass through intake (preflight, route), analysis (atlas, impact, predict, reuse) and safety and fit (context, scope, memory, minimality, goal-anchor) to one verdict](docs/diagrams/pre-action-gate.svg)](https://codewithjuber.github.io/forgekit/diagrams/pre-action-gate.html) +[![The pre-action gate: referenced entities pass through intake (preflight, route), analysis (atlas, impact, predict, reuse) and safety and fit (context, scope, memory, minimality, goal-anchor) to one verdict](docs/diagrams/pre-action-gate.svg)](https://jubershaikh.com/forgekit/diagrams/pre-action-gate.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/pre-action-gate.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/pre-action-gate.html): pan, zoom, search, and trace any node. **blast radius** — the set of files an edit is predicted to impact, read from the code graph. `forge impact` computes it; the pipeline surfaces it before the model touches @@ -112,9 +112,9 @@ claims into `.forge/ledger/`. Because a claim's bytes are a pure function of `(kind, body, scope)`, every replica computes the same identity — so teammate ledgers fold together over plain git with no conflicts. -[![Proof-carrying memory: local events write claims and independent oracles append evidence to .forge/ledger/; a merged read view feeds the recall list, lesson injection and the brain index; teammate ledgers merge through git union-merge and forge ledger merge](docs/diagrams/ledger-flow.svg)](https://codewithjuber.github.io/forgekit/diagrams/ledger-flow.html) +[![Proof-carrying memory: local events write claims and independent oracles append evidence to .forge/ledger/; a merged read view feeds the recall list, lesson injection and the brain index; teammate ledgers merge through git union-merge and forge ledger merge](docs/diagrams/ledger-flow.svg)](https://jubershaikh.com/forgekit/diagrams/ledger-flow.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/ledger-flow.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/ledger-flow.html): pan, zoom, search, and trace any node. Mechanically: evidence and tombstones are append-only, hash-deduped logs; confidence (`val`) is a decayed Beta posterior moved only by oracles; merge is a join-semilattice @@ -129,9 +129,9 @@ Decision recorded in A claim's life, from mint to tombstone: -[![Claim lifecycle: a minted claim starts uncertain; confirmations raise it to trusted and contradictions lower it; below val 0.35 it goes dormant until a later confirmation; idle, duplicate and dormant claims are archived with a reason and new evidence brings them back; forge ledger retract tombstones a claim permanently; a reworded lesson is minted as a new claim](docs/diagrams/claim-lifecycle.svg)](https://codewithjuber.github.io/forgekit/diagrams/claim-lifecycle.html) +[![Claim lifecycle: a minted claim starts uncertain; confirmations raise it to trusted and contradictions lower it; below val 0.35 it goes dormant until a later confirmation; idle, duplicate and dormant claims are archived with a reason and new evidence brings them back; forge ledger retract tombstones a claim permanently; a reworded lesson is minted as a new claim](docs/diagrams/claim-lifecycle.svg)](https://jubershaikh.com/forgekit/diagrams/claim-lifecycle.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/claim-lifecycle.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/claim-lifecycle.html): pan, zoom, search, and trace any node. ## 4. The reuse / context loop @@ -140,9 +140,9 @@ when its evidence still holds — the confidence is above the floor _and_ its at dependencies still resolve. Otherwise it falls through to generation and mints a fresh claim on the way back. -[![Reuse cache: a spec is looked up by a lossless exact key, then by MinHash and LSH similarity checked by a semantic guard (operators, numbers, literals); a hit is served only while the proof check holds (confidence at least 0.6) and is flagged as not revalidated when there is no atlas; a match that differs is only an adapt-tier candidate; a miss is generated, verified and minted as a claim into .forge/ledger/](docs/diagrams/reuse-cache.svg)](https://codewithjuber.github.io/forgekit/diagrams/reuse-cache.html) +[![Reuse cache: a spec is looked up by a lossless exact key, then by MinHash and LSH similarity checked by a semantic guard (operators, numbers, literals); a hit is served only while the proof check holds (confidence at least 0.6) and is flagged as not revalidated when there is no atlas; a match that differs is only an adapt-tier candidate; a miss is generated, verified and minted as a claim into .forge/ledger/](docs/diagrams/reuse-cache.svg)](https://jubershaikh.com/forgekit/diagrams/reuse-cache.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/reuse-cache.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/reuse-cache.html): pan, zoom, search, and trace any node. The completeness gate on the retrieval side is `forge context ""`: it pins the required-knowledge set for the edit (`R(edit)`), downgrades items along a compression ladder @@ -167,9 +167,9 @@ synthesis §5.3, corrected 2026-09-21). Where those deterministic checks run in one Claude Code session: -[![One Claude Code session with forgekit's hooks: SessionStart injects learned lessons and the last handoff; UserPromptSubmit runs cortex and preflight against the cached atlas and returns an advisory; PreToolUse runs protect-paths, cost-budget, doom-loop and cortex pre-edit and allows or denies the call; PostToolUse formats, redacts secrets and captures evidence; Stop runs the completion gate, lean guard and session learner and distills lessons into the ledger](docs/diagrams/hook-sequence.svg)](https://codewithjuber.github.io/forgekit/diagrams/hook-sequence.html) +[![One Claude Code session with forgekit's hooks: SessionStart injects learned lessons and the last handoff; UserPromptSubmit runs cortex and preflight against the cached atlas and returns an advisory; PreToolUse runs protect-paths, cost-budget, doom-loop and cortex pre-edit and allows or denies the call; PostToolUse formats, redacts secrets and captures evidence; Stop runs the completion gate, lean guard and session learner and distills lessons into the ledger](docs/diagrams/hook-sequence.svg)](https://jubershaikh.com/forgekit/diagrams/hook-sequence.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/hook-sequence.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/hook-sequence.html): pan, zoom, search, and trace any node. **The completion gate (Stop, `src/gate.js`).** The only Stop-path guard that may answer: `completion-gate.sh` runs synchronously (the lesson-mining `cortex.sh stop` stays @@ -342,9 +342,9 @@ hook never ran, or a session whose one Stop block was already spent. Plain `forge verify`, end to end: -[![forge verify: suites are planned for the root and every nested package that declares one; the code state (HEAD, staged and unstaged diffs, untracked files) is captured before and after each suite runs in its own directory, and a change during the run makes the result INCOMPLETE; the verdict is PASS, FAIL, INCOMPLETE or NOT_CONFIGURED; a hallucinated-symbol check runs against the atlas; the result is sealed in .forge/provenance.json and a verifier event is appended to .forge/verify-events.jsonl](docs/diagrams/verify-pipeline.svg)](https://codewithjuber.github.io/forgekit/diagrams/verify-pipeline.html) +[![forge verify: suites are planned for the root and every nested package that declares one; the code state (HEAD, staged and unstaged diffs, untracked files) is captured before and after each suite runs in its own directory, and a change during the run makes the result INCOMPLETE; the verdict is PASS, FAIL, INCOMPLETE or NOT_CONFIGURED; a hallucinated-symbol check runs against the atlas; the result is sealed in .forge/provenance.json and a verifier event is appended to .forge/verify-events.jsonl](docs/diagrams/verify-pipeline.svg)](https://jubershaikh.com/forgekit/diagrams/verify-pipeline.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/verify-pipeline.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/verify-pipeline.html): pan, zoom, search, and trace any node. **Deep verification (`src/consensus.js`, `forge verify --deep`).** Where plain `verify` asks one oracle (the tests) plus one heuristic, this runs a table of independent lenses diff --git a/CHANGELOG.md b/CHANGELOG.md index 36255b1..f478ce6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Changed + +- **The site's canonical URL is `https://jubershaikh.com/forgekit/`.** GitHub Pages serves the + project site from that custom domain, and `codewithjuber.github.io/forgekit/` only redirects + there. `brand.json`, the landing and 404 pages (canonical, Open Graph and JSON-LD) and every + diagram link now point at the custom domain directly, so links and link previews skip the + redirect. + ## [1.7.1] - 2026-09-26 ### Fixed diff --git a/ONBOARDING.md b/ONBOARDING.md index 9ceded8..54f2ff9 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -11,9 +11,9 @@ Windsurf, Zed, Continue, and OpenClaw at once. Author it once; every tool reads This page is the fast path: install, configure a repo, do a task, and watch the ledger start paying off on day two. -[![Guided onboarding: forge init configures your tools from one source; then for each task you work as usual, the substrate checks whether to ask first, which model to use and what breaks, the agent edits with guardrails, and cortex learns from corrections so the next task is smarter](docs/diagrams/onboarding-loop.svg)](https://codewithjuber.github.io/forgekit/diagrams/onboarding-loop.html) +[![Guided onboarding: forge init configures your tools from one source; then for each task you work as usual, the substrate checks whether to ask first, which model to use and what breaks, the agent edits with guardrails, and cortex learns from corrections so the next task is smarter](docs/diagrams/onboarding-loop.svg)](https://jubershaikh.com/forgekit/diagrams/onboarding-loop.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/onboarding-loop.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/onboarding-loop.html): pan, zoom, search, and trace any node. ## 1. Install (once) diff --git a/README.md b/README.md index dad9bf9..313e52a 100644 --- a/README.md +++ b/README.md @@ -132,9 +132,9 @@ Forgekit supplies an external reliability layer: Forgekit runs a deterministic substrate before work, lets the external coding agent act, and records evidence from tests, CI, or explicit human correction afterwards. -[![How forgekit fits around a coding agent: a task goes through the pre-action substrate; missing information sends it back to clarify first, enough information lets the agent act, and the outcome is recorded in memory that feeds the next check](docs/diagrams/core-loop.svg)](https://codewithjuber.github.io/forgekit/diagrams/core-loop.html) +[![How forgekit fits around a coding agent: a task goes through the pre-action substrate; missing information sends it back to clarify first, enough information lets the agent act, and the outcome is recorded in memory that feeds the next check](docs/diagrams/core-loop.svg)](https://jubershaikh.com/forgekit/diagrams/core-loop.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/core-loop.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/core-loop.html): pan, zoom, search, and trace any node. Only independent oracles (tests, CI, a human accept/revert) move a memory's confidence — so a wrong lesson decays out instead of ossifying. Full design: diff --git a/brand.json b/brand.json index 88bd568..e8ac661 100644 --- a/brand.json +++ b/brand.json @@ -13,7 +13,7 @@ "recall": "cross-session memory" }, "site": { - "url": "https://codewithjuber.github.io/forgekit/", + "url": "https://jubershaikh.com/forgekit/", "repo": "https://github.com/CodeWithJuber/forgekit" }, "fonts": { diff --git a/docs/GUIDE.md b/docs/GUIDE.md index 0d4cfe6..d9bd6e3 100644 --- a/docs/GUIDE.md +++ b/docs/GUIDE.md @@ -70,9 +70,9 @@ substrate** (`forge substrate` — the pre-action check). The full argument is t The daily loop — every outcome an oracle observes lands in the team ledger, and the ledger informs the next task: -[![The team loop: substrate pre-checks, then the edit; oracles (forge verify, forge imagine --run, CI, a human accept or revert) record outcomes that move each claim's value in the team ledger in .forge/ledger/; teammates' ledgers merge through git and forge ledger merge; lessons, facts and reuse hits feed the next pre-check](diagrams/team-loop.svg)](https://codewithjuber.github.io/forgekit/diagrams/team-loop.html) +[![The team loop: substrate pre-checks, then the edit; oracles (forge verify, forge imagine --run, CI, a human accept or revert) record outcomes that move each claim's value in the team ledger in .forge/ledger/; teammates' ledgers merge through git and forge ledger merge; lessons, facts and reuse hits feed the next pre-check](diagrams/team-loop.svg)](https://jubershaikh.com/forgekit/diagrams/team-loop.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/team-loop.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/team-loop.html): pan, zoom, search, and trace any node. ```bash cd your-project @@ -670,9 +670,9 @@ The independent check: runs the real test suite and flags edited symbols that ar the codebase (possible hallucinations). This is what turns "the model says it's done" into "the tests say it's done." -[![forge verify: suites are planned for the root and every nested package that declares one; the code state (HEAD, staged and unstaged diffs, untracked files) is captured before and after each suite runs in its own directory, and a change during the run makes the result INCOMPLETE; the verdict is PASS, FAIL, INCOMPLETE or NOT_CONFIGURED; a hallucinated-symbol check runs against the atlas; the result is sealed in .forge/provenance.json and a verifier event is appended to .forge/verify-events.jsonl](diagrams/verify-pipeline.svg)](https://codewithjuber.github.io/forgekit/diagrams/verify-pipeline.html) +[![forge verify: suites are planned for the root and every nested package that declares one; the code state (HEAD, staged and unstaged diffs, untracked files) is captured before and after each suite runs in its own directory, and a change during the run makes the result INCOMPLETE; the verdict is PASS, FAIL, INCOMPLETE or NOT_CONFIGURED; a hallucinated-symbol check runs against the atlas; the result is sealed in .forge/provenance.json and a verifier event is appended to .forge/verify-events.jsonl](diagrams/verify-pipeline.svg)](https://jubershaikh.com/forgekit/diagrams/verify-pipeline.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/verify-pipeline.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/verify-pipeline.html): pan, zoom, search, and trace any node. ```console $ forge verify diff --git a/docs/UNIVERSAL_ROUTING.md b/docs/UNIVERSAL_ROUTING.md index c4a123c..cb5af22 100644 --- a/docs/UNIVERSAL_ROUTING.md +++ b/docs/UNIVERSAL_ROUTING.md @@ -14,9 +14,9 @@ The router code names no vendor, model, tier or threshold, and a test enforces t How a recommendation is chosen, run and learned from: -[![forge route universal: the task's 12 features and each model's P(solve) and expected cost select the cheapest cascade that meets the objective, or report INFEASIBLE with a labeled least-bad fallback; each attempt is checked by tests or forge verify, a failure escalates to the next model, and forge route outcome records each outcome for forge route fit, which refits a local estimate shrunk toward the shipped prior](diagrams/router-cascade.svg)](https://codewithjuber.github.io/forgekit/diagrams/router-cascade.html) +[![forge route universal: the task's 12 features and each model's P(solve) and expected cost select the cheapest cascade that meets the objective, or report INFEASIBLE with a labeled least-bad fallback; each attempt is checked by tests or forge verify, a failure escalates to the next model, and forge route outcome records each outcome for forge route fit, which refits a local estimate shrunk toward the shipped prior](diagrams/router-cascade.svg)](https://jubershaikh.com/forgekit/diagrams/router-cascade.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/router-cascade.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/router-cascade.html): pan, zoom, search, and trace any node. ## The model diff --git a/docs/cognitive-substrate/README.md b/docs/cognitive-substrate/README.md index d7007cb..cc16713 100644 --- a/docs/cognitive-substrate/README.md +++ b/docs/cognitive-substrate/README.md @@ -202,9 +202,9 @@ Set **`FORGE_LLM=1`** to add a **thin, opt-in semantic layer** on top: a cheap ` call proposes a completeness reading (M2), a complexity band (M1), the coupled edges the regex graph misses (impact), and whether an off-goal file actually serves the goal (M4). -[![Rubric first, LLM second: a task or edit goes to the deterministic rubric and, when FORGE_LLM=1, to an LLM proposer whose proposal is verified against the rubric band, repository grounding (grep) and tests; the verdict moves (llm-cleared, lowered, raised or verified) only when the proposal passes those checks, and otherwise the deterministic verdict holds](../diagrams/llm-reconcile.svg)](https://codewithjuber.github.io/forgekit/diagrams/llm-reconcile.html) +[![Rubric first, LLM second: a task or edit goes to the deterministic rubric and, when FORGE_LLM=1, to an LLM proposer whose proposal is verified against the rubric band, repository grounding (grep) and tests; the verdict moves (llm-cleared, lowered, raised or verified) only when the proposal passes those checks, and otherwise the deterministic verdict holds](../diagrams/llm-reconcile.svg)](https://jubershaikh.com/forgekit/diagrams/llm-reconcile.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/llm-reconcile.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/llm-reconcile.html): pan, zoom, search, and trace any node. The model **proposes**; the deterministic rubric, the code graph, and the tests **verify**. The verdict only moves when the proposal survives that check — otherwise it falls back, unchanged. diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md index 4c3bf1d..41b949d 100644 --- a/docs/diagrams/README.md +++ b/docs/diagrams/README.md @@ -6,7 +6,7 @@ folder. Nobody hand-draws a diagram or hand-edits a rendered file. `forge docs c rejects a hand-written Mermaid block in any tracked Markdown or MDX file, and it rejects an embed that names a diagram the manifest does not register. -**Browse them:** https://codewithjuber.github.io/forgekit/diagrams/. Each diagram opens as +**Browse them:** https://jubershaikh.com/forgekit/diagrams/. Each diagram opens as an interactive page where you can pan, zoom and search (`/`). Press `?` for the guide, and select a node to trace what it depends on and what depends on it. @@ -52,7 +52,7 @@ To add a diagram, create its source and add an entry `{ "id", "type", "usedIn": - **Markdown (GitHub, npm):** link the SVG to its interactive page: ```md - [![Alt text that says what the diagram shows](docs/diagrams/core-loop.svg)](https://codewithjuber.github.io/forgekit/diagrams/core-loop.html) + [![Alt text that says what the diagram shows](docs/diagrams/core-loop.svg)](https://jubershaikh.com/forgekit/diagrams/core-loop.html) ``` - **Docs site (Mintlify):** put the copy in a ``, then add a link to the interactive diff --git a/docs/plans/substrate-v2/00-overview.md b/docs/plans/substrate-v2/00-overview.md index db47a37..94bb870 100644 --- a/docs/plans/substrate-v2/00-overview.md +++ b/docs/plans/substrate-v2/00-overview.md @@ -77,9 +77,9 @@ are partial** — their acceptance criteria are not met (reasons in the table). Each phase is labeled done or partial; a dashed arrow touches a partial phase. -[![Substrate v2 phases: P0 specs leads to P1 ledger core, which feeds P2 team sync, P3 reuse cache, P4 context assembly and P6 UI quality gate; P4 leads to P5 loop closure; P2, P5 and P6 feed P7 dashboard; P3 and P5 feed P8 evaluation; P4 and P8 are partial, the rest are done](../../diagrams/phase-map.svg)](https://codewithjuber.github.io/forgekit/diagrams/phase-map.html) +[![Substrate v2 phases: P0 specs leads to P1 ledger core, which feeds P2 team sync, P3 reuse cache, P4 context assembly and P6 UI quality gate; P4 leads to P5 loop closure; P2, P5 and P6 feed P7 dashboard; P3 and P5 feed P8 evaluation; P4 and P8 are partial, the rest are done](../../diagrams/phase-map.svg)](https://jubershaikh.com/forgekit/diagrams/phase-map.html) -[Open the interactive diagram](https://codewithjuber.github.io/forgekit/diagrams/phase-map.html): pan, zoom, search, and trace any node. +[Open the interactive diagram](https://jubershaikh.com/forgekit/diagrams/phase-map.html): pan, zoom, search, and trace any node. | Phase | Delivers | Depends on | Acceptance | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------- | diff --git a/landing/404.html b/landing/404.html index 9091cea..ff1269d 100644 --- a/landing/404.html +++ b/landing/404.html @@ -9,17 +9,17 @@ content="Shared memory, impact analysis, and guardrail hooks for AI coding agents — authored once, emitted as native config for Claude Code, Codex, Cursor, Gemini, Aider, and more." /> - + - + - + @@ -28,7 +28,7 @@ name="twitter:description" content="Shared memory, impact analysis, and guardrail hooks for AI coding agents — authored once, emitted as native config for Claude Code, Codex, Cursor, Gemini, Aider, and more." /> - + diff --git a/landing/index.html b/landing/index.html index 91659f7..0035daf 100644 --- a/landing/index.html +++ b/landing/index.html @@ -7,22 +7,22 @@ - - - + + + - - + + - - + +