dev-std audit is the canonical read-only signoff command for
Wavenumber repository checks. It groups checks by scope so projects can run
the full release-facing audit or focus on one policy area while migrating.
The default audit scope is all. Narrow scopes such as
docs.plans are intended for migration and local ratchets.
dev-std check is a compatibility alias for existing CI jobs;
new signoff wiring should call dev-std audit.
dev-std plan and dev-std log are workflow
helpers over the same catalog. Read and mutation commands operate only on
compliant plan catalogs and fail when the same metadata problems reported
by docs.plans are present. The initial mutation surface is
non-destructive: plan create, plan status,
plan step add, plan step status,
log show, log create, adr create,
and requirement create. Delete, retire, and migration commands
are future slices.
Durable governance docs use adjacent scopes. docs.adrs
validates ADR metadata and standing-decision hygiene, including failure
when no ADR inventory exists. docs.build validates the
canonical build document and its minimal setup, invocation, output, and
validation topics. docs.domains validates the
domain registry, domain HTML coverage, and file-to-domain ownership under
configured owned roots, including failure when no registry exists.
docs.requirements validates requirement metadata and
verification obligations, including failure when no requirement inventory
exists. docs.surfaces validates optional
governed-surface manifests that connect public APIs, workflows, transforms,
schemas, and other owned surfaces to implementation refs, verification refs,
fixture/data refs, and typed exceptions. docs.artifacts,
docs.vendors, and docs.release validate
artifact, vendored-code, and release-channel catalogs.
docs.traceability
validates typed local and external refs across issues, plans, ADRs,
requirements, design docs, source, schemas, and tests.
docs.links validates local documentation links in Markdown and
HTML. These scopes are opt-in ratchets during migration and can later be
included in package signoff.
The current audit model treats the path passed to dev-std audit
as one package root. Monorepo packages should run audit from package-level
signoff until workspace-level package registration is added. Repo-root
workspace audits are a future layer and should not be inferred from the
package-local contract.
Plan and log commands discover the package root by walking upward from the
current directory or --root value until they find
dev-std.toml, legacy wn-dev-std.toml, or a
pyproject.toml with [tool.wn_dev_std]. A
.git directory is a fallback boundary when no Wavenumber config
marker is present.
The docs.plans scope audits active plan and work-log artifacts.
The default approved root is docs/plans. Projects may override
the approved roots with [documentation.plans] in
dev-std.toml, legacy wn-dev-std.toml, or
[tool.wn_dev_std.documentation.plans] in
pyproject.toml.
[documentation.plans]
roots = ["docs/pcb/plans", "docs/sch/plans"]
Approved roots are allowed locations, not required folders. A repository or
package with no active plans does not need to keep an empty
docs/plans folder or a placeholder file.
Active plans and attached work logs are Markdown documents with TOML front
matter. Plan metadata uses type = "plan"; log metadata uses
type = "plan_log". Logs must identify their owning plan with
plan_id and the owning plan step with step_id.
Every active/pending/blocked plan must define at least one structured
[[steps]] entry and at least one structured
[[exit_criteria]] entry.
+++
type = "plan_log"
id = "pcb-a0-2026-06-27-001"
plan_id = "pcb-a0"
step_id = "audit-existing-plans"
created = "2026-06-27T12:00:00-04:00"
+++
Plans must declare structured [[steps]] metadata. Step
metadata is the canonical current execution state for the plan; prose
checklists are allowed only as explanatory text. Each step has an
id, title, status, and optional
depends_on references to other step ids in the same plan.
[[steps]]
id = "audit-existing-plans"
title = "Audit existing plans"
status = "done"
[[steps]]
id = "release"
title = "Release package"
status = "pending"
depends_on = ["audit-existing-plans"]
Step status values are pending, active,
blocked, and done. Step ids must be unique within
a plan, step dependencies must reference existing steps, and a plan may not
have more than one active step. A pending plan may not have an active step.
If every structured step is done, the plan should be closed
out instead of remaining active.
Work logs must carry a step_id that references an existing
step in the owning plan. The docs.plans audit fails missing
or unknown step links so log history stays attached to plan execution
state.
log create <plan-id> <step-id> accepts
--body for short one-line notes and --body-file
for longer Markdown. Agents should prefer --body-file when a
log entry may run into shell command-line length, newline, or quoting
limits.
Exit criteria are machine-readable closeout conditions for a plan. They are
distinct from steps: steps describe execution state, while exit criteria
describe the externally observable conditions that must be true before the
plan can be retired. Each exit criterion has an id,
title, and status.
[[exit_criteria]]
id = "signoff"
title = "Focused signoff passes"
status = "pending"
Valid exit-criterion statuses are pending, met,
and blocked. The docs.plans audit fails a plan
with missing, malformed, duplicate, or invalid exit criteria. If every exit
criterion is met while the plan status remains
active, the audit fails so the plan is closed out instead of
lingering after its exit conditions are satisfied.
A rogue plan-like or log-like document outside approved plan roots fails the
docs.plans audit. This includes common active-work names such
as plan, roadmap, worklog, logbook, Markdown files with a standalone
log filename token such as v1_1_log.md,
log/, logs/, and worklogs/.
Inside approved roots, plan-like and log-like files must use the TOML
front matter contract.
Valid active plan statuses are active, pending,
and blocked. complete is not a valid resting
state in active plan roots. Completed work should be closed out into durable
artifacts such as code, tests, design docs, requirements, ADRs, or release
notes, then the temporary plan and work logs should be removed. Useful
historical or reverse-engineering material may be kept, but it should be
renamed and classified as history, research, design, or another durable
document type rather than left as an active-work log.
ADRs and requirements use the same TOML-front-matter pattern as plans, but
they are durable artifacts instead of temporary execution state.
docs.adrs expects type = "adr", a domain-scoped
id such as core-adr-0001, a matching filename, and a valid ADR
status. Accepted ADRs fail when they still contain active-work language
such as open-question sections or release-exit cleanup text.
docs.requirements expects type = "requirement",
a domain-scoped id such as transforms-req-0001, a matching
filename, and a valid requirement status. Active and implemented
requirements must declare [[verification_refs]], or explicitly
set verification_status = "unverified" with an issue ref.
docs.surfaces validates
docs/governance/governed_surfaces.toml when present. Active
and implemented surfaces must have structured verification refs or a typed
exception. Local implementation, test, and fixture refs must resolve;
external refs must name the owning repository. Optional parity
relationships must reference known surfaces, declare parity and fixture
coverage modes, and track accepted divergence with an exception or issue.
Surface domains must exist in
docs/governance/domain_registry.toml when that registry is
present.
Runtime Rack evidence is intentionally separate from the committed
governance manifest. dev-std checks the declared contract;
wn-rack may later export observed test, fixture, artifact, and
result evidence that stricter signoff modes compare against the declared
refs.
If a governed-surface manifest includes [[fixtures]] or
[fixture_governance], docs.surfaces also audits
fixture/data hygiene. Registered active fixtures must resolve and be used,
surface fixture refs must be registered, and discovered files under
configured fixture roots must be cataloged or ignored. Fixture refs may be
physical files or logical evidence surfaces such as case ids, synthetic
vectors, oracle artifacts, fixture sets, and Rack evidence.
docs.traceability validates simple string ref arrays and typed
ref tables. Local refs must resolve when they point at repo files. External
source and test refs must name the owning repository so cross-repo and
cross-language verification is explicit.
docs.links scans Markdown and HTML documents under
docs/ for local links. Missing local targets fail the scope;
external URLs, anchors, mailto:, and similar non-file links are
ignored. HTML links to raw ADR or requirement Markdown fail so design pages
point reviewers at generated governance pages instead of source files. The
same scope validates data-dev-std-gov-ref hooks against the
configured generated governance HTML output root and fails unknown ids,
missing generated hrefs, or stale relative hrefs.
docs.build requires a canonical build document at
docs/build.html or docs/build.md.
HTML build docs must include data-doc="build" and
data-doc-status="accepted". Markdown build docs must use TOML
front matter with type = "build_doc", id,
title, and status = "accepted".
The document must cover required tools or setup, build commands or invocation, outputs or artifacts, and validation or signoff. The check is intentionally content-light: it ensures a durable build entry point exists without trying to parse every project-specific build system.
docs.artifacts validates
docs/governance/artifacts.toml when tracked artifact-like files
are present. It covers committed runtime artifacts, app/plugin bundles,
generated source, public reference assets, fixture data, oracle outputs,
vendored runtime artifacts, and release evidence. Default audit is
tracked-file-first and does not fail ignored local build output.
docs.vendors validates
docs/governance/vendors.toml for committed vendored source
under roots such as vendor/ and third_party/.
docs.release validates
docs/governance/release.toml when a package config declares a
non-none distribution such as pypi. Each release
channel must link both a process_doc and a
build_doc so setup, tool invocation, packaging, and publishing
responsibilities are explicitly documented.
Existing repositories should add governance scopes incrementally. A package
can start with dev-std audit . --scope docs.adrs or
dev-std audit . --scope docs.requirements in its local signoff
and then add docs.traceability and docs.links as
the repo is converted. Repos with declared API, transform, serialization,
porting, or workflow surfaces should add docs.surfaces once
the first governed-surface manifest exists. Repos with committed artifacts,
vendored source, or configured release channels should add
docs.artifacts, docs.vendors, and
docs.release as applicable. The checks are designed to fail
loudly with concrete file paths so migration work can be planned rather
than silently ignored.
A minimal bootstrap for an existing package is:
dev-std.toml
docs/governance/domain_registry.toml
docs/governance/governed_surfaces.toml
docs/<domain>/adr/*.md
docs/<domain>/requirements/*.md
docs/domains/<domain>.html
Packages may start with only dev-std.toml and the scopes they
are ready to ratchet. The generic signoff command should stay repo-neutral
so projects do not need custom Python just to get governance failure
signals:
dev-std audit . \
--scope docs.plans \
--scope docs.adrs \
--scope docs.requirements \
--scope docs.domains \
--scope docs.build \
--scope docs.surfaces \
--scope docs.artifacts \
--scope docs.vendors \
--scope docs.release \
--scope docs.traceability \
--scope docs.links
Once the source documents are compliant, projects can generate browseable
governance docs with
dev-std governance html --output docs/generated/governance.
The generated output is derivative and should be rebuilt from the committed
Markdown sources when needed.