Validation re-runs while an author edits carriers

problem

An author editing a Spec re-runs sdp validate by hand after every save.

outcome

Let sdp validate --watch re-run the one validation path on every carrier change and stay alive after findings, as a loop for authoring and never a second validation path.

rule line 19 · specs/consumers/validate-watch.sdp.md:19

sdp validate --watch [root] installs its watcher first, then runs the same validate path sdp validate runs, from scratch, once at start and again after every carrier create, change, delete or rename under the root.

rule line 20 · specs/consumers/validate-watch.sdp.md:20

A carrier ends in .sdp.md, .sdp.gherkin or .sdp.ts. The watcher ignores the directories discovery skips, the configured exclusion prefixes and every non-carrier path other than the rules files and parameter files --rules names, which it watches wherever they live, as spec:validation.corpus-rules#rule.watchReruns and spec:validation.corpus-rules#rule.watchedParams state, and the symbolic links discovery warns about, as spec:extraction.excludes#rule.canonicalDiscovery states, because creating, removing or replacing one changes the warning list. The watcher never follows a link. A watched directory removed or replaced by a link, a file or another directory, and an event with no filename, each schedule a run because their affected carriers cannot be named. So does a watched directory's own watch reporting a change to the directory itself, because a directory deleted and recreated can keep its identity while that watch has died; on a platform that reports a change to the directory's attributes the same way, that change schedules a run too. An event for an entry that has the directory's own name can look the same and then schedules a run too, as where the filesystem reports no birth time for the directory. A directory that replaces a watched one, the root included, is watched in its place, and a root that no longer resolves to a directory ends the watch with exit 1.

rule line 21 · specs/consumers/validate-watch.sdp.md:21

Events that arrive while a run is in progress coalesce into one pending run.

rule.operatorStop line 22 · specs/consumers/validate-watch.sdp.md:22

Findings print as sdp validate prints them and the process stays alive; operator SIGINT terminates the process with exit 0 even while a rules body is active, without waiting for it. No further rules file runs or output is written after the stop.

no example exercises it

rule line 23 · specs/consumers/validate-watch.sdp.md:23

For sdp validate, --watch cannot combine with --check-clean, and it re-runs on carrier edits and on edits to the files --rules names, and never on source edits, so an author re-runs validation after editing an anchor. This rule restricts no other verb's --watch, which its own Spec states.

4 unkeyed rules.

Verifier bindings

• test:protocol.validate-watch · watch-loop checks verify the validate --watch authoring loop · anchored · test anchor binding present · test/cli.test.ts:1692

  External run evidence from test/cli.test.ts

  Test anchors: test:protocol.engine-provenance, test:protocol.extraction-determinism, test:protocol.projections-model.publication, test:protocol.regenerability, test:protocol.validate-watch. Specs verified by those bindings: spec:consumers.engine-provenance, spec:consumers.projections-model, spec:consumers.validate-watch, spec:extraction.determinism, spec:extraction.regenerability.

  Run 1: external run evidence from vitest 4.1.10

  Build: CI 439 · Branch: docs/articles-refresh-1 · Commit: 61576184ea9f39b7f91c51fef5ff991b0bf2d0e6 · Start: 2026-11-04T08:03:40.500Z · Stop: 2026-11-04T08:04:09.917Z

  Name	Suite	Result	Duration
  prints the exact help text for no args	sdp cli	passed	2.5 ms
  points operators to the shipped on-ramps and Protocol corpus	sdp cli	passed	2.6 ms
  describes both anchor forms and non-failing warnings in help	sdp cli	passed	0.61 ms
  prints the exact help text for --help	sdp cli	passed	0.29 ms
  builds the checkout-v1 example: writes graph, contracts, and registrar manifest atomically	sdp cli	passed	183.58 ms
  invalidates an existing Design Review when build replaces its source graph	sdp cli	passed	102.06 ms
  views the self-hosting corpus from the default repository root	sdp cli	passed	14803.46 ms
  renders contracts warnings through the one formatter and counts them in the summary	sdp cli	passed	11.76 ms
  withholds case-colliding contract paths with a warning: graph kept, nothing gates	sdp cli	passed	7.14 ms
  passes --check-clean on the example (determinism self-check through the CLI)	sdp cli	passed	63.79 ms
  end-to-end determinism self-check: delete generated/, rebuild, byte-identical	sdp cli	passed	239.81 ms
  fails clean on a root that is not a directory: one line, exit 1, never a stack trace	sdp cli	passed	0.44 ms
  rejects an unknown option: one line, exit 1, nothing runs	sdp cli	passed	0.2 ms
  accepts repeatable --exclude paths for build	sdp cli	passed	7.89 ms
  accepts repeatable --exclude paths for validate	sdp cli	passed	9.26 ms
  accepts repeatable --exclude paths for view	sdp cli	passed	8.56 ms
  uses the identical normalized exclusions in both --check-clean extractions	sdp cli	passed	11.76 ms
  refuses invalid --exclude path "" before build writes	sdp cli	passed	1.23 ms
  refuses invalid --exclude path "." before build writes	sdp cli	passed	0.67 ms
  refuses invalid --exclude path "./explorations" before build writes	sdp cli	passed	0.46 ms
  refuses invalid --exclude path "explorations/" before build writes	sdp cli	passed	0.41 ms
  refuses invalid --exclude path "/explorations" before build writes	sdp cli	passed	0.42 ms
  refuses invalid --exclude path "../x" before build writes	sdp cli	passed	0.41 ms
  refuses invalid --exclude path "a/../b" before build writes	sdp cli	passed	0.34 ms
  refuses invalid --exclude path "a//b" before build writes	sdp cli	passed	0.33 ms
  refuses invalid --exclude path "a\\b" before build writes	sdp cli	passed	0.49 ms
  refuses a missing --exclude operand before build writes	sdp cli	passed	0.51 ms
  names a flag supplied as an --exclude operand before build writes	sdp cli	passed	0.35 ms
  documents repeatable --exclude paths in help	sdp cli	passed	0.13 ms
  rejects a second root argument: one line, exit 1, nothing runs	sdp cli	passed	0.3 ms
  notes an empty authored model: zero spec files still builds and exits 0, but says where it looked	sdp cli	passed	2.84 ms
  renders a finding's location exactly once, from the structured fields: file:line — [severity]	sdp cli	passed	5.53 ms
  renders a Gherkin parser failure through the public CLI	sdp cli	passed	3.78 ms
  exits 1, writes nothing, and removes a stale graph.json on a hard-error corpus	sdp cli	passed	6.4 ms
  fails build on an integer-like design key holding a static value	sdp cli	passed	10.07 ms
  fails build on an integer-like design key holding a non-static value	sdp cli	passed	3.54 ms
  fails build on an integer-like design key holding a method	sdp cli	passed	3.59 ms
  fails build on an integer-like design key holding an accessor	sdp cli	passed	3.72 ms
  fails --check-clean on a diverging second extraction: exit 1, the stale graph.json removed	sdp cli	passed	11.32 ms
  fails --check-clean on a diverging second contract generation: exit 1, no artifact survives	sdp cli	passed	40.44 ms
  owns the contracts tree wholesale: with nothing to generate, a stale contracts dir is removed	sdp cli	passed	8.01 ms
  refuses a swapped registrar ancestor before creating outside parent directories	sdp cli	passed	23.4 ms
  reconciles a registrar sibling that a later generation no longer owes	sdp cli	passed	44.01 ms
  fails --check-clean on registrar-byte drift and removes the uncertified known set	sdp cli	passed	54.69 ms
  passes --check-clean without a prior manifest when no registrars are owed	sdp cli	passed	8.5 ms
  fails --check-clean on registrar manifest whitespace drift	sdp cli	passed	53.03 ms
  fails --check-clean on registrar manifest ignored property drift	sdp cli	passed	55.98 ms
  removes graph, contracts, manifest, and registrar siblings after a staged write failure	sdp cli	passed	46.62 ms
  fails clean when extraction throws past discovery: one line, exit 1, the stale graph.json removed	sdp cli	passed	1.74 ms
  fails clean when generated exists as a file: one line each for build and view, never a stack trace	sdp cli	passed	1.59 ms
  names the survivor when a recovery-path removal is denied: a stale artifact never silently reads as current	sdp cli	passed	1.58 ms
  stops a build when an existing Design Review cannot be invalidated	sdp cli	passed	6.18 ms
  fails clean when the checks throw: one line, exit 1, the built graph.json stays	sdp cli	passed	7.39 ms
  suppresses the empty-model note when spec files were found but none reified — a failed file is not an absent one	sdp cli	passed	4.51 ms
  treats a root of only ordinary .feature files as an empty authored model, not a missing-identity error	sdp cli	passed	3.08 ms
  suppresses the empty-model note when a failed .sdp.gherkin finding.file matches the carrier suffix predicate	sdp cli	passed	3.35 ms
  builds a mixed root with one .sdp.gherkin carrier and ignores the ordinary .feature sibling	sdp cli	passed	3.64 ms
  removes the temp twin on a failed build and a failed view — no partial .tmp artifact survives	sdp cli	passed	21.76 ms
  recognizes the published-bin path: a .bin-style symlink resolves to the entry module	sdp cli	passed	0.79 ms
  exits 0 quietly on a stdout EPIPE and stays fatal for any other stream error	sdp cli	passed	0.92 ms
  validates the example: exit 0, the artifact written, and no warning	sdp cli	passed	58.4 ms
  gates on the checks, not the build: a clean-building broken link validates to exit 1 with the artifact kept	sdp cli	passed	8.03 ms
  short-circuits the checks on extraction hard errors: validate keeps build semantics	sdp cli	passed	4.99 ms
  prints help plus an unknown-command error	sdp cli	passed	0.23 ms
  views the example: validate + the Design Review written, with no warning	sdp cli	passed	84.09 ms
  owns the view directory wholesale: a stale page does not survive a re-render	sdp cli	passed	35.98 ms
  regenerates the view byte-identically: delete generated/, re-view, same bytes	sdp cli	passed	58.04 ms
  writes the view even when checks fail: findings render in it, the exit code is validate's	sdp cli	passed	9.51 ms
  keeps build semantics on extraction hard errors: no graph, no view, stale view removed	sdp cli	passed	4.54 ms
  fails view --check-clean on a diverging second render: exit 1, the stale view removed	sdp cli	passed	10.34 ms
  fails clean when the render throws: one line on stderr, exit 1, the stale view removed	sdp cli	passed	6.38 ms
  closes the compiled watch process with exit 0 after operator SIGINT	sdp validate --watch	passed	490.08 ms
  documents --watch as a validate-only authoring loop	sdp validate --watch	passed	0.32 ms
  rejects --watch on build with a named error and no watcher	sdp validate --watch	passed	0.23 ms
  rejects --watch on view with a named error and no watcher	sdp validate --watch	passed	0.13 ms
  rejects --watch on census with a named error and no watcher	sdp validate --watch	passed	0.13 ms
  rejects --watch on mermaid with a named error and no watcher	sdp validate --watch	passed	0.13 ms
  rejects --watch on gherkin with a named error and no watcher	sdp validate --watch	passed	0.13 ms
  rejects --watch on import with a named error and no watcher	sdp validate --watch	passed	0.31 ms
  rejects --watch on new with a named error and no watcher	sdp validate --watch	passed	0.4 ms
  rejects --watch on q with a named error and no watcher	sdp validate --watch	passed	0.35 ms
  rejects --watch --check-clean with a named error and no watcher	sdp validate --watch	passed	0.21 ms
  installs the watcher before the first validation cycle	sdp validate --watch	passed	8.85 ms
  catches an edit during the first cycle with exactly one coalesced rerun	sdp validate --watch	passed	12.09 ms
  coalesces a burst during an active cycle into exactly one rerun	sdp validate --watch	passed	11.97 ms
  prints validation findings and keeps watching until abort exits 0	sdp validate --watch	passed	11.72 ms
  ignores generated, dist, node_modules, coverage, dot directories, and configured excludes	sdp validate --watch	passed	13.37 ms
  coalesces production-shaped events from later turns into one pending rerun	sdp validate --watch	passed	11.99 ms
  does not natively subscribe to excluded or generated subtrees	sdp validate --watch	passed	31.81 ms
  routes a native watcher error through a typed channel and closes once	sdp validate --watch	passed	7.71 ms
  clean-repo determinism: the full pipeline at a different absolute path is byte-identical	not recorded	passed	152.57 ms
  clean-repo determinism: an untouched Protocol copy has the same graph with external and local engines	not recorded	passed	9629.74 ms
  prints one line naming the package version and the recorded commit, and exits 0	sdp --version	passed	0.67 ms
  names the commit unknown when the build recorded none or recorded something else	sdp --version	passed	1.12 ms
  reads the version from the package manifest two directories above the CLI module	sdp --version	passed	0.46 ms
  documents --version and --params in the usage text	sdp --version	passed	0.2 ms
  records the checked-out commit at build time, or unknown when git cannot name one	sdp --version	passed	16.95 ms
  publishes the commit the build step reads from git beside the CLI	sdp --version	passed	1.94 ms
  builds commit metadata from a substituted git archive extracted without .git	sdp --version	passed	60.71 ms
  uses only a full archive commit when git gives none, keeping git first	sdp --version	passed	1.82 ms
  answers from the compiled CLI with the commit its build recorded beside it	sdp --version	passed	475.14 ms
  runs recipe 4 as shipped, its changed files passed with --params @PATH	a shipped recipe file through the compiled CLI	passed	588.2 ms

• test:protocol.validate-watch-rules · process checks verify operator stop during active corpus rules · anchored · test anchor binding present · test/corpus-rules.test.ts:351

  External run evidence from test/corpus-rules.test.ts

  Test anchors: test:protocol.validate-watch-rules. Specs verified by those bindings: spec:consumers.validate-watch.

  Run 2: external run evidence from vitest 4.1.10

  Build: CI 439 · Branch: docs/articles-refresh-1 · Commit: 61576184ea9f39b7f91c51fef5ff991b0bf2d0e6 · Start: 2026-11-04T07:59:39.962Z · Stop: 2026-11-04T08:03:39.928Z

  Name	Suite	Result	Duration
  documents repeatable rules, per-file parameters and check-clean	corpus rule arguments	passed	3.18 ms
  refuses "--params" before deriving	corpus rule arguments	passed	2.02 ms
  refuses "--params" before deriving	corpus rule arguments	passed	0.53 ms
  refuses "--rules" before deriving	corpus rule arguments	passed	0.36 ms
  refuses "--rules" before deriving	corpus rule arguments	passed	0.86 ms
  refuses "--rules" before deriving	corpus rule arguments	passed	1.19 ms
  refuses "--rules" before deriving	corpus rule arguments	passed	0.57 ms
  refuses "--rules" before deriving	corpus rule arguments	passed	0.6 ms
  refuses "--rules" before deriving	corpus rule arguments	passed	0.52 ms
  binds parameters to the preceding file across other options	corpus rule arguments	passed	2.92 ms
  refuses rules on build	corpus rule arguments	passed	0.81 ms
  refuses rules on view	corpus rule arguments	passed	0.3 ms
  refuses rules on census	corpus rule arguments	passed	0.31 ms
  refuses rules on mermaid	corpus rule arguments	passed	0.5 ms
  refuses rules on gherkin	corpus rule arguments	passed	0.41 ms
  refuses rules on q	corpus rule arguments	passed	0.49 ms
  refuses the same rules file through a symlink before deriving	corpus rules on validate	passed	2.57 ms
  refuses a finding file outside root-relative POSIX paths: /etc/passwd	corpus rules on validate	passed	31.38 ms
  refuses a finding file outside root-relative POSIX paths: ../outside.ts	corpus rules on validate	passed	8.95 ms
  refuses a finding file outside root-relative POSIX paths: src/../../outside.ts	corpus rules on validate	passed	11.3 ms
  refuses a finding file outside root-relative POSIX paths: src\\probe.ts	corpus rules on validate	passed	14.57 ms
  refuses a finding file outside root-relative POSIX paths: C:/outside.ts	corpus rules on validate	passed	16.94 ms
  reports a root-relative finding path: src/probe.ts	corpus rules on validate	passed	18.38 ms
  reports a root-relative finding path: src/../probe.ts	corpus rules on validate	passed	13.86 ms
  reports a error finding apart from Protocol findings	corpus rules on validate	passed	18.35 ms
  reports a warning finding apart from Protocol findings	corpus rules on validate	passed	21.36 ms
  fails a broken file and continues: throw new Error('two\nlines')	corpus rules on validate	passed	15.12 ms
  fails a broken file and continues: return {	corpus rules on validate	passed	37.68 ms
  fails a broken file and continues: return { findings: [] }; /* open comment	corpus rules on validate	passed	20.15 ms
  fails a broken file and continues: return { findings: [] }; }) ;(function(){	corpus rules on validate	passed	17.1 ms
  fails a broken file and continues: return { diagnostics: ['bad'] }	corpus rules on validate	passed	6 ms
  fails a broken file and continues: return { unknownParams: ['typo'], accepts: [] }	corpus rules on validate	passed	7.06 ms
  fails a broken file and continues: return { findings: [{ validatorId: 'a', severity: 'warning', message: 'x' }] }	corpus rules on validate	passed	8.88 ms
  fails a broken file and continues: return { findings: [{ ...({ validatorId: "probe-rule", subjectId: "probe-subject", severity: "error", message: "probe finding" }), severity: 'info' }] }	corpus rules on validate	passed	16.32 ms
  fails a broken file and continues: return { findings: [{ ...({ validatorId: "probe-rule", subjectId: "probe-subject", severity: "error", message: "probe finding" }), validatorId: 'a/b' }] }	corpus rules on validate	passed	8.46 ms
  fails a broken file and continues: return { findings: [{ ...({ validatorId: "probe-rule", subjectId: "probe-subject", severity: "error", message: "probe finding" }), line: 1 }] }	corpus rules on validate	passed	7.21 ms
  fails a broken file and continues: return { findings: [{ ...({ validatorId: "probe-rule", subjectId: "probe-subject", severity: "error", message: "probe finding" }), relatedId: 1 }] }	corpus rules on validate	passed	8.99 ms
  fails a broken file and continues: return { findings: [{ ...({ validatorId: "probe-rule", subjectId: "probe-subject", severity: "error", message: "probe finding" }), path: 1 }] }	corpus rules on validate	passed	6.75 ms
  fails a broken file and continues: return { findings: [{ ...({ validatorId: "probe-rule", subjectId: "probe-subject", severity: "error", message: "probe finding" }), file: '' }] }	corpus rules on validate	passed	7.84 ms
  fails an unreadable file	corpus rules on validate	passed	8.66 ms
  discards every finding of a malformed answer	corpus rules on validate	passed	7.8 ms
  clones the graph and report separately for each file and leaves written bytes whole	corpus rules on validate	passed	8.7 ms
  gives each file only its own parameters, including JSON files and keyed values	corpus rules on validate	passed	8 ms
  keeps the ordinary validate output unchanged and q report free of corpus data	corpus rules on validate	passed	9.15 ms
  does not run rules when the graph does not derive	corpus rules on validate	passed	9.11 ms
  exposes corpus data only on the aggregate validate outcome	not recorded	passed	7.31 ms
  awaits bodies in file order and keeps a Protocol error fatal	not recorded	passed	12.4 ms
  SIGINT exits 0 during a live rules body, with no later output or rules, even if it can settle: false	not recorded	passed	819.64 ms
  SIGINT exits 0 during a live rules body, with no later output or rules, even if it can settle: true	not recorded	passed	820.15 ms
  rereads rules when its file changes	not recorded	passed	24.28 ms
  gives each watch cycle fresh parameters after a body mutates them	not recorded	passed	14.56 ms

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

No decision record named.

• component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:31 · layer edge · context protocol

  Uses

  • component:protocol.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol
  • component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:671 · layer application · context protocol
  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:197 · layer application · context protocol
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
  • component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol
  • component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:697 · layer application · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:76 · layer domain · context protocol
• impl:protocol.validate-watch · watches carrier directories and coalesces events into a pending validation rerun · src/cli/validate-watch.ts:924

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:31 · layer edge · context protocol

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.