Quality Gates

Forge scores your artifacts before you build against them. forge analyze reads the whole spec surface — spec, design, tasks, constitution, and the foundation baselines — and returns a reproducible 100-point quality score. It is read-only. It never edits an artifact; it proposes.

Commands

forge analyze [<spec-path>] [--portfolio] [--save] [--json]

analyze scores a single change or spec, or (with --portfolio, or no path given) every scored artifact in one view. Cross-cutting: callable at any time, non-destructive, safe to rerun. The same engine backs the /forge.analyze slash command.

forge health is a separate, portfolio-wide risk dashboard — not a quality score. It classifies every active change's current risk from verify/task/ review-gate state rather than scoring spec text; see the CLI reference.

Run analyze after tasks, before implement. It sits between drafting the contract and building against it — the last cheap moment to catch a gap.

What it inspects

analyze reads across artifacts, not one file in isolation — most defects live in the seams between them.

Artifact	What it extracts
spec.md	Requirements, scenarios, acceptance criteria, edge cases
plan.md (plus the optional data-model.md / contracts/ companions, when present)	Architecture choices, data model and contract definitions, phases, constraints
tasks.md	Task IDs, phases, parallel markers, file paths
constitution.md	Principles and MUST / SHOULD normative statements
Foundation baselines	Security, infra, brand, and design conventions as constraints

It then runs seven detection passes over that combined surface:

• Duplication — near-duplicate requirements across artifacts.
• Ambiguity — vague terms without measurable criteria; unresolved TODO / ??? / <placeholder> markers.
• Underspecification — requirements with verbs but no measurable outcome; stories missing acceptance criteria; tasks referencing files no artifact defines.
• Constitution alignment — requirements that conflict with a MUST principle, or mandated sections that are missing.
• Coverage gaps — requirements with zero tasks, tasks with no mapped requirement, non-functional requirements absent from the task list.
• Design and branding consistency — hardcoded values instead of tokens, undefined tokens, missing accessibility or error states. Runs only when a design or brand baseline exists.
• Inconsistency — terminology drift, entities in the plan but not the spec, contradictory task ordering, conflicting technology choices, features that violate the security or infra baseline.

Severity of findings

Every finding carries a severity. Severity decides what blocks and what merely advises.

Severity	What triggers it
CRITICAL	Constitution violation, missing core artifact, blocking requirement with zero coverage
HIGH	Duplicate or conflicting requirement, ambiguous security or performance attribute, untestable criterion
MEDIUM	Terminology drift, missing non-functional coverage, underspecified edge case
LOW	Wording and style improvements, minor redundancy

Constitution conflicts cap the score

A requirement that fights a MUST principle is always CRITICAL — the constitution is non-negotiable within analyze's scope. A stale constitution quietly drags down every assessment, so keep it current. See The Workflow.

The 100-point score

The score is a fixed rubric across six weighted dimensions. Same inputs, same score — every time.

Dimension	Max	What it measures
Completeness	20	Purpose/Requirements skeleton present, sections filled, no placeholders
Consistency	20	Constitution-aligned, no conflicting artifacts, consistent terminology
Coverage	20	Every requirement carries acceptance scenarios — no scenario-less spec
Clarity	15	No vague adjectives without metrics, no ambiguous language
Testability	15	Every requirement has a Given/When/Then scenario and measurable criteria
Freshness	10	Spec is no older than the code paths and delta specs it references
Total	100	—

Ratings: Excellent (90+), Good (80+), Fair (70+), Poor (below 70).

Read-only — it proposes, never applies

analyze prints a findings table, a coverage summary, and the score, then offers to draft concrete remediation edits for the top findings. It never touches spec.md, plan.md, tasks.md, or any baseline on its own — you choose which suggestions to accept. Findings are capped at the highest-signal 50.

How it feeds implement and archive

analyze is not decoration. Its output routes the change through the rest of the spine.

• Before implement — CRITICAL findings should be resolved first. A score below 70 is a signal to run /forge.clarify and fill the gaps rather than build on sand.
• Toward archive — a passing score is one of the signals that a change is genuinely ready to promote. Archive stays gated on honest task status regardless, but a clean analyze removes the spec-level excuses.
• --save persists the score so health can aggregate it. --portfolio and forge health roll every scored artifact into one status view, so quality is visible across the project, not just per-change.

Maturity and refinement

The score is a snapshot. Maturity tracks an artifact's trajectory as it earns trust over its life.

Level	Meaning
draft	Initial creation, straight out of specify
refined	Gaps filled, questions clarified, stories strengthened
validated	Quality score clears 80
implemented	Code generated and tested
evolved	Updated from implementation learnings and drift review

Refinement — the /forge.refine engine — closes the loop from the other direction. Where analyze checks the spec before you build, refinement learns from what you actually built and proposes improvements back into the spec:

• Gap detection — the spec says "handle errors" but the implementation has fifteen error paths. Refine proposes expanding the section with the real paths.
• Staleness detection — the linked code changed significantly since the spec was last touched. Refine flags what drifted.
• Consistency propagation — the constitution gained a principle. Refine scans every existing spec for the requirements that now violate it.

Suggestions are grouped by artifact and reviewed one at a time — accept, reject, or modify. Nothing applies automatically. /forge.levelup captures recurring conventions and feeds them back as project-wide improvements, and the constitution itself can learn: after several implementation cycles it can surface a repeated decision and propose codifying it as a new principle.

Analyze forward, refine backward

Reach for analyze to gate a change on its way into implement. Reach for refine to fold hard-won implementation reality back into a spec that has fallen behind the code. Together they keep the enforced ledger honest in both directions.

Next steps

• The Workflow — where analyze and refine sit on the SDD spine.
• Command Reference — every command, as CLI and slash command.
• Adversarial Review — the delivery-side gate that bounds what ships.
• Spec-Viewer Dashboard — where the 100-point score is rendered.