Skip to content

feat: formal-synthesis paper features (v2) — know, precommit, verify --deep, radar, ledger sync, deja, dash v2, report + Mintlify docs #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CodeWithJuber merged 12 commits into from
Jul 17, 2026
Merged

feat: formal-synthesis paper features (v2) — know, precommit, verify --deep, radar, ledger sync, deja, dash v2, report + Mintlify docs #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
276e039
feat(know): A7 knowledge-router — total routing of facts to storage h…
claude Jul 17, 2026
647b8eb
feat(precommit): commit-level gate rung (F1 classifier + secret scan)…
claude Jul 17, 2026
35d4c4a
feat(update): --to <version> pin/downgrade
claude Jul 17, 2026
6cf4db7
feat(verify): multi-lens consensus (noisy-OR + cross-family gate, opt…
claude Jul 17, 2026
262c53d
feat(radar): dependency-currency rings from evidence + I4 ledger reco…
claude Jul 17, 2026
679c99d
feat(ledger): sync — git-ref/dir CRDT push-pull, --personal recall po…
claude Jul 17, 2026
71194fd
feat(deja): session summary claims + similar-task lookup + preflight …
claude Jul 17, 2026
f411605
feat(dash): v2 — live refresh, history trends, radar/memory/gate/time…
claude Jul 17, 2026
91a627e
feat(report): static self-contained HTML report emit
claude Jul 17, 2026
f7f7ba4
docs(mintlify): user-facing documentation site (docs.json + MDX)
claude Jul 17, 2026
eb47396
fix(review): narrow verify --deep secret lens, fix dash radar field r…
claude Jul 17, 2026
f173644
style(biome): apply canonical formatting to review-fix files
claude Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .github/workflows/docs-links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
name: docs-links

# Advisory broken-link check for the Mintlify site. Runs only on PRs that touch the
# mintlify/ folder. Non-blocking: the job reports findings but does not fail the PR
# (continue-on-error), so a transient link check never gates a merge. Mintlify deploys
# via its GitHub App, not from CI — there is intentionally no deploy workflow here.

on:
pull_request:
paths:
- "mintlify/**"
workflow_dispatch: {}

permissions:
contents: read

jobs:
broken-links:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"

- name: Check internal links
working-directory: mintlify
continue-on-error: true
run: npx --yes mintlify broken-links
83 changes: 83 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,89 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- **`forge know` — the A7 knowledge-router.** Total routing (formal-synthesis
Theorem T6) of any fact to its storage home: exemplar k-NN over a labeled bank
(`src/knowledge_router.js`) picks among claude-md / rule / skill / state /
decision / ledger-fact / recall; below-confidence facts fall back to the ledger
(provenance `fallback`) instead of being dropped. Append-only homes are written
directly (decide log, repo-ledger fact claim, personal recall store), curated
files get advice naming the right command, secrets are refused before dispatch,
and `--dry-run`/`--json` route without writing. Distilled Cortex lessons that
read like decisions or durable facts auto-route to those homes (fail-open).
- **Commit-level gate rung (`forge precommit`).** The gate lattice's middle rung
(turn ⊂ commit ⊂ PR): `src/commit_gate.js` classifies staged files with the same
registry-derived classifier as the Stop gate (code staged with no doc/state artifact
→ finding) and runs the built-in secret detector over staged added lines as a
gitleaks fallback. `FORGE_COMMIT_GATE` sets the mode (`warn` default · `block` ·
`0` kill switch); a detected secret blocks in every mode. `forge harden` now installs
a pre-commit hook that runs gitleaks when present, then the commit gate — and never
clobbers a user-authored hook (writes `pre-commit.forge` beside it instead).
- **Pin/downgrade via `update --to <version>`.** New `applyUpdateTo` in
`src/update.js`: for a git checkout it fetches tags, verifies the release tag
exists (unknown version → honest miss, never a throw), and detached-checkouts
the tag with a note on how to return to latest; npm-global installs get the
exact `npm i -g <pkg>@<version>` instruction instead.
- **Multi-lens verification consensus.** `forge verify --deep` (new `src/consensus.js`)
runs a LENSES table over the diff — tests, unknown symbols, unreviewed impact
radius, docs drift, secrets in added lines, spec-lock drift, plus an optional
`--llm` majority-of-3 reviewer panel — and aggregates noisy-OR
`P(defect)=1−∏(1−wᵢsᵢ)` with the same cross-family gate as the lesson miner: a
lone structural signal (or the model reviewer alone) never blocks; a failing test
suite or a leaked secret blocks solo. Findings extend `.forge/provenance.json`
with per-lens evidence and the Theorem-D residual `∏(1−cⱼ)` over the lenses that
ran, and each run appends one `stage:"verify"` metrics record.
- **`forge radar` — dependency-currency rings (I4 verified currency).** New zero-dep
`src/radar.js` reads this repo's Node manifests, probes the registry (injectable
`fetchImpl`; metadata + bulk advisories; 4s timeout) and classifies every dependency
into an adopt/trial/assess/hold ring from _evidence_ — staleness (540-day half-life),
major-version lag, severity-weighted advisories, deprecation; atlas usage is stakes,
not risk. Deprecated or a critical advisory → `hold`; fewer than two verified evidence
kinds → `assess` (never adopt on absence). Cached at `.forge/radar.json`
(`FORGE_RADAR_TTL_H`, default 24h); `--offline` serves the stale cache or fails
honestly; `--refresh` re-probes; `--json` for tooling. A network scan records I4
evidence into the ledger (`currency:<dep>` facts, supersede semantics) plus a metrics
line, and the pre-edit hook surfaces a cache-only advisory when a file imports a `hold`
dependency (kill switch `FORGE_RADAR=0`).
- **Cross-machine memory sync.** `forge ledger sync` push-pulls the PCM ledger through a
git ref (`refs/forge/ledger` via `hash-object`/`mktree`/`commit-tree` plumbing;
non-fast-forward races re-merge and retry ≤3 — monotone by the CRDT join, so nothing is
lost) or a shared directory (bidirectional union-merge; `FORGE_SYNC_DIR` is the default
dir target). Target precedence: `--dir` > `--remote`/`--ref` > the repo's git remote >
`FORGE_SYNC_DIR` > an honest "no target". `--personal` syncs the per-user ledger beside
the recall store, making recall facts portable across machines. Fails open (offline,
missing remote, or corrupt remote blob → an honest reason, never a throw); the git
runner is injectable so tests drive it with local bare remotes and never touch the
network.
- **Anti-repetition memory (`forge deja`).** A first-try success mints no Cortex lesson,
so its trace used to be discarded when the session ended — the root of cross-session
repetition. Now every session Stop mints one `summary` claim (an existing ledger kind)
with a secret-redacted gist of the task and the files touched, attaching a `test.run`
confirm outcome when the session's own tests passed (so verified work outranks a mere
attempt). New `src/deja.js` `dejaLookup` ranks prior summaries/lessons/diagnoses via the
same Eq. 3 retrieval as `ledger query`; `forge deja "<task>"` surfaces them, and the
pre-action substrate shows a one-line "déjà vu" advisory when a prompt matches prior
solved work. Kill switch `FORGE_DEJA=0`. Because summaries are ordinary ledger claims,
`forge ledger merge` carries them between machines.
- **Dashboard v2 (`forge dash`).** The localhost lens gains four panels over the
durable `.forge/` stores plus live refresh: Radar (dependency-currency rings read
from the `.forge/radar.json` cache — never fetches), Trends (per-stage
`metrics.jsonl` history bucketed by day as inline-SVG sparklines, 90-day window),
Memory browser (ranked recall search over the ledger via `retrieve`, with
confidence and freshness bars), and Session timeline (durable mint/tombstone events
across sessions). New read-only endpoints `GET /api/history`, `/api/claims?q=&kind=`,
`/api/radar`, and `/api/timeline`; the page polls every 5s, paused while the tab is
hidden. The append-only write discipline (only `POST /api/ratify` and `/api/retract`)
is unchanged, and corrupt or missing stores degrade to empty sections.
- **Static HTML report (`forge report`).** New zero-dep `src/report.js` emits a
self-contained `.forge/report.html` — the offline twin of `forge dash` (no server, no
fetch, no CDN, no JS to read it). `renderReport` is pure and reuses `dashData`, buckets
`metrics.jsonl` into a 90-day activity sparkline (server-side inline SVG), reads the
`.forge/radar.json` cache directly and defensively (absent → the radar section is
omitted), and draws its palette from `rootTokensCss()` so it matches the dashboard.
`--out <path>` overrides the default location.

## [0.19.0] - 2026-07-17

### Added
Expand Down
92 changes: 54 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,44 +173,50 @@ Output is plain text when piped; on a TTY it adds brand-palette color and confid
meters. `NO_COLOR` turns color off, `FORCE_COLOR=1` forces it on (e.g. in CI, `0`
forces off), and `TERM`/`COLORTERM` follow the usual terminal conventions.

| Group | Command | Does |
| -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Config layer** | `forge init` | emit every tool's native config from one source |
| | `forge sync` | recompile canonical source → each tool's native files (idempotent) |
| | `forge doctor` | pass/fail health check: tools, guards, MCP, drift, update |
| | `forge update` | self-update — `--check` reports if a newer version exists, bare applies it |
| | `forge docs` | docs↔code drift — `check` reconciles commands/env/MCP/CHANGELOG; `sync` sweeps the diff for stale doc mentions |
| | `forge config` | provider setup — show / switch / add providers, set the default model |
| | `forge harden` | wire gitleaks pre-commit + sandbox settings |
| | `forge catalog` | Start-Here index of every tool / crew / guard |
| | `forge brand` | print the brand token map |
| **Memory & team** | `forge ledger` | proof-carrying memory — stats / verify / show / blame / query / ratify / retract / merge / import |
| | `forge recall` | cross-session personal memory — list / add / consolidate |
| | `forge remember` | durable, repo-committable fact |
| | `forge brain` | portable project-memory index |
| | `forge cortex` | self-correcting lessons — `status` / `why` |
| | `forge reuse` | proof-carrying code cache — query / mint / stats |
| | `forge handoff` | bounded session snapshot (`.forge/state.md`) — rewritten each handoff, re-injected every session start |
| | `forge decide` | append-only decision log (`.forge/decisions.md`, D-#### ADR-lite) — future sessions read it instead of re-deciding |
| **Substrate (pre-action)** | `forge substrate` | the full pre-action gate in one pass |
| | `forge preflight` | assumption / info-gap check |
| | `forge route` | cheapest capable model tier (`route gateway` emits LiteLLM config) |
| | `forge impact` | predict blast radius for a symbol or file |
| | `forge scope` | cluster + surface coupled files |
| | `forge imagine` | consequence sim + minimal dry-run suite (`--run` executes it sandboxed) |
| | `forge context` | budgeted context assembly + completeness gate |
| | `forge atlas` | build / query / has (hallucinated-symbol check) the code graph |
| | `forge stack` | detect this repo's real stack (languages, frameworks, test commands) from its manifests |
| | `forge anchor` | goal-drift check (advisory) — `set`/`show`/`clear` persists the goal across sessions |
| | `forge diagnose` | doom-loop: same failure 3× → diagnosis + escalation |
| | `forge lean` | scope-minimality footprint (advisory) |
| | `forge cost` | real per-day spend · measured stage factors (`--stages`) |
| **Verification & safety** | `forge verify` | independent gate — tests + hallucinated-symbol flag + provenance |
| | `forge scan` | skill-gate: vet a SKILL.md / .mcp.json for injection / RCE / exfil |
| | `forge spec` | spec-as-contract drift — init / lock / check |
| **UI / design** | `forge taste` | pick one visual direction → DESIGN.md |
| | `forge uicheck` | contrast · fingerprint · design · visual (WCAG · slop+conformance · Playwright) |
| **Observability** | `forge dash` | localhost-only read-only dashboard over ledger, metrics, blast radius (default port 4242) |
| Group | Command | Does |
| -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Config layer** | `forge init` | emit every tool's native config from one source |
| | `forge sync` | recompile canonical source → each tool's native files (idempotent) |
| | `forge doctor` | pass/fail health check: tools, guards, MCP, drift, update |
| | `forge update` | self-update — `--check` reports if a newer version exists, bare applies it, `--to <version>` pins/downgrades |
| | `forge docs` | docs↔code drift — `check` reconciles commands/env/MCP/CHANGELOG; `sync` sweeps the diff for stale doc mentions |
| | `forge config` | provider setup — show / switch / add providers, set the default model |
| | `forge harden` | wire the pre-commit gate (gitleaks + commit gate) + sandbox settings |
| | `forge catalog` | Start-Here index of every tool / crew / guard |
| | `forge brand` | print the brand token map |
| **Memory & team** | `forge ledger` | proof-carrying memory — stats / verify / show / blame / query / ratify / retract / merge / sync / import |
| | `forge recall` | cross-session personal memory — list / add / consolidate |
| | `forge remember` | durable, repo-committable fact |
| | `forge brain` | portable project-memory index |
| | `forge cortex` | self-correcting lessons — `status` / `why` |
| | `forge deja` | anti-repetition — ranks prior solved/verified sessions for a task you're about to start (`FORGE_DEJA=0` disables) |
| | `forge reuse` | proof-carrying code cache — query / mint / stats |
| | `forge handoff` | bounded session snapshot (`.forge/state.md`) — rewritten each handoff, re-injected every session start |
| | `forge decide` | append-only decision log (`.forge/decisions.md`, D-#### ADR-lite) — future sessions read it instead of re-deciding |
| | `forge know` | route any fact to its storage home (decision / ledger / recall / …) — total routing, an unsure fact still lands |
| **Substrate (pre-action)** | `forge substrate` | the full pre-action gate in one pass |
| | `forge preflight` | assumption / info-gap check |
| | `forge route` | cheapest capable model tier (`route gateway` emits LiteLLM config) |
| | `forge impact` | predict blast radius for a symbol or file |
| | `forge scope` | cluster + surface coupled files |
| | `forge imagine` | consequence sim + minimal dry-run suite (`--run` executes it sandboxed) |
| | `forge context` | budgeted context assembly + completeness gate |
| | `forge atlas` | build / query / has (hallucinated-symbol check) the code graph |
| | `forge stack` | detect this repo's real stack (languages, frameworks, test commands) from its manifests |
| | `forge anchor` | goal-drift check (advisory) — `set`/`show`/`clear` persists the goal across sessions |
| | `forge diagnose` | doom-loop: same failure 3× → diagnosis + escalation |
| | `forge lean` | scope-minimality footprint (advisory) |
| | `forge cost` | real per-day spend · measured stage factors (`--stages`) |
| **Verification & safety** | `forge verify` | independent gate — tests + hallucinated-symbol flag + provenance; `--deep` multi-lens consensus (`--llm` reviewer panel) |
| | `forge precommit` | commit-level gate rung — staged code w/o docs + secret scan (`FORGE_COMMIT_GATE=block\|warn\|0`) |
| | `forge radar` | dependency-currency rings (adopt/trial/assess/hold) from registry evidence — cached, offline-honest |
| | `forge scan` | skill-gate: vet a SKILL.md / .mcp.json for injection / RCE / exfil |
| | `forge spec` | spec-as-contract drift — init / lock / check |
| **UI / design** | `forge taste` | pick one visual direction → DESIGN.md |
| | `forge uicheck` | contrast · fingerprint · design · visual (WCAG · slop+conformance · Playwright) |
| **Observability** | `forge dash` | localhost-only live dashboard: ledger, metrics trends, radar rings, memory browser, session timeline, blast radius (default port 4242) |
| | `forge report` | static, self-contained HTML snapshot of `.forge/` (`.forge/report.html`) — opens offline, no server |


**→ Every command with a worked example and real output:
[`docs/GUIDE.md`](docs/GUIDE.md).**
Expand All @@ -225,12 +231,22 @@ built to merge without conflicts:
forge init # once — also emits the .gitattributes union-merge rule the ledger needs
# …work normally: cortex and `forge remember` shadow claims into the ledger as you go…
git pull && forge ledger merge <path-to-their-ledger> # fold in a teammate's ledger — any order
forge ledger sync # push-pull the ledger through a git ref (refs/forge/ledger) or a shared dir — CRDT, any order
```

Identical knowledge minted independently converges to **one** claim with every author
preserved in its provenance; `forge ledger blame <id>` shows who minted it, every oracle
outcome, and per-author trust. No server, no sync service — it's just files in git.

`forge ledger sync` moves that state between machines without a merge argument: with no
flags it uses the repo's git remote, serializing the ledger to a `state.json` blob under a
dedicated ref (`refs/forge/ledger`) — a raced non-fast-forward push re-merges and retries,
monotone by the CRDT join, so nothing is ever lost. Point it at a shared folder with
`--dir <path>` (or set **`FORGE_SYNC_DIR`** as the default dir target when there's no
remote), and add `--personal` to sync the per-user ledger beside the recall store — the
one `forge recall add` shadows facts into — so your personal facts follow you across
machines.

## How it compares

Structural differences only — each row is checkable against the named source, and the full
Expand Down
Loading
Loading