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.cli validates optional command-line governance
manifests that connect command inventory, canonical command paths, aliases,
deterministic parser/help parity, design-doc coverage, and config/output
contract links. 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.18"
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.18"
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 greenfield typescript-web-app and
python-ts-app profiles run TypeScript guardrail checks under
the language scope. The audit validates owned TypeScript
source under src/, tsconfig.json or a configured
typecheck config, mandatory strict compiler options, package scripts,
committed package-manager lockfile, and CSS token hygiene when owned CSS is
present.
The TypeScript audit resolves local-file extends chains only.
Package-based extends, skipLibCheck: true,
allowJs: true, and owned JavaScript source in TypeScript
profiles require explicit [typescript.exceptions] or
[typescript.migration] metadata. The audit does not parse
TypeScript source in Python; explicit public boundary types are enforced by
the required project lint and typecheck scripts.
The rust-app and rust-firmware profiles run Rust
guardrail checks under the language scope. The audit validates
Rust-owned source under src/ or a configured
[rust].source_root such as src/rs, Cargo package
or workspace metadata, Cargo.lock,
rust-toolchain.toml, unsafe lint posture, and Rack command
declarations for Cargo fmt, check, Clippy, tests, and rustdoc warnings.
The Rust audit parses Cargo.toml,
rust-toolchain.toml, and embedded
.cargo/config.toml with TOML parsing. It does not parse Rust
source in Python. Source semantics, unsafe-block enforcement, rustdoc
warnings, and lint failures belong to rustc, Clippy, rustfmt, rustdoc,
Cargo tests, and project signoff. cargo doc warning failures
are declared through RUSTDOCFLAGS="-D warnings".
rust-firmware adds static checks for
[rust.firmware] target metadata,
.cargo/config.toml, memory/linker artifacts such as
memory.x or a documented link.x provider,
runner/flashing metadata such as Embed.toml,
probe-rs, or cargo-embed, plus local docs for
no_std, panic, allocator, hardware setup, and host-test split.
Tokio and Embassy are documented scenario defaults, not mandatory audit
dependencies.
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]. For each configured root, dev-std
delegates Rack manifest/layout checks to Rack's native audit surface from
wn-rack>=2026.7.16 and maps Rack failures into normal
dev-std audit output.
[tests]
roots = ["tests"]
signoff_strata = ["L99_signoff"]
Rack owns rack.toml, STRATUM.toml, discovered
test files, declared subtest files, duplicate manifest entries, and signoff
stratum existence. Dev-std owns explicit root configuration, upgrade
guidance when Rack audit support is missing, and the requirement that each
configured signoff stratum declare the signoff concern.
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.cli validates
docs/contracts/command_manifest.a0.json when present, while
allowing explicit legacy command_manifest.v0.json paths for
repositories that have not migrated to the richer contract. The scope checks
command identity, command status, design references, aggregate
section[data-command] coverage, per-command design docs,
config/output schema links, and deterministic parser/help inventory parity
when a provider is configured. It does not replace
docs.surfaces; command entries should link to governed
surfaces or use the same typed evidence semantics.
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.
dev-std audit . --scope docs.release --mode release adds
produced-payload inspection for configured
[[channels.promoted_artifacts]] entries in
release.toml. Default mode shape-validates promoted-artifact
declarations without reading local build output. Release mode checks that
required payloads exist, that artifact-like files under declared promoted
roots are cataloged, and that declared checksum, package version, and
source-commit metadata match the local file and source tree. Uncataloged
payload detection uses the catalog-wide promoted-artifact pattern set so
channels can share staging roots.
--mode release only changes docs.release in the
first implementation. Non-release scopes keep default behavior. Workspace
audits aggregate release-mode checks per registered member; each member
resolves its own release catalog and promoted artifact paths relative to
that member root.
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 public CLIs should add
docs.cli once a command manifest and design-doc coverage are
available. 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.cli \
--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.18 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.