nwdes command reference

Common write options

Run every nwdes command from the top level of the checkout. Roots default to cwd and the repository root; lane verbs resolve the main worktree. These options select the destination for feature, slice, work, rework, CLI role-recording verbs, document and commit.

IDs use lowercase letters, digits, and hyphens, starting with a letter or digit. nwdes assigns record IDs such as P1, S1, and E1. Single-line values cannot contain line boundaries or surrounding whitespace. nwdes writes the handoff; roles supply typed values, not JSON.

The default feature handoff is docs/feature/ID/handoff.json. The default briefs are brief.md, architecture.md, and acceptance.md beside it, with HTML versions. Configuration selects their directory, not individual filenames. Read the paths printed by the command.

Role recording

nwdes prompt prints the complete role bundle ending with its generated verb reference. Every recording call uses the kind's nwdes CLI verbs and common write options. All recording roles use this one channel; roles never write JSON.

The first add, set or remove creates an empty scoped draft. Use open --from-current to seed an authority replacement from current rows. nwdes assigns new IDs. close requires --outcome and --diagnostic (or --diagnostic-file on the CLI); with no draft it validates empty values. Expectations revisions use close --revise.

CLI example for root-recorded product facts:

nwdes product promise add --feature search --kind Outcome --text 'The search result is returned'
nwdes product slice add --feature search --observation Find --promise P1
nwdes product close --feature search --outcome accepted --diagnostic 'Public facts recorded.'

A successful close publishes and removes the draft. A refusal preserves the draft unchanged so the owning role can correct its values. abort removes the draft; abort with no draft refuses. Every recording verb takes a per-draft lock and refuses without waiting when held. The root does not submit role replies.

Inside a Git worktree, each role close writes a private receipt under the Git directory. Authority closes and nwdes commit use the same nonblocking OS lock; nwdes never refuses a close because another role's close is uncommitted. Outside Git, authority closes preserve their existing outputs and create no lock or receipt; commit refuses InputUnreadable naming Git. See the commit reference for ownership, message fields and every refusal.

Crafters record with the common write options and their assigned --slice; reviewers name --subject oracle, slice or candidate, with --slice required for oracle and slice and omitted for candidate. nwdes writes runs/craft.S<n>.json, runs/review.oracle.S<n>.json, runs/review.slice.S<n>.json or runs/review.candidate.json next to the handoff, without changing it. New run records end with one newline; earlier records without it remain readable. The root keeps no reply copy.

Measure

nwdes measure --host-sessions ROOT_SESSION_FILE [--candidate COMMIT] [--rework FILE] [--objective-minutes N] [--repo-root ROOT] [--project-root ROOT] [--global-config FILE] [--feature ID | --epic ID]
nwdes measure --requests FILE [--objective-minutes N]

Choose exactly one source; each flag may appear once. --requests accepts a nonempty JSON array with role, nullable task and slice, UTC start and end, and boolean continuation and rework. Its report is explicitly supplied, not host-recorded. The objective is a positive integer printed without a success verdict.

Host mode uses OMP version-3 native request and tool-result clocks. Feature elapsed starts at the earliest linked architect request; a no-architect bugfix starts at the root's first user request. The endpoint is the latest successful examination close, bound by native value-verb replay to a committed postimage or a qualifying current handoff, with exactly the nonempty fixed expectations and every verdict met. The candidate must be a full lowercase commit ID committed before the examination prompt; equality of those seconds is ambiguous. Record-only commits may follow the candidate on the committed path. Current-handoff fallback requires HEAD exactly at the candidate and no changed or untracked path outside the handoff directory.

Roots use the role-verb destination configuration; omitted feature/epic scope must be unambiguous in the native delivery commands. Each role close is reported separately. Recorded command exits are claims, printed apart from native command success/failure. A numeric native exit is reported only from an explicit integer in the harness-owned tool result's message.details.exitCode; program output, footer text and recorded exits never supply that number. Missing or malformed exit metadata supplies no numeric exit, not a default zero. Lifecycle qualification is separate from elapsed; integration tail is separate from both role effort and design/intake-to-examination elapsed. Lane-free delivery has no fabricated integration receipt.

Measurement counts only the accepted candidate review, never an embedded review, when any recorded review invocation supplies --subject; pre-change deliveries with no such invocation retain their legacy review rule.

Native --help reads do not change a draft or publish a close and are excluded from lifecycle replay. The candidate gate uses the latest eligible root examination prompt before the examiner session's first user request; a continuation or later re-prompt cannot replace that association. Opaque observation/output paths do not replace the root prompt clock with an examiner request clock. Draft-start ownership follows successful opens or first edits across linked sessions for the same kind and DraftKey scope until close or abort; a close in another session is not replayable.

Native --host-sessions measurement has been qualified only against a small set of recorded OMP deliveries and their observed command shapes; it is not evidence of general host compatibility or of measurement qualification beyond them. Failed and partial trials on other models are negative results, not successes. When in doubt, prefer --requests mode: its report is explicitly supplied rather than replayed.

Role effort is the union of half-open request intervals, not CPU time. Continuations and unanswered requests are counted independently. --rework declares (session, request) objects with zero-based request indices; undeclared rework is unknown (not declared). Tokens, costs and quality scores are not inferred.

Missing, malformed, unreadable or unbindable host evidence prints not measured with its cause and exits zero. Argument grammar errors refuse; supplied-file errors remain refusals. Every host report states: observation provenance is not verified beyond commit order. Observations captured before a candidate but supplied later cannot be detected. Measurement is an observation report, not a formal proof.

Configuration

Destination configuration uses nested JSON objects. The dotted names below describe that object nesting, not literal JSON property names. nwdes reads its configuration keys without interpreting unrelated producers' settings.

{
  "nwdes": {
    "feature": {"directory": "global/features"},
    "epic": {"directory": "global/epics"},
    "project": {"directory": "global/product"}
  },
  "adr": {"directory": "docs/decisions"},
  "lanes": {"trunk": "main", "disposable": ["build/"]}
}

{
  "nwdes": {"feature": {"directory": "design/features"}}
}

{
  "nwdes": {"directory": "special/scoped-docs"}
}

Standard results

Write commands report written or unchanged outputs. Read commands print help, prompts, packets, or deltas. A refusal reports WHAT, WHY, and HOW for each detected defect. A successful command is not a workflow approval.

Common refusal names are MissingFact, PartInvalid, ConfigurationMalformed, HandoffInvalid, and DanglingReference. Closing can also report RoleNotAccepted. Read the group's help for its exact list. I/O or missing-asset failures are distinct from invalid supplied facts.

Successful product or design closes, expectations revisions, and owned-promise replacement through slice set can report withdrawals. Each notice identifies the removed entry, its retired references, and the role that can record replacement facts. The root chooses whether and when to invoke that role.

These lines accompany existing WROTE/UNCHANGED path lines only after successful output writing. A successful replacement exits 0 without a refusal on stderr. Failed writes publish no withdrawal notices; identical replay emits none.

Each removed structured entry has one notice, even when it has several retired references. WHAT uses pre-replacement paths and indexes. Parent removal is reported once, not again for its children. Notices follow canonical part/schema order and original array order; cause IDs follow deterministic identity order. Cascading verdict WHY identifies the original withdrawn expectation row and E ID.

Withdrawal removes the dependent entry, not just its citation. It neither aliases retired identities to replacements nor transfers evidence. There is no withdrawal verb, readiness gate, or automatic dispatch: HOW names possible repair roles and submission commands, while the root alone chooses whether and when to invoke them. Existing common write options still select repository and feature. Retained identities do not certify semantic freshness.

For worked commands with observed results, see the tutorial. For a real delivery, see Deliver a feature.