Quality Standards

Configure the readiness thresholds and per-ticket gates that guard quality across your specifications.

SpecForge enforces quality at two points: the Planning Review — scored by the validator against per-layer readiness thresholds before implementation starts — and the per-ticket assay inside complete_work_session, which checks each ticket’s delivered work as it lands. This page documents the configuration that tunes both.

Quality standards are project-level settings. They are not specforge configure keys — the configure command accepts only the five flat keys documented in the CLI reference (mcpOutputFormat, projectId, specificationId, autoSetContext, defaultProjectId). The thresholds and gate switches below live in the project’s .specforge/config.json (validator + implementation-lifecycle config), seeded by specforge init and editable through the dashboard.

Planning Readiness Thresholds

The Planning Review scores a specification across its scoring dimensions and produces a weighted score from 0 to 100 at each layer of the plan. A layer advances only when its score meets or exceeds the configured threshold. Thresholds are set per layer, not as a single number:


{
  "thresholds": {
    "global": 80,
    "specification": 80,
    "epic": 70,
    "ticket": 70
  }
}

Options

Layer	Type	Default	Description
`global`	number (0-100)	`80`	Overall weighted readiness across the whole plan. When this is met, the specification advances to `ready`.
`specification`	number (0-100)	`80`	Minimum readiness for the specification-level fields (goals, requirements, scope, guardrails).
`epic`	number (0-100)	`70`	Per-epic readiness floor — each epic must clear this on its own.
`ticket`	number (0-100)	`70`	Per-ticket readiness floor — each ticket must clear this on its own.

✅ Start with defaults. They represent a balance between rigor and speed. Raise thresholds as your team gains confidence with the workflow.

Structural Ratios

Beyond the scored dimensions, the validator enforces structural topology ratios on the dependency graph. These are not feature-to-test ratios — they bound how the dependency graph is shaped:

Option	Type	Default	Description
`topology.maxRootRatio`	number (0-1)	`0.25`	Maximum fraction of tickets that have no dependencies (roots). Too many roots means the plan under-specifies ordering.
`topology.maxLeafRatio`	number (0-1)	`0.25`	Maximum fraction of tickets that nothing depends on (leaves). Too many leaves means the plan is a flat list, not a graph.

Blueprint coverage and dependency validity are checked during cross-validation (every ticket-coverage blueprint must be linked by at least 2 tickets; circular, broken, and orphan references are rejected) — they are structural checks, not user-settable thresholds.

🔬 For engineers: These are the tuning parameters of the planning control loop described in Engineering Foundations. The per-layer thresholds set the acceptance zone at each level of the plan. Raising a threshold tightens the tolerance — the system requires less deviation from the ideal spec before passing.

Per-Ticket Assay Gates

When an agent calls complete_work_session, the implementation lifecycle runs four advance gates against the ticket’s delivered work. Each gate can be individually toggled. A ticket does not advance to done until every enabled gate passes.


{
  "gates": {
    "acceptance": true,
    "step": true,
    "file": true,
    "test": true
  },
  "maxRetries": 7,
  "skipStepsCheck": false,
  "validateFiles": "local"
}

Gate Details

Gate	What it checks
`acceptance`	Were all acceptance criteria on the ticket satisfied?
`step`	Were all implementation steps on the ticket completed?
`file`	Were all expected file changes (creations, modifications, deletions) recorded?
`test`	Were test results submitted for the ticket when it requires them?

⚠️ Disabling a gate lets the lifecycle advance past that dimension without its check. If you disable acceptance, the assay won’t verify whether the ticket actually met its stated criteria. Disable deliberately, not casually.

Lifecycle Options

Option	Type	Default	Description
`maxRetries`	number	`7`	Retry budget: after this many failed advance attempts on a work session, the lifecycle locks the session into a discovery-only state and requires human intervention. This prevents infinite loops on fundamentally stuck tickets.
`skipStepsCheck`	boolean	`false`	When `true`, the step-completion gate is skipped — the agent may advance without every implementation step marked done.
`validateFiles`	`"agent"` \| `"local"`	`"local"`	Who validates the recorded file changes. `"agent"` trusts the agent’s self-reported set; `"local"` has the MCP-local verify the changes against the worktree.

Progress Weights

The per-ticket completion (progress) score is a weighted aggregate of the ticket’s dimensions. The four-key weight struct is:


{
  "weights": {
    "steps": 0.55,
    "ac": 0.3,
    "tests": 0.15,
    "files": 0
  }
}

The step and file dimensions are unified — a step’s progress requires its linked files recorded as matched — so files carries 0 by default while steps absorbs the combined weight. Coherence is a separate fixed formula and carries no weights.

Configuration Profiles

Different situations call for different settings. Here are common configurations.

Prototyping

Speed matters more than ceremony. Lower thresholds, skip the step check.


{
  "thresholds": { "global": 60, "specification": 60, "epic": 55, "ticket": 55 },
  "gates": { "acceptance": true, "step": false, "file": true, "test": false },
  "skipStepsCheck": true
}

Why keep the thresholds meaningful even for prototypes? Because a bad decomposition wastes more time than a quick review costs. Lowering the thresholds lets you pass with rougher plans while still catching circular dependencies and empty epics.

Standard Development

The defaults. Balanced between rigor and velocity. Good for teams getting started with SpecForge.


{
  "thresholds": { "global": 80, "specification": 80, "epic": 70, "ticket": 70 },
  "gates": { "acceptance": true, "step": true, "file": true, "test": true },
  "maxRetries": 7,
  "validateFiles": "local"
}

Production-Grade

Maximum rigor. Higher thresholds, every gate on, local file validation. Use for specifications that will ship to users.


{
  "thresholds": { "global": 90, "specification": 90, "epic": 85, "ticket": 85 },
  "gates": { "acceptance": true, "step": true, "file": true, "test": true },
  "maxRetries": 7,
  "validateFiles": "local"
}

The key difference: higher thresholds catch marginal plans that would squeak through at 80. Keeping every gate on and validateFiles: "local" means each ticket’s delivered work is verified against the worktree, not taken on the agent’s word.

Configuring quality standards

Quality standards are project-level validator and implementation-lifecycle settings, not specforge configure keys — the configure command accepts only the five flat keys documented in the CLI reference (mcpOutputFormat, projectId, specificationId, autoSetContext, defaultProjectId). The per-layer readiness thresholds and gate settings are managed through the dashboard or by editing .specforge/config.json.

📖 Quality standards apply at the project level. All specifications within a project inherit the same review configuration. For the complete configuration schema, see Configuration Schema.