@mstar-harness/opencode 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/dist/mstar.js +1 -1
  3. package/harness-commands/codebase-audit.md +2 -2
  4. package/harness-skills/mstar-audit/SKILL.md +20 -0
  5. package/harness-skills/mstar-audit/references/audit-playbook.md +27 -0
  6. package/harness-skills/mstar-branch-worktree/SKILL.md +7 -0
  7. package/harness-skills/mstar-coding-behavior/SKILL.md +5 -0
  8. package/harness-skills/mstar-compound/references/compound-workflow.md +16 -0
  9. package/harness-skills/mstar-compound-refresh/SKILL.md +5 -0
  10. package/harness-skills/mstar-iteration/references/phase-4-5-pr-delivery.md +1 -0
  11. package/harness-skills/mstar-plan-artifacts/SKILL.md +1 -0
  12. package/harness-skills/mstar-plan-artifacts/references/status-and-residuals.md +8 -0
  13. package/harness-skills/mstar-review-qc/SKILL.md +6 -0
  14. package/harness-skills/mstar-roles/references/project-manager/qc-and-residuals.md +2 -1
  15. package/harness-skills/mstar-roles/references/qc-specialist/deep-review-lenses.md +16 -7
  16. package/harness-skills/mstar-roles/references/qc-specialist/report-template.md +17 -1
  17. package/harness-skills/mstar-roles/references/qc-specialist-shared.md +3 -1
  18. package/harness-skills/mstar-roles/references/writing-specialist.md +33 -0
  19. package/harness-skills/mstar-sdd/SKILL.md +5 -1
  20. package/harness-skills/mstar-sdd/references/file-handoffs.md +2 -0
  21. package/harness-skills/mstar-skill-authoring/SKILL.md +4 -2
  22. package/harness-skills/mstar-skill-authoring/references/regression-fixation.md +46 -0
  23. package/harness-skills/mstar-skill-authoring/references/skillsbench-authoring.md +37 -0
  24. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -6,6 +6,16 @@ The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface re
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [2.3.0] - 2026-08-16
10
+
11
+ ### Harness
12
+
13
+ - Internal `@mstar-harness/engine` devDependencies in cli/opencode/dsh now use the `workspace:*` protocol; the release-prep engine-spec sync step was removed.
14
+
15
+ - Version alignment with harness **2.3.0** (no OpenCode package API change).
16
+
17
+ See root [CHANGELOG.md](../../CHANGELOG.md) **2.3.0**.
18
+
9
19
  ## [2.2.0] - 2026-08-13
10
20
 
11
21
  ### Bundled harness skills (`harness-skills/` at publish)
package/dist/mstar.js CHANGED
@@ -195,7 +195,7 @@ function parseAssignmentBranchForms(assignmentText) {
195
195
  if (fields.branchPolicy !== undefined && fields.branchPolicy !== "") {
196
196
  const direct = fields.branchPolicy.match(/^direct\s+on\s+(\S+)/i);
197
197
  if (direct) {
198
- const strict = fields.branchPolicy.match(/^direct\s+on\s+(\S+)(?:\s*(?:[—–]|--|-)\s*(.+))?$/);
198
+ const strict = fields.branchPolicy.match(/^direct\s+on\s+(\S+)(?:\s*(?:[\u2014\u2013]|--|-)\s*(.+))?$/);
199
199
  forms.directOn = { branch: direct[1].trim(), reason: strict ? (strict[2] ?? "").trim() : "" };
200
200
  }
201
201
  }
@@ -2,7 +2,7 @@
2
2
  name: codebase-audit
3
3
  description: Survey a codebase as a senior advisor and produce prioritized, self-contained improvement plans. Read-only on source code. Use standalone before iteration-start to discover what's worth doing, or independently to build a prioritized backlog.
4
4
  agent: project-manager
5
- input: "[no args]"
5
+ input: "[simplify]"
6
6
  ---
7
7
 
8
8
  # Audit Codebase
@@ -33,7 +33,7 @@ The audit is **advisory** — it does not enter the per-plan state machine (`Tod
33
33
 
34
34
  ## Execute
35
35
 
36
- Execute **`mstar-audit`** end to end(SKILL.md:Recon → Audit → Vet & prioritize → Write plans;effort `quick` / `standard` / `deep`;scope variants `security` / `perf` / `tests` / `branch` / `next` / `roadmap`)。Plans → `{PLAN_DIR}/audit-<YYYY-MM-DD>/NNN-<slug>.md` + `README.md` index,per **`mstar-plan-artifacts/references/plan-quality-bar.md`**。
36
+ Execute **`mstar-audit`** end to end(SKILL.md:Recon → Audit → Vet & prioritize → Write plans;effort `quick` / `standard` / `deep`;scope variants `security` / `perf` / `tests` / `branch` / `next` / `roadmap` / `simplify`)。Plans → `{PLAN_DIR}/audit-<YYYY-MM-DD>/NNN-<slug>.md` + `README.md` index,per **`mstar-plan-artifacts/references/plan-quality-bar.md`**。
37
37
 
38
38
  Executor: PM dispatches `@code-reviewer`;大型仓库 scout 扇出经 Assignment `Delegation: allowed (scout/explore only, read-only)`(Routing 表)。
39
39
 
@@ -70,6 +70,21 @@ Every finding follows **`references/finding-format.md`** — read it before the
70
70
 
71
71
  ### Phase 3 — Vet, prioritize, confirm
72
72
 
73
+ **Attack before vet — claims must survive an adversarial pass first.** Take the top candidate findings (by leverage; scale the count to finding volume — attack the whole table when small, the head when large) and run a three-way attack on each:
74
+
75
+ 1. **Counter-example** — find a boundary case that makes the claim not hold.
76
+ 2. **Simpler explanation** — does a simpler explanation cover the same evidence?
77
+ 3. **Evidence verifiability** — open the cited `file:line` and check it actually supports the claim.
78
+
79
+ Dispose per the five-state rule (single-pass version — the four dispositions below implement the survey's five-state semantics: uncovered-keep == 未提及保留; never-drop == 全空/null 回流):
80
+
81
+ - **Survived** — passes to vet unchanged.
82
+ - **Refuted** — drop, and record in the index's "considered and rejected" section: `- <finding>: not worth doing because <one line>`.
83
+ - **Hallucinated** — the attack surfaced a claim never in the original finding set: discard it and log a red-team record line in the index (never into the findings table; it does not occupy a "considered and rejected" slot — it was never a finding). Disambiguation: hallucinated = a claim the attack itself produced; fabricated/unsupported evidence inside the original finding goes to **Refuted** via the evidence-verifiability axis, not to Hallucinated.
84
+ - **Uncovered** — the attack did not reach a finding: treat as unreviewed and keep for vet. Never drop a finding just because the attack missed it.
85
+
86
+ Where the attack step decides whether a claim stands on its face, vet below confirms the code itself — opening cited files and disposing by-design / mis-attribution / duplicate cases; survived findings hand to vet below.
87
+
73
88
  **Vet before presenting — subagents over-report.** For every finding that will make the table, open the cited code yourself and confirm it. Three failure classes to expect:
74
89
 
75
90
  1. **By-design behavior** reported as a bug or vulnerability (e.g. honoring `https_proxy` flagged as SSRF — standard proxy convention; or a tradeoff explicitly recorded in an ADR).
@@ -112,6 +127,7 @@ If an audit directory from a previous run exists, **reconcile, don't duplicate**
112
127
  | Category focus (`security`, `perf`, `tests`, ...) | Recon, then that category only, then plan | Useful for targeted sweeps |
113
128
  | `branch` | Current branch changes only | Files changed since merge-base with default branch + their direct importers. Tag every finding `introduced` or `pre-existing` |
114
129
  | `next` / `roadmap` | Direction category only, in depth | 4–6 grounded suggestions; selected ones become design/spike plans |
130
+ | `simplify` | DEBT-focused deep pass: dead / duplicated / speculative / over-built / added-then-removed / hand-rolled-where-a-dependency-exists surfaces | Prove-or-reject per playbook §5; findings use Category DEBT; tiny-real items → "considered and rejected" rows, never inline TODOs (Hard Rule 1) |
115
131
 
116
132
  ## Output format
117
133
 
@@ -138,6 +154,10 @@ If an audit directory from a previous run exists, **reconcile, don't duplicate**
138
154
  ## Findings considered and rejected
139
155
 
140
156
  - <finding>: not worth doing because <one line>.
157
+
158
+ ## Red-team dispositions
159
+
160
+ - <finding>: <survived / refuted / hallucination-dropped / uncovered-kept>, <one-line reason>
141
161
  ```
142
162
 
143
163
  Status values: `TODO` | `IN PROGRESS` | `DONE` | `BLOCKED` | `REJECTED`
@@ -18,6 +18,8 @@ The highest-trust category — real bugs found by reading, not speculation.
18
18
  - Concurrency: check-then-act on shared resources, missing transactions around multi-write operations, idempotency of retried operations (webhooks, queues).
19
19
  - Type escape hatches: `any` / `as` casts / `@ts-ignore` clusters — each one is a place the compiler was overruled.
20
20
  - Resource leaks: unclosed handles, connections, subscriptions; missing `finally`.
21
+ - Derived-state drift: every cache, replay, projection, denormalized copy, or UI echo must trace to an authoritative source and an invalidation point; flag retained state with neither.
22
+ - Bounds covering the final operation: who owns the complete emitted/retained result (wrappers and metadata included)? Probe tiny/exact limits, oversized single chunks, and multibyte text against byte limits.
21
23
 
22
24
  ## 2. Security
23
25
 
@@ -34,6 +36,7 @@ Review only what is directly supported by code evidence. Keep findings framed as
34
36
  - Dependency posture: run the ecosystem's audit command (`npm audit`, `pip-audit`, `cargo audit`) in read-only mode. Report only critical/high advisories that affect reachable runtime code.
35
37
  - Production configuration: overly broad CORS where credentials are allowed, missing response-hardening headers (e.g. CSP), cookies missing appropriate `HttpOnly`/`Secure`/`SameSite` attributes, debug/verbose behavior enabled in production.
36
38
  - Data minimization: PII or sensitive operational data in logs, stack traces returned to clients, internal error details exposed through API responses.
39
+ - Enforcement bypass: for every validation/rejection point, look for alternate callers that route around it — direct calls, wrappers, facades, schema-less paths, listener ordering.
37
40
 
38
41
  ## 3. Performance
39
42
 
@@ -56,6 +59,9 @@ The goal is not a percentage — it's *which untested code is dangerous*.
56
59
  - Existing test quality: tests that assert nothing meaningful, heavy mocking that tests the mocks, snapshot tests nobody reads, flaky patterns (real timers, real network, order dependence).
57
60
  - Missing test layers: unit-only suites with zero integration coverage on API boundaries, or the inverse.
58
61
  - Verification infrastructure: is there a one-command way to know the codebase works? If not, that's finding #1 and a prerequisite plan for any risky change.
62
+ - Real entry path: do tests exercise the shipped entry (CLI, loader, plugin boot) rather than a hand-mounted equivalent?
63
+ - Externally observable state: assertions verify logs, events, files, exit codes — never implementation restatement or agent-reported success.
64
+ - User-visible output is behavior (conditional): in repos shipping UI copy, CLI output, API error shapes, or prompt text, wording is behavior — snapshot or e2e coverage should pin it.
59
65
 
60
66
  ## 5. Tech Debt & Architecture
61
67
 
@@ -65,6 +71,27 @@ The goal is not a percentage — it's *which untested code is dangerous*.
65
71
  - God objects/modules: files an order of magnitude larger than the repo median that everything touches; functions with double-digit parameters or deep conditional nesting.
66
72
  - Inconsistent patterns: three ways of doing data fetching / error handling / styling — pick the winner (the one the team converged on most recently) and plan the consolidation.
67
73
  - Abstraction mismatches: premature abstractions with a single implementation, or missing abstractions where the same change always requires touching N files in lockstep.
74
+ - Public-but-one-caller: a public method on a generic service with a single internal caller is a private-capability closure candidate.
75
+ - Unjustified defaults/public options: flag defaults or public operations/formats with no current-consumer evidence or prior art.
76
+
77
+ ### Prove-or-reject before reporting DEBT (`simplify` scope)
78
+
79
+ **Prove before reporting dead code.** Classify consumers first — production corpus / tests-docs-only / ambiguous (examples, scripts: inspect, don't assume). Grep the exact symbol, plus event/field/config names, both quoted and bare. Read the call sites — a grep hit is a lead, not a verdict. "Tests are the only consumer" is a finding-enabler when the pinned behavior is non-load-bearing; "an invariant/test existing only to protect an unused API" is itself the signal.
80
+
81
+ **Hand-rolled vs dependency swap bar.** Name the exact surface the package covers — residual semantics count against the swap. Health-check the dependency honestly. A recorded decision (ADR/knowledge doc) beats the swap claim — re-litigating a settled tradeoff needs new evidence. Weigh net deletion: implementation + dedicated tests + docs − remaining glue. A wrapper that relocates the same complexity is not a win.
82
+
83
+ **Mirrored-fact test.** When several mechanisms track the same liveness/settlement fact, propose one controller — but preserve machinery protecting publication, rollback, callback containment, and first-terminal arbitration.
84
+
85
+ **Strong-candidate families** (one line per family):
86
+ - Symbols with no production consumer.
87
+ - Tests/docs-only consumers pinning non-load-bearing behavior.
88
+ - Two representations mirroring the same fact.
89
+ - Seam methods fully implemented for support but with zero consumption.
90
+ - Speculative product generality.
91
+ - Invariants/rollbacks/expected-outputs existing only to protect an unused API.
92
+ - Hand-rolled where a dependency exists.
93
+
94
+ **Guards.** A production caller exists → feature decision, not cleanup (reject). A recorded seam/ADR rationale → new evidence must beat it. Tiny-but-real items → "considered and rejected" rows in the index, never inline TODOs (Hard Rule 1).
68
95
 
69
96
  ## 6. Dependencies & Migrations
70
97
 
@@ -217,3 +217,10 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
217
217
  - 若 **QA 与同仓其他可写角色并发**提交测试代码,仍须遵守上文「同仓并发写入」**worktree** 规则(可为 QA 单开一条写入 worktree,**同一 `Working branch`**,由 PM 在 Assignment 写明)。
218
218
 
219
219
  派发前清单与常见反模式 → **`references/parallel-writable-pre-dispatch.md`**。
220
+
221
+ ## History rewrite 与推送安全
222
+
223
+ - 已推送分支的任何 history rewrite:先 `git fetch` 记录远端**精确 OID**,发布用 `--force-with-lease=<branch>:<observed-oid>`;**禁止**裸 `--force`。
224
+ - Rewrite 推送后:重新 fetch heads;rewrite 前的 review threads / approvals / check 结果**不再是当前证据** — merge 结论前须重审(commit hash 与 inline-comment anchor 已失效)。
225
+ - 证据最窄原则(audit / QA Assignment 场景):选择会在目标回归上失败的**最窄**检查;不因「push 在即」重跑已通过的检查。
226
+ - 本节只管 rewrite / lease / 证据失效面;CI / review 波次 push 门禁(时序)SSOT → `mstar-iteration` §5.1a。
@@ -92,6 +92,11 @@ When something does not work, investigate; do not guess.
92
92
  - **Run existing tests before and after changes.** If they passed before and fail after, you broke something. If they were already failing, say so.
93
93
  - **If stuck, say so.** "I tried X and Y; neither worked. I'm seeing Z. I think it might be W but am not sure" is infinitely more useful than silently trying random things for 20 iterations.
94
94
 
95
+ **Dataflow-directed diagnosis — how to locate, verify, and falsify** (for where to fix, see Surgical Changes · bug=root-cause; for the pre-fix repro test, see the bullets above):
96
+ - **Map the data flow before judging.** Trace input → processing → storage → output, noting who writes and who reads at each step. A bug is a state deviation from expectation at some point in that flow (expected state vs observed state) — locate it from the data, not by static code reading.
97
+ - **Four verifiable cross-checks.** Every hypothesis must be cross-checkable: re-run the repro / log comparison / input-output comparison / dual-path comparison. A hypothesis that cannot be verified on the spot is not a conclusion.
98
+ - **Falsify the fix.** After the fix, re-run the original repro and compare output with expectation. If the problem did not disappear, the root cause was wrong — report "verification failed" explicitly; never pretend success.
99
+
95
100
  ## 5) Goal-Driven Execution
96
101
 
97
102
  Convert vague requests into verifiable outcomes and iterate until verified. Define concrete success criteria before major edits; use brief `Step -> verify` checkpoints for multi-step tasks; for split delivery, maintain a durable roadmap (current slice, later slices, dependencies, owner/trigger, completion condition); prefer evidence-backed completion (tests, command output, reproducible checks). If verification fails, loop on diagnosis and fix before declaring completion. Do not finish with "next plan / later / follow-up" only in prose — remaining work must be written to the plan/status artifact or the task reports `Partial` / `Blocked`.
@@ -113,6 +113,22 @@ After writing, validate the YAML frontmatter:
113
113
  - `date` is YYYY-MM-DD format
114
114
  - Array fields use `[item1, item2]` syntax
115
115
 
116
+ ### 3.5 知识文档质量门:HEAD-resolvability & prose hygiene
117
+
118
+ 写作完成、进入 Phase 4 前,对文档运行本质量门(writing-specialist 编辑 durable harness artifacts 时适用同一 rubric — 见 `mstar-roles/references/writing-specialist.md` Output Guidance 指针):
119
+
120
+ - **The one test**:读者在 HEAD(无 chat transcript / dispatch prompt / 未合并草稿访问权)能否解析每个引用并验证每个声明?
121
+ - **mstar 泄漏分类**(vantage 来自 authoring session 而非仓库现状;修剪或重述):
122
+ - dead session citations:chat-only decision 序号 → 引 plan/knowledge/roadmap 属主路径,或独立重述事实
123
+ - durable docs 中的 change narration:knowledge/roadmap/README 陈述现状;已修回归 → counterfactual-present(「without X, Y happens」)
124
+ - review choreography:谁在哪轮确认 → 平实事实;finding id 留在 review bundle(其 sanctioned genre)
125
+ - reviewer-addressed justification(向评审自辩的措辞)
126
+ - control-flow narration(过程/控制流叙述)
127
+ - hedges without markers → 既有 `simplify:` / `temporary` 标记约定(`mstar-coding-behavior`;引用不重复)
128
+ - authoring-language slips:双语对之外的 zh/en 混杂
129
+ - **Keep 规则(mstar-sanctioned)**:review bundle / QC report 内的 R# 与 finding id(durable 文档引用 QC 证据的 sanctioned pattern 是经 review bundle 路径引用:finding id 留在 bundle 内,durable 文档只引用 bundle 路径本身);issue 引用;带 provenance 词的 measured bounds;runtime old/new 生命周期态;Alternatives-considered genre 节;HEAD 持久工件中的 iteration/plan id
130
+ - **过度修正陷阱**:义务↛背书翻转;hypothetical 保持标记;共享一句时删子句不删句。「修剪前枚举命题」→ complete-proposition rule(`mstar-roles/references/writing-specialist.md` Output Guidance — SSOT,不在本节重述)
131
+
116
132
  ## Phase 4: Discoverability check
117
133
 
118
134
  Check whether the project's `AGENTS.md` or `CLAUDE.md` would lead a future agent to discover `{KNOWLEDGE_DIR}`.
@@ -50,6 +50,9 @@ For each candidate document, classify into one of five outcomes:
50
50
  | **Replace** | Old doc is misleading; known better replacement exists | Create trustworthy successor, then delete old |
51
51
  | **Delete** | No longer useful, applicable, or distinct | Delete — git history preserves it |
52
52
 
53
+ > **Guardrail — rejected approaches:** a captured rejected approach stays only while the losing idea remains a tempting, meaningful mistake; delete it once obsolete or no longer plausible.
54
+ > **Calibration:** first real run of this axis — 9 size-divergent knowledge docs (36–78 lines) under `{KNOWLEDGE_DIR}/architecture-patterns/` classified at fold time, all kept by future value (evidence: `.mstar/plans/20260815-mstar-knowledge-prose-folds.md` `## Review Gate Summary` → Task evidence); length proved not to be a criterion.
55
+
53
56
  ## Core rules
54
57
 
55
58
  1. **Evidence over opinion.** Signals are inputs, not a scorecard. Use engineering judgment.
@@ -58,6 +61,7 @@ For each candidate document, classify into one of five outcomes:
58
61
  4. **Be decisive.** When evidence is clear (file renamed, class moved), apply. Only ask PM when genuinely ambiguous.
59
62
  5. **Avoid low-value churn.** Don't edit for typos, polish, or cosmetic changes that don't improve accuracy.
60
63
  6. **Delete, don't archive** — **except** formal **iteration-start** §1.6 corpus hygiene (`mstar-iteration/references/iteration-corpus-hygiene.md`), which **moves** superseded/redundant knowledge/specs to `{HARNESS_DIR}/archived/knowledge|specs/`. Outside that gate, git history is the archive; `git log --diff-filter=D -- <path>` finds deleted docs.
64
+ > **Not adopted:** frozen-archive seal machinery, `Archived:` triplets, or a verifier — they contradict rule 6 (delete, don't archive; git history is the archive); do not reintroduce.
61
65
  7. **Evaluate document-set design.** Check whether two+ docs overlap and should be consolidated. Redundant docs silently drift apart.
62
66
 
63
67
  ## Scope selection
@@ -92,6 +96,7 @@ For each doc, check:
92
96
  2. **Referenced conventions still match?** — check against current `AGENTS.md`, `CONCEPTS.md`, lint configs.
93
97
  3. **Solution still the recommended approach?** — has a newer pattern superseded it?
94
98
  4. **Overlap with other docs?** — search for same module/tags to find duplicates.
99
+ 5. **Future decision value?** — rationale / alternatives considered / negative guarantees / reintroduction conditions that would still guide a future change → **Keep, regardless of length**. A completed decision whose body has no future leverage left (one-off fix detail, superseded mechanics) enters the Delete candidate pool. Word count and age remain discovery aids, never criteria.
95
100
 
96
101
  ### Phase 3: Classify and act
97
102
 
@@ -48,6 +48,7 @@
48
48
  **顺序记忆**:`observe findings → fix locally early → wait until CI + review wave idle → push batch → wait new wave → repeat`。
49
49
 
50
50
  > **Engine check (when available):** run `mstar iteration push-cadence [--ci-running] [--review-wave]` (or `import { pushCadenceProbe } from "@mstar-harness/engine"` in a host hook) to probe the push gate above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
51
+ History rewrite / force-with-lease / 改写后证据失效规则 SSOT → `mstar-branch-worktree`「History rewrite 与推送安全」节;本节只管 push 时序。
51
52
 
52
53
  ### 5.1 Loop(repeat until §5.5 exit)
53
54
 
@@ -28,6 +28,7 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
28
28
 
29
29
  > **Engine check (when available):** run `mstar status validate <path>` (or `import { validateStatus } from "@mstar-harness/engine"` in a host hook). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
30
30
 
31
+ - **Fail-loud handoff**: findings must pass `validateResidual` (per entry) / `validateStatus` (whole file) before registration; malformed → reject + rewrite → **`references/status-and-residuals.md`** (“Fail-loud handoff contract”).
31
32
  - **Lifecycle**: open → verified close → **`archived/residuals/<plan-id>.json`**; machine **`severity`** enum in reference.
32
33
 
33
34
  > **Engine check (when available):** run `mstar status archive-residuals <plan-id>` (or `import { archiveResiduals } from "@mstar-harness/engine"` in a host hook). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
@@ -59,6 +59,14 @@ Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md**
59
59
 
60
60
  **Open `detail_doc` (optional):** repo-relative path under **`{PLAN_DIR}/residuals/<plan-id>/`** matching **`id`** (e.g. `R1`); omit if prose layer unused (`knowledge-and-designs.md`).
61
61
 
62
+ ## Fail-loud handoff contract
63
+
64
+ Findings must pass engine validation **before** registration into `residual_findings`: `validateResidual(entry)` per entry, `validateStatus(doc)` for the whole file (`mstar status validate` / engine import). Malformed entries — **non-object**, missing any of the nine required fields (`id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`, `target`, `tracking` — mirroring engine `RESIDUAL_REQUIRED_FIELDS` in `packages/engine/src/status.ts`), or **severity** outside the enum — are **rejected** (`ok:false` + violation): fix and rewrite — never silent pass-through, downgrade-write, or “write then patch”.
65
+
66
+ dsh-derived findings map their keys per the engine-residual validation verification spec §5; dsh keys never enter the schema.
67
+
68
+ ---
69
+
62
70
  ## Residual findings: `severity` (SSOT, machine field)
63
71
 
64
72
  Each `residual_findings[<plan-id>][]` entry’s **`severity`** must be from this enum (legacy read paths → **`jq` examples** at end). QC report Markdown **Critical / Warning / Suggestion** are **section titles** — **do not** copy them verbatim into JSON `severity`.
@@ -53,6 +53,12 @@ description: "Morning Star QC orchestration — **SDD mandatory plan QC tri-revi
53
53
 
54
54
  Leaf reviewers apply verdict per **`mstar-roles/references/qc-specialist/report-template.md`**. PM **`{SDD_DIR}/review/qc-consolidated.md`** synthesizes tri (or single-seat `qc.md`) into one gate decision for implement fix waves and QA gate, then records the durable summary in the main plan/status artifacts.
55
55
 
56
+ ### 覆盖语义(未提及 = 未审查)
57
+
58
+ - **未提及 = 未审查**:某 finding / severity 项 / 声明未被任何席位报告提及 → 不得在汇总中标记为已解决或通过;如实标注 `unreviewed`,按需转 targeted re-review 或补充席位。
59
+ - **汇总层零注入**:consolidated 中每条发现可溯源到某 `qcN.md`;PM 不得在汇总层引入席位报告之外的新声明(PM 自身观察走独立 Status Update,不混入 gate 决策输入)。
60
+ - **Unconfirmed 传导**:任一席位 verdict = `Unconfirmed`(`report-template.md` 定义的证据通道失败态)→ gate 决策不得为 `Approve`——先补证据(重发 review-package / 修 diff 基线)再收敛;受影响席位走既有 targeted re-review 机制(同 `qcN.md` `## Revalidation` 原位更新 verdict),不新增 re-review 形态、不改 N 规则。
61
+
56
62
  ## 证据规则(PM · consolidated 输入)
57
63
 
58
64
  - Critical 发现须含触发条件、影响范围、修复建议。
@@ -47,7 +47,7 @@ Use this reference when PM is dispatching QC, consolidating review verdicts, or
47
47
  ```markdown
48
48
  ## QC Consolidated Decision
49
49
 
50
- **Decision**: Approve | Request Changes | Needs Discussion
50
+ **Decision**: Approve | Request Changes | Needs Discussion | Unconfirmed
51
51
  **Blocking Items**: {list or None}
52
52
  **Residual Findings**: {list with owner/target date, or None}
53
53
  **Assigned Fix Owners**: {role list}
@@ -56,6 +56,7 @@ Use this reference when PM is dispatching QC, consolidating review verdicts, or
56
56
 
57
57
  ## Quick Decision Rules
58
58
 
59
+ - Any seat `Unconfirmed` (evidence-channel failure) -> Decision: `Unconfirmed` (supplement evidence, then re-converge); never falls through to `Approve`
59
60
  - Any unresolved `Critical` -> `Request Changes`
60
61
  - No `Critical`, but unresolved high-impact warning with disagreement -> `Needs Discussion`
61
62
  - Otherwise -> `Approve`
@@ -33,8 +33,8 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
33
33
  | Reviewer | 默认透镜 |
34
34
  |----------|---------|
35
35
  | QC1 (architecture/maintainability) | **Modularity Lens** + **Contract Lens** |
36
- | QC2 (security/correctness) | **Security Lens** + **Correctness Lens** |
37
- | QC3 (performance/reliability) | **Performance Lens** + **Reliability Lens** |
36
+ | QC2 (security/correctness) | **Security Lens** + **Correctness Lens** + **Bounds Lens** + **Real-Entry-Path Lens** |
37
+ | QC3 (performance/reliability) | **Performance Lens** + **Reliability Lens** + **Enforcement-Path Lens** + **Ownership / Derived-State Lens** |
38
38
 
39
39
  ### 按信号追加透镜
40
40
 
@@ -47,22 +47,27 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
47
47
 
48
48
  ---
49
49
 
50
- ## 透镜清单(每透镜一行焦点;详细追问由 reviewer 按专业判断展开)
50
+ ## 透镜清单(每透镜一行焦点;详细追问由 reviewer 按专业判断展开;新增透镜各附 ≤4 条结构化追问,均可由 diff/read/grep 回答)
51
51
 
52
52
  每个透镜是一组审查焦点。QC reviewer 在报告中按透镜分节列出发现,每个发现标注来自哪个透镜(`Source Type: deep-lens: <Lens>`)。
53
53
 
54
54
  - **Modularity Lens** — 新依赖方向合理;无逻辑错放层级(controller 业务逻辑、model 视图逻辑);公共接口职责单一边界清晰;无循环依赖/隐含耦合。
55
- - **Contract Lens** — 公共 API/接口签名无未声明 breaking change(有则 plan 声明 + 迁移说明);新端点遵循命名/参数约定;返回类型稳定(新字段不破坏已有解析)。
56
- - **Security Lens** — 认证/授权/session/token/permission 逻辑正确;未验证输入未直入 DB/命令/文件;敏感数据(密钥/token/PII)未在日志/错误/返回值泄露;新访问控制点覆盖所有调用路径。
55
+ - **Contract Lens** — 公共 API/接口签名无未声明 breaking change(有则 plan 声明 + 迁移说明);新端点遵循命名/参数约定;返回类型稳定(新字段不破坏已有解析);docs-match-code:config/defaults/errors/wire fields/events 变更同 diff 更新 README/JSDoc;双语仓对照同步。
56
+ - **Security Lens** — 认证/授权/session/token/permission 逻辑正确;未验证输入未直入 DB/命令/文件;敏感数据(密钥/token/PII)未在日志/错误/返回值泄露;新访问控制点覆盖所有调用路径。(与 **Enforcement-Path Lens** 互指:访问控制点自身的正确性归本透镜;拒绝/校验路径的执行与旁路追迹归 Enforcement-Path)
57
57
  - **Correctness Lens** — 错误处理显式可恢复(无吞关键异常的 catch-all);边界条件覆盖(空/零/溢出/并发);状态转换一致(无外部可观察中间态);返回值/副作用与声明一致。
58
58
  - **Performance Lens** — 无 N+1 查询(ORM eager loading);循环/批处理无无界操作;新索引必要且不退化写入;大对象/列表分页或流式。
59
- - **Reliability Lens** — 资源(连接/句柄/锁)异常路径也释放;外部调用有超时+重试;缓存失效正确(不长期返回过期);无可能无限增长的结构(无界缓存/日志/队列)。
59
+ - **Reliability Lens** — 资源(连接/句柄/锁)异常路径也释放;外部调用有超时+重试;缓存失效正确(不长期返回过期);无可能无限增长的结构(无界缓存/日志/队列)。(与 **Lifecycle & Concurrency Lens** 互指:资源释放/超时重试/缓存失效归本透镜;对象生命周期与并发时序(发布竞态/取消/重入/清理完整性)归 Lifecycle & Concurrency)
60
60
  - **Auth Lens** — 认证中间件覆盖所有新端点;权限检查在业务逻辑前(先鉴权再操作);session 生命周期正确(创建/续期/失效);权限提升路径需二次确认。
61
61
  - **Input Validation Lens** — 外部输入(query/body/headers)经类型/范围/格式验证;无可触发路径遍历/注入/XSS;文件上传有大小/类型检查;错误信息不暴露内部实现细节。
62
62
  - **Data Migration Lens** — migration 可回滚(`down` 存在且正确);大表用非阻塞策略;数据一致(不丢/无脏中间态);并发写入下安全。
63
63
  - **Error Handling Lens** — 异常层级清晰(业务 vs 系统);面向用户错误消息安全;关键操作失败副作用正确处理(事务回滚/补偿);无"静默失败"路径。
64
64
  - **Standards Lens** — 风格/命名/文件组织符项目约定;无与现有冲突的重复实现;新依赖有充分理由;遵循项目 `AGENTS.md` 维护契约。
65
- - **Testing Lens** — 关键逻辑路径有覆盖;边界/异常路径覆盖;无仅 happy-path 跳 failure-mode;集成测试覆盖外部服务交互边界。
65
+ - **Testing Lens** — 关键逻辑路径有覆盖;边界/异常路径覆盖;无仅 happy-path 跳 failure-mode;集成测试覆盖外部服务交互边界;断言必须在目标回归上失败;验证外部状态/logs/events/disposal,不复述实现、不信任 agent 自报。
66
+ - **Lifecycle & Concurrency Lens** — 对象生命周期与并发时序:① publication 前无竞态(无其他路径可观察到未初始化状态)?② await 期间取消/超时传播到被等待任务且资源正确回收?③ reentry 前所有权已转移或显式保留?④ detach 清理完整(监听器/句柄移除),disposal 在 quiescent(无 in-flight 任务)时执行?(与 **Reliability Lens** 互指:资源/超时/缓存归 Reliability;生命周期/并发时序归本透镜)
67
+ - **Ownership / Derived-State Lens** — ① 每个保留值(字段/闭包捕获/缓存条目)是 borrowed 还是 owned,借用方生命周期不超过所有者?② 每个 cache/UI echo/replay/query view 追溯到 documented success point 与 authoritative source?③ 派生状态(缓存/投影/回显)的失效点与权威源同步声明?
68
+ - **Bounds Lens** — ① 完整产出(含 wrapper/metadata/封套行)的 owner 明确,边界检查覆盖完整产出而非仅载荷?② tiny/exact limit 被探测(空/最小/恰好等于上限)?③ 超大单块(单条记录超上限)被拒绝/截断而非绕过按行/按条门禁?④ 多字节文本(UTF-8 多字节字符)按字节上限而非字符数处理?
69
+ - **Enforcement-Path Lens** — ① 每个 deny/veto 路径追到实际执行拒绝的操作(而非仅声明策略)?② 直调/wrapper/facade/schema-less 路径/listener 顺序等旁路调用方是否都经同一校验点?③ 观察/记录侧(listener/consumer/回调)不会绕过主校验路径写入状态或缓存?(与 **Security Lens** 互指:访问控制点自身正确性归 Security;拒绝/校验路径的执行与旁路追迹归本透镜)
70
+ - **Real-Entry-Path Lens** — ① 测试/覆盖走 shipped entry(CLI/bin/loader/plugin boot)而非 hand-mounted 等价物(手工装配的组件实例)?② 真实入口的启动/挂载顺序(注册时序)被覆盖?
66
71
 
67
72
  ---
68
73
 
@@ -70,6 +75,8 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
70
75
 
71
76
  所有透镜发现归入主报告的 `## Findings` 三节(Critical / Warning / Suggestion)中,每个发现的 `Source Type` 标注为对应透镜名(如 `deep-lens: Security Lens`),与主审查者的 `manual-reasoning` 发现同等待遇。
72
77
 
78
+ 每个透镜 finding 必须附 **diff / read / grep 锚点** + **预期 vs 实际(Expected vs observed)**——无锚点不入报告(宁可漏报不虚报)。
79
+
73
80
  ```markdown
74
81
  ## Scope
75
82
  - plan_id: <id>
@@ -81,6 +88,8 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
81
88
  ### 🔴 Critical
82
89
  - [DS-001] Auth middleware missing on POST /api/admin/users → <fix>
83
90
  - Source Type: deep-lens: Auth Lens
91
+ - Verification: diff/read/grep anchor(`src/routes/admin.ts:41-52` 缺 auth 中间件引用 vs `src/middleware/auth.ts` 注册路径)
92
+ - Expected vs observed: 预期所有 `/api/admin/*` 经 auth 中间件 vs 实际 `POST /api/admin/users` 直入 handler
84
93
  - Confidence: High
85
94
  ```
86
95
 
@@ -28,18 +28,28 @@ Write under the Assignment-provided **`{SDD_DIR}/review/qc#.md`** (`qc1`…`qc3`
28
28
  ## Findings
29
29
  ### 🔴 Critical
30
30
  - {issue} -> {fix}
31
+ - Verification: {re-run repro | log comparison | input-output comparison | dual-path comparison | diff/read/grep anchor}
32
+ - Expected vs observed: {expected state} vs {actual observation}
31
33
 
32
34
  ### 🟡 Warning
33
35
  - {issue} -> {fix}
36
+ - Verification: {re-run repro | log comparison | input-output comparison | dual-path comparison | diff/read/grep anchor}
37
+ - Expected vs observed: {expected state} vs {actual observation}
34
38
 
35
39
  ### 🟢 Suggestion
36
40
  - {improvement}
41
+ - Verification: {diff/read/grep anchor}
42
+ - Expected vs observed: {expected state} vs {actual observation}
43
+
44
+ ### ⚪ Unconfirmed
45
+ - {finding} — channel gap: {reason}
37
46
 
38
47
  ## Source Trace
39
48
  - Finding ID: {F-001}
40
49
  - Source Type: {git-diff | read | grep | doc-rule | manual-reasoning | deep-lens: <name> | assignment-ci-note}
41
50
  - Source Reference: {path/snippet — not a test/build log you produced}
42
51
  - Confidence: High | Medium | Low
52
+ - Note: every finding carries `Verification` + `Expected vs observed` — see the Findings entry format above
43
53
 
44
54
  ## Summary
45
55
  | Severity | Count |
@@ -47,14 +57,18 @@ Write under the Assignment-provided **`{SDD_DIR}/review/qc#.md`** (`qc1`…`qc3`
47
57
  | 🔴 Critical | {n} |
48
58
  | 🟡 Warning | {n} |
49
59
  | 🟢 Suggestion | {n} |
60
+ | ⚪ Unconfirmed | {n} |
50
61
 
51
- **Verdict**: Approve | Request Changes | Needs Discussion
62
+ **Verdict**: Approve | Request Changes | Needs Discussion | Unconfirmed
52
63
  ```
53
64
 
54
65
  Report **Critical / Warning / Suggestion** sections are human-readable; PM maps to machine **`severity`** in `status.json` per `mstar-plan-artifacts/references/status-and-residuals.md`.
55
66
 
56
67
  ## Verdict rules (reviewer applies)
57
68
 
69
+ - Evidence channel failure (Review range cannot be established / key file unreadable) → `Unconfirmed` — report states the failure reason; PM-side handling per `mstar-review-qc` consolidated
70
+ - **Partial** evidence-channel failure → mark only the affected findings **Unconfirmed** (keep verifiable findings; state channel gaps in Summary)
71
+ - Any `Unconfirmed` finding (with or without Critical/Warning) → verdict `Unconfirmed`, never `Approve`; `Approve` additionally requires every finding's evidence channel intact
58
72
  - Unresolved **Critical** or **Warning** → `Request Changes`
59
73
  - No Critical/Warning but high-impact unresolved trade-off (often architectural Suggestion) → `Needs Discussion`
60
74
  - **Approve** only when Critical = 0 and Warning = 0 (unresolved)
@@ -67,6 +81,8 @@ Report **Critical / Warning / Suggestion** sections are human-readable; PM maps
67
81
 
68
82
  ## Evidence rules
69
83
 
84
+ - **If you cannot state a verifiable cross-check, do not report the finding** (prefer omission to fabrication)
85
+ - **A failed evidence channel is not "no problem"** — when the review-package is missing, the diff cannot be parsed, or a referenced file is unreadable, mark the affected scope **Unconfirmed**; never default to "no findings"
70
86
  - Critical findings: trigger condition, impact scope, fix suggestion (from source reasoning)
71
87
  - Low-confidence / runtime-only doubts: follow-up steps for **L4 QA** or implementer — not self-executed suites
72
88
  - Repeated cross-task patterns: mark as recurring in findings
@@ -102,9 +102,11 @@ report_kind: qc
102
102
  reviewer: {role_id}
103
103
  reviewer_index: {reviewer_index}
104
104
  plan_id: "<id>"
105
- verdict: "Approve | Request Changes | Needs Discussion"
105
+ verdict: "Approve | Request Changes | Needs Discussion | Unconfirmed"
106
106
  generated_at: "YYYY-MM-DD"
107
107
  ---
108
+
109
+ Verdict enumeration and rules (incl. `Unconfirmed` semantics) → **`references/qc-specialist/report-template.md`**.
108
110
  ```
109
111
 
110
112
  ## Completion Report
@@ -49,6 +49,39 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
49
49
  - If unspecified, choose the clearest structure for target audience
50
50
  - Keep writing usable and publication-ready
51
51
  - Include source notes when factual claims require evidence
52
+ - Durable harness artifacts (knowledge docs, plans, README, promoted guides) must pass the **HEAD-resolvability test**: a reader at HEAD — no chat transcripts, dispatch prompts, or unmerged drafts — can resolve every reference and verify every claim.
53
+ - Leakage taxonomy and keep rules (mstar-sanctioned): SSOT → `mstar-compound/references/compound-workflow.md`.
54
+ - The same rubric applies to writing scenarios; do not duplicate its prose here.
55
+
56
+ ### Complete-proposition rule
57
+
58
+ Before trimming or restating a passage, enumerate the propositions it makes:
59
+
60
+ - actor + action
61
+ - condition / timing / ordering
62
+ - modality (must / may / must not)
63
+ - negative guarantee + exception
64
+ - ownership / side-effect / failure / consequence
65
+
66
+ Trim modifiers, repetition, or narration **only when every factual clause survives** the edit. Word count alone is not an improvement — a shorter sentence that drops a guarantee, a condition, or an ownership boundary changes the contract, not the prose.
67
+
68
+ ### Coverage-by-artifact
69
+
70
+ One explanation has one home; essential contract facts may repeat locally. Each durable artifact type has a coverage focus:
71
+
72
+ | Artifact | Coverage focus |
73
+ |----------|----------------|
74
+ | Knowledge docs | unique rationale, alternatives considered, shipped verification evidence, named coverage gaps |
75
+ | Plans | prerequisites, actions, observable verification |
76
+ | Review bundles | defect / location / impact / evidence; blockers separated from suggestions |
77
+ | SKILL.md | behavioral guardrails + explicit "guidance, not script" scope limitation |
78
+ | README | consumer contract: config / semantics / failures / limitations / extension points — durable gaps, not cleanup inventories |
79
+ | Completion reports | what / why / verification |
80
+
81
+ ### Doc standards
82
+
83
+ - **Atomic-move rule**: a move = remove + add + fixing every inbound link in the same change; no orphaned references may survive the change set.
84
+ - **Tutorial vs reference**: user-facing docs are either a tutorial (ordered steps to an observable outcome) or a reference (explicitly scoped lookup).
52
85
 
53
86
  ## Completion Report
54
87
 
@@ -87,7 +87,11 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
87
87
 
88
88
  1. `mstar sdd review-package MERGE_BASE HEAD` → branch diff in `{SDD_DIR}/review/`
89
89
  2. PM dispatches **plan QC tri-review (L3)** — **`QC mode: full tri-review`**, **N=3** — with branch review-package path and report paths under `{SDD_DIR}/review/` → **`mstar-review-qc`** · **`mstar-dispatch-gates`**. Layer SSOT → **`mstar-review-qc/references/review-responsibility-boundaries.md`**. PM writes `{SDD_DIR}/review/qc-consolidated.md` and durable main-plan gate summary. **Mandatory whenever `Execution mode: sdd`** (single-plan or iteration).
90
- 3. Critical/Important QC findings → **one** fix dispatch (full list), then targeted re-review
90
+ 3. Critical/Important QC findings → **one** fix dispatch (full list), then targeted re-review. Fix rounds run on four mechanics — the per-task fix loop applies the same (`references/file-handoffs.md`):
91
+ - **Unverified rounds count**: a fix round without verification evidence (reviewer not confirmed / report not on disk) is **not clean** — re-check and count the round; never enter the convergence branch.
92
+ - **Full re-entry**: the next fix dispatch carries **all** open findings (including last round's unverified items) — never slice a subset.
93
+ - **Capped cross-round excerpt**: from round ≥2, the fix dispatch attaches an excerpt of prior rounds' findings and dispositions (advisory caps: ~500 words per round, ~1500 total — suggested values, not hard limits).
94
+ - **Honest non-convergence**: open findings at wave close → list them in detail and state the disposition — re-feed to the next fix round **or** transfer to residual tracking — never silently close.
91
95
  4. QA gate → **`mstar-harness-core`** Done rules; PM **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**
92
96
 
93
97
  ## Progress ledger
@@ -48,6 +48,8 @@ Fix subagent appends to same `task-N-report.md` with test evidence:
48
48
 
49
49
  Re-dispatch reviewer only when all three are present.
50
50
 
51
+ 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`.
52
+
51
53
  ## Progress ledger
52
54
 
53
55
  On clean task review, append to `$SDD_DIR/progress.md`:
@@ -152,11 +152,13 @@ Agents 按 **skill 名** 发现 skill;文档若给出完整仓内相对路径
152
152
  - Progressive disclosure:
153
153
  - Evidence for behavior change (P6):
154
154
  - Stale references checked:
155
- - Verdict: Approve | Request Changes | Needs Discussion
155
+ - Verdict: Approve | Request Changes | Needs Discussion | Unconfirmed
156
+ - Unconfirmed: paired evidence (P6) cannot be established or verified
156
157
  ```
157
158
 
158
159
  ## References
159
160
 
160
161
  | 何时 | 打开 |
161
162
  |------|------|
162
- | 需要完整 skill-writer 流程、原则细则、输出模板 | `references/skillsbench-authoring.md` |
163
+ | 需要完整 skill-writer 流程、原则细则、输出模板 | `references/skillsbench-authoring.md` |
164
+ | 需要把「真实产物」固化为可重跑断言(P6 重武器选项) | `references/regression-fixation.md` |
@@ -0,0 +1,46 @@
1
+ # 回归固化参考(Regression Fixation Reference)
2
+
3
+ 行为塑形改动(skill 正文流程、命令序列、CLI 行为面)的 paired evidence 武器库之一(P6 **重武器选项**)。默认证据仍是 SKILL.md「验证门控」的 P6 before/after + 应用案例;仅当行为可脚本化、且该行为面值得长期固化时,用本手法。
4
+
5
+ ## 何时用(When)
6
+
7
+ - 行为面有**可执行产物**:skill 正文里的流程脚本 / 命令序列 / CLI 调用链。
8
+ - 该面曾出过行为 bug,或改动触碰宿主边界(解析、打包、路径解析、子进程执行)。
9
+ - 例外:纯文案 / 无可观测行为的规则微调 → 走默认 P6,不加载本参考。
10
+
11
+ ## 手法(Technique)
12
+
13
+ 1. **真实产物当被测对象(real artifact as test subject)**
14
+ 不 import 源码、不 mock 掉被测面本身——直接运行用户/agent 实际触达的产物(built bundle、命令序列、宿主钩子驱动的完整流程)。产物侧跑通,才能覆盖「源码 import 跑不到」的缺陷面(bundle 解码、产物路径解析、子进程环境)。
15
+ → 本仓实例:`packages/cli/test/bundle-smoke.test.ts`(2026-08-16 落地)对 **built bundle** `dist/mstar-harness.js` 子进程执行 `dispatch validate` 并断言 exit code,而非 import `src/index.ts`。
16
+
17
+ 2. **Mock 宿主钩子(mock host hooks)**
18
+ 把宿主边界替换为受控桩:mstar 面对应 dispatch / file IO / CLI 调用。固定输入(fixture 文件、argv、环境变量),断言行为输出(exit code、stdout/stderr、副作用文件)。钩子命名沿用宿主自身词汇,不引入外部系统 hook 名。
19
+
20
+ 3. **双路径断言一致(dual-path assertion)**
21
+ 同一断言集对两条路径各跑一遍并断言一致:**真实模块路径**(import 产物 / 源码)与**被测路径**(vm 求值真实脚本 / 子进程 bundle)。任一路径偏离 → 立即暴露「实现与产物行为漂移」。
22
+
23
+ 4. **修复固化(fix solidification)**
24
+ 行为 bug 修复流程:先写复现用例见 FAIL → 修 → 用例见 PASS → 进回归集。此后每次改动重跑回归集,同类 bug 不再复发(回归集随修复轮增长)。
25
+
26
+ ## 最小骨架(Skeleton,零外部依赖)
27
+
28
+ ```js
29
+ // node:test + vm:求值「真实脚本文本」,不复制逻辑到测试
30
+ import test from "node:test";
31
+ import vm from "node:vm";
32
+
33
+ const script = readFileSync("flow.js", "utf8"); // 真实产物
34
+ const sandbox = { dispatch: mockDispatch, fileIO: mockFileIO }; // mock 宿主钩子
35
+ vm.runInNewContext(script, sandbox); // 被测路径
36
+ assert.deepEqual(sandbox.events, expected); // 断言行为输出
37
+ // 双路径:同一断言集对真实模块路径再跑一遍,assert 一致
38
+ ```
39
+
40
+ bun test 同理:`Bun.spawnSync` 子进程跑 bundle + `expect` 断言(见本仓 bundle-smoke 实例)。
41
+
42
+ ## 边界(Boundaries)
43
+
44
+ - **零外部依赖**:Node 内置 `vm` / `node:test`(或 bun test)即可,不引入第三方测试框架。
45
+ - **不强制**:默认仍是 P6 before/after + 应用案例;本参考是重武器选项。
46
+ - **只固化可观测行为**:模型判断、触发精确性等不可脚本化断言的面,仍走压力场景(SKILL.md「验证门控」)。
@@ -76,6 +76,43 @@ Do **not** restate generic knowledge the model already has — that wastes token
76
76
  6. **Pressure / paired check** — 2–3 prompts that fail without the skill; confirm improvement (P4, P6).
77
77
  7. **Ship note** — list deletions/compressions (P2/P5) and how P6 was verified.
78
78
 
79
+ ## Authoring devices
80
+
81
+ Small, composable techniques for specific authoring problems; each maps onto one or two
82
+ principles above. Pull one in when it fits — do not encode all six into every skill.
83
+
84
+ 1. **Calibrated examples file** (serves P2/P5) — keep one small reference of real cases
85
+ distilled into annotated judgments; readers identify the governing principle, not text
86
+ templates, and it is written back when a new rule settles. In this harness: the Q1–Q8
87
+ worked judgments in `mstar-compound` `references/compound-workflow.md`; this iteration's
88
+ fold-B overcorrection checklist (device 3) is a softer second instance.
89
+
90
+ 2. **Recall batteries** (serves P5) — for audit/hunt skills: over-matching probes that
91
+ force a semantic judgment, plus a documented list of known false-positive families; a
92
+ zero-hit pattern proves nothing until you have seen it match. In this harness: the recon
93
+ hints `mstar-audit` fans out to scout subagents — scoping facts, domain risk hints, and
94
+ decided-tradeoff "don't report" pointers.
95
+
96
+ 3. **Overcorrection traps** (adjacent to P6) — a short section per skill naming the failure
97
+ modes of over-applying its own rules, so the skill guards its own bias. In this harness:
98
+ the overcorrection-traps row in `mstar-compound` `references/compound-workflow.md`
99
+ (obligation↛endorsement flips, hypotheticals stay marked, delete clauses, not sentences).
100
+
101
+ 4. **Required-explicit-input** (adjacent to P3) — when the required scope or answers are
102
+ missing, report and stop; never infer a repo-wide default. In this harness: `mstar-audit`
103
+ asks which findings to turn into plans — "do not write 30 plans nobody asked for" —
104
+ instead of inferring the scope itself.
105
+
106
+ 5. **Questions ≠ write authority** (serves P6) — interaction and calibration gates never
107
+ change edit authority; only the evaluation does. In this harness: `grill-me` interviews
108
+ without editing, and `mstar-sdd` keeps the per-task reviewer's report separate from the
109
+ implementer's application.
110
+
111
+ 6. **Invocation boundary** (adjacent to P3) — declare expensive workflows user-invocable
112
+ only; never put them in a skill load order. In this harness: the `/iteration-*` lifecycle
113
+ lives in `commands/`; `mstar-harness-core` keeps command-layer references out of the
114
+ `mstar-*` load matrix.
115
+
79
116
  ## Output template
80
117
 
81
118
  ```markdown
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mstar-harness/opencode",
3
- "version": "2.2.0",
3
+ "version": "2.3.0",
4
4
  "description": "Morning Star harness OpenCode plugin — skills bootstrap + engine-backed runtime hooks (status lint, dispatch validation, Enforcement: hard gates).",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -36,6 +36,6 @@
36
36
  "access": "public"
37
37
  },
38
38
  "devDependencies": {
39
- "@mstar-harness/engine": "2.2.0"
39
+ "@mstar-harness/engine": "workspace:*"
40
40
  }
41
41
  }