# 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

```sh
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](/reference/cli#health).

```mermaid
flowchart LR
  S[specify] --> P[plan] --> T[tasks]
  T --> A[forge analyze]
  A -->|score clears| I[implement]
  A -->|findings| F[fix specs]
  F --> A
```

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 |

::: warning 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](/guide/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).

::: info 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.

```mermaid
flowchart LR
  D[draft] --> R[refined] --> V[validated] --> I[implemented] --> E[evolved]
```

| 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.

::: tip 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](/guide/workflow) — where analyze and refine sit on the SDD spine.
- [Command Reference](/guide/commands) — every command, as CLI and slash command.
- [Adversarial Review](/features/review) — the delivery-side gate that bounds what ships.
- [Spec-Viewer Dashboard](/features/dashboard) — where the 100-point score is rendered.