T-DOQI-serialize-moon-in-quality-line-mode

Status: open/ready · Impact: medium · Complexity: small

AUTO-DEFINED: this spec was best-effort machine-authored by /sdlc:task-auto-define on 2026-07-04 because the task is autonomy: autonomous/pr. Review the Goal, Approach, Today, Files-to-touch, and Acceptance-criteria carefully before trusting it.

Goal

sdlc quality run --line launches its per-check bunx moon run invocations in parallel, and on a moon-based project those concurrent invocations collide on moon’s workspace lock — producing a spurious FAIL for a check that is actually clean. This follow-up, spawned from T-QX1Q-gate-covers-declaration-emit in git@github.com:sksizer/markdown-contract.git, asks the sdlc plugin (the source of truth for the quality runner) to serialize those per-check moon invocations in --line mode — or, at minimum, document --log as the trustworthy mode for moon-based projects — so concurrent bunx moon run calls no longer collide on moon’s workspace lock and a real failure is never masked or fabricated by lock contention.

sdlc quality run --line produced a false FAIL bunx moon run core:lint caused by moon workspace-lock contention between the parallel bunx moon run invocations it launches; --log (sequential) mode was clean and a baseline-gated --line retry also came back clean, confirming a flake rather than a real failure. Fix: serialize the per-check moon invocations in --line mode (or, at minimum, document --log as the trustworthy mode for moon-based projects) so concurrent bunx moon run calls no longer collide on moon’s workspace lock and report spurious failures.

— T-QX1Q-gate-covers-declaration-emit

Today

The premise that sdlc quality run --line “launches its per-check bunx moon run invocations in parallel” does not hold against the current runner code: both run paths execute the resolved verb list strictly sequentially in a blocking spawnSync loop. The observed workspace-lock false-FAIL therefore cannot originate from runner-level parallelism — the runner never overlaps two bunx moon run calls. What survives is a stale doc-comment that seeds the “parallel” belief, an undocumented --log-is-trustworthy contract for moon-based projects, and the absence of a regression test pinning the sequential invariant.

Location	Role today
plugin/lib/services/quality/ops/run.ts	Substrate-native `sdlc quality run` op — the live path. Runs verbs sequentially in a blocking `spawnSync` loop for both `--line` (silent, buffered) and `--log` (streamed, `stdio: inherit`). Its module doc-comment mislabels the sibling core as “the parallel, io-seam’d core” and references a `run_quality_checks.ts` shim that no longer exists — the seed of the “parallel” premise.
plugin/lib/services/quality/run-checks.ts	The legacy quality-run core (`runChecks`), self-described as “sequential run/emit logic” and implemented as a sequential `spawnSync` loop. Now has no importers (the `run_quality_checks.ts` shim it served is gone).
plugin/conventions/sdlc-yaml.md	Conventions doc. Its Execution-semantics section already states verbs “run sequentially in declared order,” but does not name `--log` as the trustworthy mode for moon-based projects or explain the moon workspace-lock interaction.
plugin/lib/services/quality/tests/quality_ops.test.ts	The op’s unit + CLI-parity suite. Exercises `--line`/`--log` pass/fail projection but does not assert that verbs execute strictly sequentially, so a refactor to `Promise.all` could reintroduce verb-level parallelism undetected.

Proposed

Because sdlc quality run already runs verbs sequentially, the primary “serialize the per-check moon invocations” ask is satisfied by the current implementation — there is no runner-level parallelism to remove. The remaining faithful work is the task’s explicit fallback arm plus hardening: (1) correct the stale plugin/lib/services/quality/ops/run.ts doc-comment that wrongly calls the core “parallel” and references a removed shim, (2) document --log as the trustworthy mode for moon-based projects in the conventions doc and the op’s flag help, and (3) pin the strictly-sequential invariant with a regression test so a future refactor cannot silently reintroduce concurrent bunx moon run invocations that would collide on moon’s workspace lock.

Approach

In plugin/lib/services/quality/ops/run.ts, rewrite the module doc-comment so it no longer describes the sibling core as “the parallel, io-seam’d core” and no longer references the removed run_quality_checks.ts shim. State the real contract: sdlc quality run executes the resolved verb list strictly sequentially in a blocking spawnSync loop for both --line and --log modes, so per-check bunx moon run invocations never overlap and cannot contend on moon’s workspace lock.
In the same file, extend the --log (and --line) flag help strings so sdlc quality run --help states that for moon-based projects verbs run sequentially and --log is the recommended trustworthy mode when a stray moon daemon or workspace lock is observed.
In plugin/conventions/sdlc-yaml.md, add a short note to the Execution-semantics section: the runner never parallelizes verbs, so for moon-based projects --log is the trustworthy mode and a workspace-lock FAIL indicates an external concurrent moon process rather than the runner.
In plugin/lib/services/quality/tests/quality_ops.test.ts, add a regression test that runs sdlc quality run with two verbs which each append a start and end marker to a shared temp file (with a small sleep between), then asserts the markers do not interleave — i.e. the second verb starts only after the first finishes — pinning strictly-sequential execution so a future refactor to Promise.all cannot reintroduce verb-level parallelism.
Run bun test to confirm the new test and the existing quality suite pass.

Files to touch

Location	Kind	Change
plugin/lib/services/quality/ops/run.ts	modify	Rewrite the module doc-comment to drop the “parallel core” / `run_quality_checks.ts`-shim references and state sequential execution; extend the `--log`/`--line` flag help to document `--log` as the trustworthy mode for moon-based projects.
plugin/conventions/sdlc-yaml.md	modify	Add a note to the Execution-semantics section documenting sequential verb execution and `--log` as the trustworthy mode for moon-based projects.
plugin/lib/services/quality/tests/quality_ops.test.ts	modify	Add a regression test asserting `sdlc quality run` executes its verb list strictly sequentially (non-overlapping).

Acceptance criteria

AC-1: plugin/lib/services/quality/ops/run.ts contains no doc-comment that describes the run core as “parallel” or references run_quality_checks.ts; its module comment states verbs run sequentially in both --line and --log modes.
AC-2: sdlc quality run --help documents --log as the recommended trustworthy mode for moon-based projects (the --log flag help text names it).
AC-3: plugin/conventions/sdlc-yaml.md documents that sdlc quality run executes verbs sequentially and names --log as the trustworthy mode for moon-based projects.
AC-4: plugin/lib/services/quality/tests/quality_ops.test.ts adds a test asserting sdlc quality run executes its verb list strictly sequentially (non-overlapping), and the full bun test suite passes.

Out of scope

Introducing verb-level parallelism or a --parallel mode to the runner.
Removing or refactoring the now-unused runChecks core in plugin/lib/services/quality/run-checks.ts (dead-code cleanup is a separate task).
Altering moon’s own workspace-lock or daemon behavior (upstream moon), or the markdown-contract project’s moon config / quality_checks list.
Baseline-gating (--diff-against-baseline) behavior.

Dependencies

none — self-contained within the sdlc plugin’s quality service. Relates to T-QX1Q-gate-covers-declaration-emit (the spawning task) but does not depend on it.

Discovery context

Spawned by /sdlc:spawn-task-pr on 2026-07-04 UTC from T-QX1Q-gate-covers-declaration-emit in git@github.com:sksizer/markdown-contract.git.

← Back to Tasks