Service 05

Cycle Doc Trailer Validator

Every commit traces back to an approved plan. Cycle: / Issue: / ProjectItem: trailers are required. Plan state and code state stay in lockstep — by gate, not by goodwill.

The problem

Spec drift is the default. Traceability is forensic.

Most repos accumulate commits with no link to anything. "Fix auth bug" appears in git log with no issue, no PR description anyone wrote, no plan it traces to. Audit week comes; nobody can answer "why did we make this change."

For AI-authored code the problem is sharper. An agent decomposes a PRD into a plan PR — the plan ratifies the approach. The agent then implements across many code PRs. Without a trailer linking each commit to the plan, the plan is a Word doc.

How it works

Trailer schema + lifecycle state machine, enforced in CI.

The validator enforces three trailers on every commit: Cycle: N (the approved plan), Issue: M (the work-tracker entry), and optionally ProjectItem: (the GitHub Project board card). A code PR whose commits don't carry these fails the gate.

It also runs a lifecycle state machine on the cycle doc itself: a plan PR opens the doc as status: draft; once the plan PR merges, the doc must flip to status: in-progress before any code PR can land against it. Once all related code PRs are merged, a docs PR flips it to status: completed. The state machine is enforced in CI — no doc, no merge.

Required trailers: Cycle: N (plan link), Issue: M (work tracker), ProjectItem: (board)
Lifecycle states: draft → in-progress → completed, validated against plan PR + code PRs
Code PR fails if its target Cycle: doc is not status: in-progress
Plan PR fails if its scope checklist is missing exit criteria
Trailers are git-native — no separate DB, no migration risk

git commit-msg + validator yaml

# Commit trailer (required on every commit in a code PR)
feat(auth): rotate session token on suspicious geo

The session-fixation attack window narrows from 15min to 0
when geo deltas exceed 500km between consecutive requests.

Cycle: 87
Issue: 1042
ProjectItem: auth-hardening

# darkfactory.yaml — cycle doc validation
cycle_doc_validation:
  required_trailers: [Cycle, Issue]
  optional_trailers: [ProjectItem]
  lifecycle:
    states: [draft, in-progress, completed]
    transitions:
      draft -> in-progress:    requires: plan-pr-merged
      in-progress -> completed: requires:
        - all-code-prs-merged
        - exit-criteria-complete
  refuse_on:
    - missing_trailer
    - cycle_doc_not_in_progress
    - cycle_doc_404

Pricing relevance

Cycle Doc Validator runs in every tier. The OSS CLI ships the validator binary; the hosted App offers a richer UI on top — visualizing plan ↔ code traceability across the fleet.

Open-source posture

Validator is OSS (Apache-2.0). Trailer schema is open-spec. The fleet visualization in the dashboard stays hosted.

Get Started

Stop shipping code that doesn't trace to a plan.

Cycle Doc Validator gates plan-PR-vs-code-PR routing in the Merge Queue Admission Policy. Together they enforce AI-Native Manifesto §9 + §10.

Request Early Access → See Pricing