@mstar-harness/dsh 3.8.2 → 3.9.0

package/harness-skills/mstar-sdd/references/file-handoffs.md

@@ -4,14 +4,16 @@ PM and subagents move artifacts as **files**, not pasted text. Pasted content st
 
 ## Before implementer dispatch
 
-Run the SDD helpers through the engine CLI **`mstar sdd …`** (engine-backed; the former bash scripts are removed — semantics unchanged).
+**PM owns helper execution and shared coordination writes.** Keep one canonical per-plan `{SDD_DIR}` root; only PM writes its `context.json` and `progress.md`. Subdirectories namespace artifacts, not a second SDD root. Scheduling → `mstar-sdd` § Ready-task scheduling.
+
+PM runs context-dependent `mstar sdd workspace`, `task-brief`, and `review-package` helpers serially for the corresponding assigned checkout/branch. These helpers may update shared context; parallel hosted leaves never invoke them. Before each dispatch, PM fixes absolute task-specific brief/report/diff destinations and copies `Worktree path` / branch into the Assignment. Updating context for another task must not change an already-dispatched leaf's inputs.
 
 1. `export SDD_DIR=$(mstar sdd workspace <plan-id>)`
    - Iteration L1 (implementer cwd = feature worktree):
-     `export MSTAR_CONTROL_ROOT=<control_worktree_path>`
-     or `mstar sdd workspace <plan-id> <control_worktree_path>`
+     `export MSTAR_CONTROL_ROOT=<main-repo-root>` — the **derived main worktree** root, verified by Git probing before the fail-closed guard
+     or `mstar sdd workspace <plan-id> <main-repo-root>`
      so `{SDD_DIR}` lands on the control harness (default-gitignored plans/status/sdd). Do not create a second SDD tree under the feature checkout.
-2. Write the execution context file `$SDD_DIR/context.json` — the absolute destination contract every handoff cites:
+2. PM writes `$SDD_DIR/context.json` for the current helper operation — parallel hosted handoffs pin these values in their Assignment instead of consulting mutable plan context:
 
    ```json
    {
@@ -24,15 +26,15 @@ Run the SDD helpers through the engine CLI **`mstar sdd …`** (engine-backed; t
    }
    ```
 
-   All paths absolute; `planFile`/`sddDir` must resolve inside the control harness; `featureCwd` must be the assigned feature worktree on `workingBranch`. The declared control root is authoritative — never re-inferred from the feature cwd.
+   All paths absolute; `planFile`/`sddDir` must resolve inside the control harness; `featureCwd` must be the assigned feature worktree on `workingBranch`. The declared control root is authoritative — never re-inferred from the feature cwd, and it must canonicalize to the Git-derived main worktree root (an integration/foreign checkout is refused, not redirected).
 3. `mstar sdd task-brief <plan-file> <N> --context "$SDD_DIR/context.json"` — bound producer: validates the artifact destination **before** mkdir/write and prints the absolute brief path (`{SDD_DIR}/task-N-brief.md`).
-4. Record `BASE_SHA` (`git rev-parse HEAD` before dispatch).
+4. Record `BASE_SHA` (`BASE_SHA=$(git -C "$FEATURE_CWD" rev-parse HEAD)` before dispatch). For dependent tasks, first satisfy `mstar-sdd` § Ready-task scheduling: PM serially integrates reviewed prerequisite commits and records their ancestry in this base. Include those commit/base IDs and the check result in the handoff; review approval alone is insufficient.
 5. Dispatch implementer with:
    - One line scene-setting (where task fits)
    - Absolute brief path: read first — verbatim requirements
    - Interfaces / decisions brief cannot know
    - Absolute report path: `$SDD_DIR/task-N-report.md`
-   - Absolute control root, feature cwd, plan and context-file paths (destination contract — see prompt templates)
+   - Absolute control root, feature cwd, branch and plan paths, plus task-specific brief/report/diff paths fixed for this dispatch; the context path is PM coordination metadata, not a leaf checkout selector
    - `Model tier` → host-specific model (required)
    - **`SDD implementer session`**: `fresh` (new subagent) or `sticky` (resume — see **`sticky-implementer-session.md`**)
 
@@ -42,20 +44,62 @@ Implementer writes full report to `task-N-report.md`. Return to PM only:
 
 - Status: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
 - Commits (SHAs)
-- One-line test summary
+- One-line verification summary (affected tests or scoped static evidence)
 - Concerns (if any)
 
+## Verification evidence
+
+Choose evidence from the actual diff, not the file extension. Scope limits → `mstar-harness-core` § 定向执行与验证边界.
+
+- **Executable logic**: report the affected test file(s), exact command/selector and actual output; bug fixes include the reproduction red/green evidence. No `Verification mode` is needed for this test triple.
+- **Non-executable documentation or prompt/skill policy**: use `Verification mode: scoped-check` with real scoped static or before/after observable evidence. This mode cannot exempt executable code, configuration logic or executable snippets from corresponding tests. Mixed changes retain executable test evidence and do not claim a scoped-check exemption for the task.
+
+```markdown
+Verification mode: scoped-check
+Changed files: <actual non-executable files>
+Tests: N/A
+Reason: <why scoped evidence fits the actual change>
+Check command: <exact targeted command actually run>
+Check result: <actual exit/result and observed output>
+```
+
+`Check result` accepts concrete static-tool output (for example `docs/guide.md:12: scoped rule`); a test-style PASS/exit token is not required. It must be nonempty and non-placeholder. Whether an observation is truthful and sufficient remains PM/QC's responsibility.
+
+For appended fixes, begin each new block with `## Verification round: <concrete label>` (for example `fix 1`). Only the last such round is active; earlier rounds remain history and cannot fill missing fields. A report without round headings is one active block. The active round supplies its complete applicable evidence, including `Verification mode` for scoped checks; executable rounds retain their own test triple without a mode. A blank/placeholder round label is invalid.
+
+Replace every placeholder with actual evidence. Unknown or duplicate modes within the active round, missing/empty/placeholder fields, and bare `Tests: N/A` fail; do not copy the template as a report. `assertSddTddTriple` / `mstar lint <task-report>` validate structure only. PM/QC check the actual changed range, applicability and evidence honesty; the checker cannot establish that commands ran or intercept arbitrary shell execution. For policy changes, record the before/after expectation and triggering scenario alongside the concrete check; no broad model-eval matrix is implied.
+
+### Captured check evidence (`sdd evidence`)
+
+An already-authorized check can run **once** and leave version-bound raw evidence in canonical SDD for read-only review: reviewers inspect the retained bundle instead of repeating the child command. Division of labor: **PM publishes the fixed, immutable task capture request** (task-specific JSON naming context, coverage declaration, declared inputs and selected environment keys); the **developer captures** the already-authorized check with it; QC/QA only inspect and verify — they never repeat the recorded child. The capture request is a separate immutable artifact, never the rotating `context.json`; no hosted leaf resolves it as a checkout selector. Capture authorizes nothing by itself: it neither dispatches agents nor grants test/full-suite/E2E permission.
+
+Exact public command shapes (angle-bracket terms are required CLI values):
+
+```text
+mstar sdd evidence capture --request <absolute-task-request.json> -- <executable> [args...]
+mstar sdd evidence verify --sdd-dir <absolute-dir> --plan <id> --task <id> --run <uuid> [--target <absolute-target.json>]
+```
+
+- Capture runs the child once (literal argv, no shell), POSIX linux/darwin only (unsupported hosts refuse before spawn), and retains `{SDD_DIR}/evidence/<run-uuid>/` with fixed `record.json`, `stdout.log`, `stderr.log`; every retry is a fresh run UUID. Capture exits: child exit code preserved; missing executable 127; timeout 124; signal 128+n (parent SIGINT 130 / SIGTERM 143); gate/IO refusal 1; usage 2. Cite the raw log paths as evidence links — not paraphrased output.
+- `verify` is read-only and portable: it never runs the recorded child, discovery or version probes, writes no assessment artifact, and emits exactly one JSON assessment. Without `--target`, exit 0 means complete **integrity only** — a retained failed run still verifies with outcome `failed` (stderr: `integrity only; outcome=<value>; acceptance not assessed`). With `--target`, exit 0 means reuse **candidate** (stderr adds `reuse candidate; coverage review required`); every non-candidate exits 1; usage 2.
+- Four outputs stay separate everywhere — **integrity** (bundle complete/unaltered), **outcome** (recorded process result), **target applicability** (`not-assessed`/`candidate`/`changed`/`uncertain`), **coverage judgment** (always `review-required` in v1). No exit code or record field decides acceptance: there is no parser promise, no pass/fail counts and no automatic coverage inference (`counts` stays null in v1) — a reviewer judges coverage.
+- Reuse semantics (first match): tested bytes equal after a later commit or a docs-only change stay reuse candidates; a changed shared runtime/config/fixture/dependency input names the affected gap (`changed`); failed/incomplete proof, unknown input scope or a different repository stays `uncertain` — a pre-fix failure is retained as `failed` and never relabeled a pre-feature baseline; without a target the result is `not-assessed`, never candidate. An empty environment allowlist or a lockfile-only dependency declaration is the caller's reviewed assumption, not automatic completeness.
+- Non-executable documentation/policy never manufactures capture evidence — it uses `Verification mode: scoped-check` above. Historical manual evidence stays manual/unverified: cite it with provenance and reviewer reasoning; NEVER retrofit it into a v1 runner record.
+- The old `mstar sdd exec` entry is unchanged and stays PM-only serialized launch (§ Bound child launch); hosted leaves never use it for their assigned checks.
+
 ## After implementer DONE
 
-1. `HEAD_SHA=$(git rev-parse HEAD)`
-2. `mstar sdd review-package "$BASE_SHA" "$HEAD_SHA" --context "$SDD_DIR/context.json"` — bound: probes git in `featureCwd`, writes the diff into the control sddDir, prints absolute paths.
+PM sets `FEATURE_CWD` from the completed task's immutable Assignment `Worktree path`, verifies its assigned branch, and restores context to that same checkout/branch. Generate the task-specific review package serially from this path; do not use the PM shell cwd for task endpoints. Leaves keep their dispatched inputs unchanged.
+
+1. `HEAD_SHA=$(git -C "$FEATURE_CWD" rev-parse HEAD)`
+2. `mstar sdd review-package "$BASE_SHA" "$HEAD_SHA" --context "$SDD_DIR/context.json"` — context `featureCwd` must equal the same `$FEATURE_CWD` used for `HEAD_SHA`; probes git there, writes the diff into the control sddDir, prints absolute paths.
 3. Dispatch task reviewer with: brief path, report path, diff path, Global Constraints (verbatim from plan).
 
 **Never use `HEAD~1` as BASE** — multi-commit tasks truncate.
 
 ## Bound child launch (CLI-launchable children)
 
-When the implementer is a CLI command rather than a hosted subagent, launch it through the bound argv entry — never raw from a primary/control checkout:
+**PM-only serialized launch:** when the implementer is a CLI command rather than a hosted subagent, PM holds the serialized context operation through context validation and child spawn, using the launch Assignment's fixed checkout/branch. Do not rotate context until the launch resolves. Hosted leaves never use this entry for their assigned checks; they run allowed commands directly from their verified assigned feature workdir and branch:
 
 ```bash
 mstar sdd exec --context "$SDD_DIR/context.json" -- <argv...>
@@ -68,24 +112,18 @@ mstar sdd exec --context "$SDD_DIR/context.json" -- <argv...>
 
 Hosted subagents are not cwd-bound by the launcher, so their dispatch prompt must carry the absolute destination contract (templates: `implementer-prompt.md`, `implementer-continuation-prompt.md`, `task-reviewer-prompt.md`) and their first step is to observe, then write:
 
-1. Observe `pwd` and the checked-out branch in the tool's workdir; both must equal `featureCwd`/`workingBranch`. On mismatch, stop and report — a declared-correct assignment does not make a wrong-checkout write safe.
-2. Source edits go through the tool workdir at `featureCwd` (or absolute feature paths); briefs/reports/diffs go only to the absolute control paths from the handoff.
+1. Observe `pwd` and the checked-out branch in the tool's workdir; both must equal the immutable Assignment `Worktree path` / branch (`featureCwd`/`workingBranch`), never a newly read value from mutable plan context. On mismatch, stop and report — a declared-correct assignment does not make a wrong-checkout write safe.
+2. Source edits go through the assigned feature workdir; write the report only to its fixed task-specific path and consume brief/diff artifacts only from the dispatched paths. Do not modify shared context/progress or invoke context-writing workspace/task-brief/review-package helpers; request missing artifacts from PM.
 
 ## Fix loop
 
-Fix subagent appends to same `task-N-report.md` with test evidence:
-
-- Covering test file(s)
-- Command run
-- Output (pristine — warnings are findings)
-
-Re-dispatch reviewer only when all three are present.
+Fix subagent appends a new `## Verification round: <concrete label>` to the same `task-N-report.md`, followed by the complete affected executable test triple or applicable `scoped-check` block above, with actual output (warnings remain findings). Reuse unaffected evidence, citing its original range and why it remains applicable. Re-dispatch the owning reviewer for the assigned finding/fix delta when the required evidence is present.
 
-The per-task fix loop applies the same fix-round mechanics as plan-level QC fix waves (SKILL.md · "After all tasks" — unverified rounds count, full re-entry, capped cross-round excerpt, honest non-convergence): from round ≥2 the excerpt of prior rounds' findings/dispositions goes into the fix dispatch brief, and the round tally/verification history lands in `$SDD_DIR/progress.md`.
+The per-task fix loop applies the same fix-round mechanics as plan-level QC fix waves (SKILL.md · "After all tasks" — unverified rounds count, affected finding/fix-delta re-entry, capped cross-round excerpt, honest non-convergence): from round ≥2 the excerpt of prior rounds' findings/dispositions goes into the fix dispatch brief, and the round tally/verification history lands in `$SDD_DIR/progress.md`.
 
 ## Progress ledger
 
-On clean task review, append to `$SDD_DIR/progress.md`:
+On clean task review, PM alone appends to `$SDD_DIR/progress.md`:
 
 ```text
 Task N: complete (<base>..<head>, review clean)
@@ -95,7 +133,7 @@ Minor findings: append under `## Minor (for plan QC)` in same file.
 
 ## Plan-level QC package
 
-After all tasks:
+After all tasks, PM generates the package serially from the integrated checkout with its corresponding context:
 
 ```bash
 MERGE_BASE=$(git merge-base <target-branch> HEAD)

package/harness-skills/mstar-sdd/references/implementer-continuation-prompt.md

@@ -26,10 +26,10 @@ Dispatch:
 
     - Control harness root (briefs/reports/diffs live here): [CONTROL_ROOT]
     - Feature worktree — cwd for all source edits, branch [WORKING_BRANCH]: [FEATURE_CWD]
-    - Plan: [PLAN_FILE] — Context file: [CONTEXT_FILE]
+    - Plan: [PLAN_FILE] — PM coordination context: [CONTEXT_FILE] (never use it to select your checkout)
     - Brief: [BRIEF_FILE] — Report: [REPORT_FILE]
     - First step on resume: re-observe `pwd` and the checked-out branch — a sticky session may wake in a different cwd; on mismatch with [FEATURE_CWD]/[WORKING_BRANCH], stop and report BLOCKED — do not write.
-    - These destinations bind the handoff, not the host: a later deliberate `chdir`, absolute-path write outside [FEATURE_CWD], or host-native edit tool (apply_patch) is NOT blocked. CLI-launchable children are started via `mstar sdd exec --context [CONTEXT_FILE] -- <argv>` (starting cwd = feature worktree).
+    - These destinations bind the handoff, not the host: a later deliberate `chdir`, absolute-path write outside [FEATURE_CWD], or host-native edit tool (apply_patch) is NOT blocked. Execute allowed commands directly with the tool workdir fixed to the verified [FEATURE_CWD] / [WORKING_BRANCH]. Hosted leaves must not invoke `mstar sdd exec --context` or resolve cwd from mutable shared context; that entry is reserved for PM serialized CLI launch (file-handoffs.md § Bound child launch).
 
     ## Context not in the brief
 
@@ -39,11 +39,16 @@ Dispatch:
 
     Write your full report to: [REPORT_FILE]
 
+    ## Scope and stop
+
+    Use only the brief's owned files, relevant inputs and named checks. Do not restart global exploration, extend the task, or run local full suites without the user's explicit scoped permission. Reuse unaffected evidence. Stop once the assigned acceptance criteria are evidenced; report concrete missing context instead of over-analyzing settled work.
+
     ## Your job
 
     1. Implement exactly what this brief specifies (prior tasks are done)
-    2. Run tests; commit on Working branch
-    3. Write report file; return short summary only
+    2. Run only assigned affected unit tests or applicable scoped-check evidence; use file-handoffs.md § Verification evidence and retain unaffected prior evidence. When this task's Assignment names a PM-fixed capture request, capture the authorized check once with `mstar sdd evidence capture --request <absolute-task-request.json> -- <executable> [args...]` and cite the retained run's record/raw logs
+    3. Commit on Working branch
+    4. Write report file with actual evidence; return short summary only
 
     ## When stuck
 

package/harness-skills/mstar-sdd/references/implementer-prompt.md

@@ -26,10 +26,10 @@ Dispatch:
 
     - Control harness root (briefs/reports/diffs live here): [CONTROL_ROOT]
     - Feature worktree — cwd for all source edits, branch [WORKING_BRANCH]: [FEATURE_CWD]
-    - Plan: [PLAN_FILE] — Context file: [CONTEXT_FILE]
+    - Plan: [PLAN_FILE] — PM coordination context: [CONTEXT_FILE] (never use it to select your checkout)
     - Brief: [BRIEF_FILE] — Report: [REPORT_FILE]
     - First step: observe `pwd` and the checked-out branch; on mismatch with [FEATURE_CWD]/[WORKING_BRANCH], stop and report BLOCKED — do not write. A declared-correct assignment does not make a wrong-checkout write safe.
-    - These destinations bind the handoff, not the host: a later deliberate `chdir`, absolute-path write outside [FEATURE_CWD], or host-native edit tool (apply_patch) is NOT blocked. CLI-launchable children are started via `mstar sdd exec --context [CONTEXT_FILE] -- <argv>` (starting cwd = feature worktree).
+    - These destinations bind the handoff, not the host: a later deliberate `chdir`, absolute-path write outside [FEATURE_CWD], or host-native edit tool (apply_patch) is NOT blocked. Execute allowed commands directly with the tool workdir fixed to the verified [FEATURE_CWD] / [WORKING_BRANCH]. Hosted leaves must not invoke `mstar sdd exec --context` or resolve cwd from mutable shared context; that entry is reserved for PM serialized CLI launch (file-handoffs.md § Bound child launch).
 
     ## Context not in the brief
 
@@ -41,14 +41,18 @@ Dispatch:
 
     ## Before you begin
 
-    Ask questions now about requirements, approach, or dependencies.
+    Read the supplied brief and relevant inputs. Ask only about a concrete missing prerequisite that prevents this task; do not reopen settled choices.
+
+    ## Scope and stop
+
+    Use only the brief's owned files, relevant inputs and named checks. Do not restart global exploration, extend the task, or run local full suites without the user's explicit scoped permission. Reuse unaffected evidence. Stop once the assigned acceptance criteria are evidenced; report concrete missing context instead of over-analyzing settled work.
 
     ## Your job
 
     1. Implement exactly what the brief specifies
-    2. Run tests (TDD if brief requires)
+    2. Run only the assigned affected unit tests; for non-executable docs/policy, use real scoped-check evidence per file-handoffs.md § Verification evidence. When the Assignment names a PM-fixed capture request, capture the authorized check once with `mstar sdd evidence capture --request <absolute-task-request.json> -- <executable> [args...]` and cite the retained run's record/raw logs (same section) instead of ad-hoc reruns
     3. Commit on Working branch
-    4. Self-review
+    4. Self-review only the task diff and directly affected contracts
     5. Write report file; return short summary only
 
     ## When stuck
@@ -59,7 +63,8 @@ Dispatch:
 
     - Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
     - Implemented / attempted
-    - Tests: command, output, red/green evidence if TDD
+    - Verification: affected test files, command, actual output (red/green for executable bug fixes), OR the complete scoped-check block from file-handoffs.md for non-executable docs/policy
+    - Reused evidence: original range and reason it remains applicable
     - Files changed
     - Self-review notes
 ```

package/harness-skills/mstar-sdd/references/sticky-implementer-session.md

@@ -4,14 +4,16 @@ Reuse the **same implementer subagent** across multiple tasks in one plan when t
 
 SSOT for mode selection and host resume → this file. Per-task artifacts → **`file-handoffs.md`**.
 
+**Parallel ready tasks use fresh sessions and task-specific artifact paths inside one canonical per-plan SDD root** (`mstar-sdd` § Ready-task scheduling). Never resume the same session concurrently or share its ledger between tracks; PM alone updates shared context/progress; parallel leaves consume immutable absolute artifact paths, not shared-context helpers.
+
 ## When to use
 
 | `SDD implementer session` | Use |
 |---------------------------|-----|
 | **`fresh`** (default) | Independent tasks, module boundaries, different dev tracks, or first task on a plan |
-| **`sticky`** | Same `fullstack-dev` (or same role id), sequential tasks on one branch, strong file/context continuity (e.g. T3+T4 daemon stderr + DB reset) |
+| **`sticky`** | One sequential dependency chain on one owner track; same `fullstack-dev` (or same role id), sequential tasks on one branch, strong file/context continuity (e.g. T3+T4 daemon stderr + DB reset) |
 
-**Prefer `sticky`** on iteration Phase 2 Autonomous Execute when PM will dispatch many tasks to the same dev on one plan feature branch.
+**Prefer `sticky`** only within a sequential dependency chain with strong context continuity; independent ready tasks remain fresh and concurrent.
 
 ## Assignment fields (implement dispatch)
 

package/harness-skills/mstar-sdd/references/task-reviewer-prompt.md

@@ -12,7 +12,7 @@ Dispatch:
     <SUBAGENT-STOP> Skip PM orchestration. Read-only review.</SUBAGENT-STOP>
 
     Review one task implementation: spec compliance first, then quality.
-    Task-scoped gate — plan-level QC comes later on the whole branch.
+    Task-scoped gate — later plan QC checks changed interfaces across tasks, reusing this report.
 
     ## What was requested
 
@@ -39,8 +39,12 @@ Dispatch:
     Diff file: [DIFF_FILE]
 
     Read the diff file once. Do not re-run git. Do not mutate checkout.
-    Do not re-run full test suite — trust implementer evidence unless a
-    specific doubt needs one focused test.
+    Review only the assigned task diff and directly affected interfaces.
+    No repository-wide exploration or full test suite. Reuse relevant
+    implementer evidence; a specific doubt permits only the assigned focused
+    unit check. Non-executable docs/policy may use scoped-check evidence;
+    verify its applicability against the diff, never invent a test obligation.
+    Stop once the assigned acceptance questions are answered.
 
     ## Output
 
@@ -57,4 +61,4 @@ Dispatch:
     **Task quality:** Approved | Needs fixes
 ```
 
-Re-review after fixes covers both verdicts. PM resolves all ⚠️ items before marking task complete.
+Re-review after fixes checks both verdicts only for the raised findings and fix delta; unchanged evidence remains reusable. PM resolves all ⚠️ items before marking task complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/dsh",
-  "version": "3.8.2",
+  "version": "3.9.0",
   "description": "Morning Star harness dsh (DeepSeek Harness) cordis function plugin — in-process engine gates (status/dispatch/lease) with hard refusal channels.",
   "keywords": [
     "dsh",