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, and log create. Delete, retire, and
migration commands are future slices.
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
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
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.
+++
type = "plan_log"
id = "pcb-a0-2026-06-27-001"
plan_id = "pcb-a0"
created = "2026-06-27T12:00:00-04:00"
+++
Multi-step plans may 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.
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.