dev-std audit is the canonical read-only signoff command for
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.test_strategy validates the canonical
package or workspace test strategy document and its high-level coverage of
Rack, signoff, lanes, parity, fixtures, assets, oracles, and evidence
surfaces. 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.
A dev-std config marker defines a policy boundary. Package configs apply to one package or application root. Workspace configs aggregate explicitly registered member policy boundaries and do not imply that every build target, runnable, board app, fixture, sample, or demo folder is a separate member.
standard_version = "2026.7.15"
kind = "workspace"
[workspace]
members = ["bom_cruncher", "lib_cruncher", "panel-monkey"]First-slice workspace audits run config-version governance at the workspace root and then run each registered member's configured governance. They do not run package/profile checks at the workspace root unless a future workspace-local opt-in is added.
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 dev-std config
marker is present.
Configured adopters must declare standard_version. Audit fails
when the configured version is missing or does not match the installed
wn-dev-std standard version. This check always runs when a
config marker is present; it is not filtered by --scope or
enabled_scopes. Repositories with no dev-std config continue to
use default audit behavior and are not part of the first migration ratchet.
standard_version = "2026.7.15"
kind = "package"
profile = "zephyr-firmware"
enabled_scopes = ["docs.plans"]
enabled_scopes records partial adoption. When no
--scope is passed, audit runs the configured scopes. Explicit
command-line scopes override the config default. Passing audit with a
targeted scope list is not full profile conformance, and audit output must
report the configured scopes.
The tests scope validates Rack test-suite structure for
projects that opt into strict test governance. The dev-std config registers
test roots with [tests] or
[tool.wn_dev_std.tests]. Each root must contain
rack.toml; each Rack stratum listed in
[strata].order must have a matching directory and
STRATUM.toml; every discovered test_*.py file
must be declared in [[subtests]]; every declared subtest file
must exist; and the configured signoff stratum must exist with at least one
signoff subtest.
[tests]
roots = ["tests"]
signoff_strata = ["L99_signoff"]In the first dev-std slice, Rack manifest validation is implemented locally because Rack does not yet expose a failing audit command. Future dev-std versions should delegate to Rack once a native Rack audit/check command is available.
The docs.test_strategy scope requires a canonical
docs/test-strategy.html file with
data-doc="test-strategy" and
data-doc-status="accepted". Rack manifests describe executable
strata and subtests; the test strategy document describes the human-review
architecture of the suite. It should explain the package or workspace test
scope, Rack and signoff gates, execution lanes, runtime parity
expectations, tested public surfaces, fixture/data assets, oracle tools,
coverage evidence, known missing coverage, and orphan/missing-asset
controls.
Simple packages may state that parity lanes, custom oracle tooling, or fixture catalogs are not applicable. Complex packages should use the same document to orient reviewers before they inspect Rack manifests, generated surface databases, custom test tools, and release signoff output.
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.
Every active/pending/blocked plan must also include the step ids
design-doc-intent-audit,
test-runtime-impact-audit, and
external-review.
The design-doc audit step is the required closeout hook for verifying
design docs, ADRs, and requirements against the user's intent, the
implemented behavior, public contracts, and tests. The test-runtime impact
step is the required closeout hook for listing new or changed tests from
git diff and Rack manifests, reviewing docs/test-strategy.html,
recording observed runtime impact, and documenting reasonable optimization
or splitting decisions for long-running tests. The external-review step
records independent review after both closeout audits.
The runtime-impact hook is a current-standard migration requirement.
Existing active plan catalogs must add the
test-runtime-impact-audit step and exit criterion before
docs.plans or full audit passes with this tool version. Repos
that cannot migrate immediately should keep CI pinned to the previous
reviewed wn-dev-std release or defer the
docs.plans scope until active plans are updated.
+++
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.
Logs for test-runtime-impact-audit should list the new or
changed tests, their Rack stratum or file location, measured or observed
runtime impact when available, any order-of-magnitude optimization pass,
and whether minute-scale tests should be split into a slower lane. This is
the executor evidence that the external reviewer should inspect before
plan closeout.
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"
Every active/pending/blocked plan must include exit criteria with ids
design-doc-intent-audit,
test-runtime-impact-audit, and
external-review.
These ids are intentionally the same as the required step ids: the step is
the work item, and the exit criterion is the observable condition that the
work satisfied. The design-doc-intent-audit criterion must not be marked
met until design docs, ADRs, and requirements have been checked against the
completed implementation. The test-runtime-impact-audit criterion must not
be marked met until New tests are listed and runtime impact is reviewed:
new tests have been listed, the test strategy document has been reviewed,
and unreasonable runtime bloat has either been optimized or explicitly
routed to an appropriate slower lane.
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.
If the audit sees attempted closeout statuses such as done,
closed, complete, or finished, it
fails with closeout-process guidance instead of treating them as valid
states.
Closeout is a process, not a status value. The expected sequence is:
complete or intentionally block the plan work, run the required
design-doc/ADR/requirement alignment audit, run the required test runtime
impact audit, update durable artifacts, complete external review, remove
the temporary plan and logs from the active plan root, and rerun
dev-std audit . --scope docs.plans to prove no active-work
residue remains.
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 signoff checklist must first identify whether the repository uses Rack.
Rack-based repositories should declare signoff strata, normally including
L99_signoff, and that stratum should run the release-facing
gates for the project profile. Non-Rack repositories still need an explicit
package signoff command with equivalent measurable gates. In either model,
the checklist must name the local command, the governance scopes it runs,
and the criteria that make signoff fail.
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.test_strategy \
--scope docs.surfaces \
--scope docs.artifacts \
--scope docs.vendors \
--scope docs.release \
--scope docs.traceability \
--scope docs.links \
--scope tests
CI should run governance before expensive functional or platform matrices.
Downstream CI should pin the released PyPI tool version that matches the
repository's standard_version, for example
uvx --from wn-dev-std==2026.7.15 dev-std audit .. Optional
upstream freshness checks may warn when a newer PyPI release exists, but
normal audit must remain deterministic and offline unless that check is
requested.
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.