Public design docs are human-reviewable contract context. They must make their maturity explicit so agents, reviewers, and signoff gates can distinguish accepted behavior from work in progress.
Every HTML file under docs/design must declare
data-doc-status on either the root body,
main, or another top-level container. Pages should also show
the same status in visible text near the title when the status is
draft or proposal.
<main data-doc-status="draft" data-doc-stage="proposal" data-doc-domain="pcb">| Status | Meaning | Release posture |
|---|---|---|
draft |
Exploratory direction. Implementation may be absent or partial. | Allowed, but release signoff must not treat it as accepted contract evidence. |
proposal |
Ready for focused implementation review, but not yet accepted. | Allowed, but release signoff must review the open decision explicitly. |
accepted |
Aligned with code, tests, contracts, and any required ADR. | May be used as accepted standard or contract evidence. |
superseded |
Retained for history after a newer doc or ADR replaced it. | Must link to the replacement before release. |
dev-std audit fails when HTML design docs are unmarked or
use a status outside the approved vocabulary. It passes but reports
draft and proposal pages so L99 signoff can
decide whether those pages are acceptable for the release being prepared.
Repositories may add stricter local gates. A package with a public API,
serialized contract, or release note that depends on an unfinished design
should fail release signoff until the relevant document is promoted to
accepted or a clear release exception is recorded.
Active plans and attached work logs use Markdown files with TOML front
matter. The minimum plan fields are type, id,
status, created, and at least one
[[exit_criteria]] entry. The minimum log fields are
type, id, plan_id, and
created. Plan documents use type = "plan" and
work logs use type = "plan_log". Plans may declare
depends_on when one plan must finish before another can
proceed.
Markdown filenames with a standalone log token, such as
v1_1_log.md, are treated as log-like by the docs audit. Keep
them as compliant plan_log files only while they support an
active plan. After closeout, delete them or distill useful material into
durable history, research, design, requirement, ADR, release, or source
documentation.
+++
type = "plan"
id = "pcb-a0-alignment"
status = "active"
created = "2026-06-27"
[[exit_criteria]]
id = "signoff"
title = "Focused signoff passes"
status = "pending"
+++
Plan status values are active, pending, and
blocked. Completed plans are closed out into durable artifacts
and removed from active plan roots rather than left with a
complete status.
Multi-step plans may declare [[steps]] metadata with
id, title, status, and optional
depends_on. Structured steps are the canonical current state
for multi-step plans. The dev-std plan and
dev-std log commands can create, read, and update canonical
plan, step, and log files when the active plan catalog is already
compliant.
Exit criteria are the canonical answer to “are we done?” Each
[[exit_criteria]] entry has an id,
title, and status. Valid statuses are
pending, met, and blocked.
The docs-plan audit fails active plans without exit criteria and reports
plans whose criteria are all met while the plan still remains
active.