The problem
You have seen every one of these.
| What happened | Why it happened | The FORGE gate |
|---|---|---|
| The agent rewrote a file it was never supposed to touch. | Authorization lived in a prompt, not in a machine-readable boundary. | TARGET_BOUNDARIES — authorized and forbidden paths compiled into every payload. |
| You asked for a feature. It confidently built the wrong one. | Intent written in ambiguous language: "handle appropriately", "as needed". | ambiguous-language lint — 17 banned phrases block compilation outright. |
| The happy path works. The first edge case crashed production. | Nobody wrote the failure cases down, so the agent never built them. | unhappy-path-ratio — edge steps must be ≥ 50% of happy-path steps to lint. |
| The change worked — and silently broke two unrelated routes. | Nothing declared what must not break. | REGRESSION_FENCE — explicit preservation rules, required in every spec. |
| Six months later, nobody remembers why it was built that way. | The rationale lived in a chat thread that is gone. | CONTEXT_DEBT_NOTE — required, linted, and versioned with the code. |
Platform
How the pipeline works.
The enforced sequence — every task
RSC-AR adversarial hardening loop
Phase 1
Proposer
Drafts the .logic spec. No TODOs, no placeholders, no ambiguous language — a complete first position.
Phase 2
Adversary
Inverts persona and attacks every claim: authorization violations, hallucinated APIs, missing failure cases, invariant gaps. Every PASS verdict must carry a one-line justification.
Phase 3
Resolver
Applies every surviving fix and outputs the hardened .logic file. forge lint must exit 0 before delivery. New assumptions re-enter Phase 2 — max 3 cycles.
Lint rules — a spec that does not lint does not compile
| Rule | Severity | What it enforces |
|---|---|---|
| required-sections | error | All 5 sections must be present and non-empty |
| forbidden-overlap | error | No file in both authorized_files and forbidden_files |
| unhappy-path-ratio | error | EDGE steps must be ≥ 50% of INTENT steps |
| ambiguous-language | error | 17 banned phrases blocked in INTENT sections |
| stale-validation | warning | validated_against must be within 30 days of today |
Coverage gates
CI blocks deploys when coverage drops
forge coverage --threshold 80 exits 1 if fewer than 80% of registered services have a spec. Raise the threshold quarterly to ratchet coverage.
Collision detection via forge validate catches forbidden-exposure, domain-overlap, and shared-authorization conflicts across all specs at once.
MCP tool surface — every command, callable in conversation
LSD FORGE ships a zero-dependency MCP server. Run forge mcp to print the exact config block for Claude Desktop, VS Code, or any stdio MCP host.
| Tool | What it does |
|---|---|
| forge_new | Collect answers in conversation and create a new .logic spec |
| forge_lint | Lint a spec and return findings |
| forge_compile | Compile a spec and return the agent payload string |
| forge_status | Project integration health |
| forge_coverage | Spec coverage gap report |
| forge_validate | Cross-spec collision detection |
| forge_spec_list | List all specs with ID, domain, and pass/fail |
Full CLI command surface
forge init
Bootstrap LSD FORGE into the current project. Run once. Detects Node, Python, Go, and Rust stacks, finds AI posture files, writes .lsd/, augments posture files, and installs a pre-commit hook that lints staged .logic files.
npx forge initforge new
Interactive wizard that authors a new .logic spec through a structured questionnaire — domain, owner, runtime, boundaries, happy path, edge cases, regression fence, and context note. Auto-assigns an ID, writes the file, and runs lint. Also available as the forge_new MCP tool for AI-driven authoring.
forge new # interactive terminal wizard
forge new --json # wizard output as JSON (file path + lint findings)forge lint [path]
Validate .logic files against the structural rules. Errors block compilation; warnings block only under --strict.
forge lint # lint all .logic files in ./specs/
forge lint specs/LS-2026-001.logic # lint a single file
forge lint --strict # warnings become errors
forge lint --plain --json # CI-friendly outputforge compile <file>
Transform a validated spec into a token-optimised agent payload. Lint runs first — specs with errors do not compile.
forge compile specs/LS-2026-001.logic # payload to stdout
forge compile specs/LS-2026-001.logic --out p.txt
forge compile specs/LS-2026-001.logic --jsonforge status
Registry health: whether .lsd/ is initialised, how many specs exist, and which registered services have no spec.
forge statusforge coverage [--threshold n]
Spec coverage gap report. With --threshold, exits 1 if fewer than n% of registered services have a spec — use it as a CI gate and raise it quarterly.
forge coverage --threshold 80forge validate
Cross-spec collision detection: forbidden-exposure (a file authorized in one spec, forbidden in another), domain-overlap, and shared-authorization across all .logic files.
forge validateforge mcp
Print the exact MCP server config block for your AI client — Claude Desktop, VS Code, or any stdio MCP host.
forge mcpExit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Lint or compile error; coverage below threshold |
| 2 | Usage error — bad command or path not found |
What's new in 1.1.0
Upgrade, pre-commit guard, editor shortcuts.
forge init --upgrade
Upgrade in place
Upgrades an existing .lsd/ installation to the 1.1.0 schema — adds missing onboarding sections, refreshes the skill kit, re-installs the pre-commit hook. Safe on a project already running 1.0.x.
forge touched
Pre-commit domain check
Runs automatically via the git pre-commit hook. Inspects every staged file and flags any path that falls outside all known spec authorization boundaries — catching out-of-scope edits before they reach a commit.
/forge
Editor shortcut — route to any FORGE command
In-editor skill that routes to spec authoring, lint, compile, status, coverage, or validate from one command. The entry point for all FORGE operations without leaving the conversation.
/forge-new
Editor shortcut — author and harden
Inline spec authoring loop: guides the AI through the RSC-AR hardening cycle, then compiles the finished .logic file to an agent payload — all within a single editor session.
Platform facts
Numbers that matter.
7
lint rules
Ambiguous, incomplete, or collision-prone specs are blocked before an agent ever reads them.
3
RSC-AR cycles max
Every spec survives a Proposer → Adversary → Resolver loop — up to three rounds before delivery.
17
banned phrases
The ambiguous-language rule blocks "as appropriate", "as needed", and 15 others that cause agents to improvise.
≥ 50%
unhappy-path ratio
Edge steps must match at least half the happy-path count. Failure cases cannot be an afterthought.
4
stack detectors
forge init auto-detects Node, Python, Go, and Rust — zero manual configuration.
0
production dependencies
The MCP server ships as a zero-dependency stdio process. Nothing to version-conflict.
1
text file per spec
Every .logic spec is a plain text file. No runtime dependency on FORGE — agents read raw payloads.
Install
Three steps. No config.
One command. No config. Works on any Node, Python, Go, or Rust project.
forge init detects your stack, finds posture files, writes .lsd/ with the onboarding trigger, and installs a pre-commit hook that lints staged specs.
The connected AI reads the onboarding trigger, runs the discovery protocol, and maps your project before it touches anything.
The machine runs when the spec is right
Stop prompting. Start specifying.
npm install lsd-forge --save-dev
npx forge init