forgeplan_guard

Check whether a methodology phase transition is allowed by the session state machine (PRD-019). The guard enforces the core rule: you cannot jump phases without completing prerequisites. Example: you cannot transition from shaping to coding unless an active artifact exists and validation has passed. Call this before any phase-changing action (forgeplan_activate, commits, PR creation).

Category: Quality

When an agent calls it

Before code — “can I go from shaping to coding?” — confirms a validated artifact exists.
Before commit — agents and hooks call guard to block commits without an artifact at Standard+ depth.
Before PR — ensures evidence and R_eff gates are met.
Recovery — after an error, guard tells you which prerequisite is missing and how to fix it.

This is the mechanism that prevents “code first, document later” drift. When enforcement is enabled, violations block the operation with a clear reason.

Input parameters

Name	Type	Required	Description
`target_phase`	`string`	yes	Target phase to check: `idle`, `routing`, `shaping`, `coding`, `evidence`, or `pr`.

Schema source: crates/forgeplan-mcp/src/server.rs::GuardParams

Returns

{
  "allowed": true,
  "from": "shaping",
  "to": "coding",
  "reason": "PRD-042 validated (PASS), ADI reasoning recorded"
}

Blocked case:

{
  "allowed": false,
  "from": "shaping",
  "to": "coding",
  "reason": "No validated artifact — run forgeplan_validate first",
  "fix": "forgeplan validate PRD-042"
}

Example invocation

{ "target_phase": "coding" }

Typical sequence

forgeplan_session — know where you are.
forgeplan_guard with target_phase — check the next hop.
If allowed: false, follow fix instruction (validate, link evidence, etc.).
Retry guard → proceed.

CLI equivalent

forgeplan guard --target coding