@mstar-harness/engine 3.6.2 → 3.7.0

package/dist/prreview.d.ts

@@ -57,8 +57,7 @@ export type PrTallyResult = {
  */
 export declare function computePrTally(input: PrTallyInput): PrTallyResult;
 /**
- * One accepted PR-review finding in the `mstar.review/v1` envelope (SP3 §
- * Schema). `mergeClass` is harness vocab (MERGE_CLASSES); `title`/`body`
+ * One accepted PR-review finding in the `mstar.review/v1` envelope (the review envelope schema). `mergeClass` is harness vocab (MERGE_CLASSES); `title`/`body`
  * are non-empty strings; the rest are optional.
  */
 export type MstarReviewFinding = {
@@ -72,7 +71,7 @@ export type MstarReviewFinding = {
     fingerprint_hint?: string;
 };
 /**
- * The `mstar.review/v1` envelope (SP3 § Schema) — a parseable review
+ * The `mstar.review/v1` envelope (the review envelope schema) — a parseable review
  * document with harness vocab, sibling to the Markdown pr-review report.
  * `verdict` is PR_VERDICTS; `tally` (when present) must be a full
  * `PrTallyResult` (shape-checked) whose `verdict` must equal the top-level
@@ -92,7 +91,7 @@ export type MstarReviewV1 = {
     };
 };
 /**
- * Validate a `mstar.review/v1` envelope (SP3 § Schema). Fail-loud sibling
+ * Validate a `mstar.review/v1` envelope (the review envelope schema). Fail-loud sibling
  * of {@link validatePrReviewReport} (the Markdown report validator) —
  * shares PR_VERDICTS / MERGE_CLASSES only, never reuses the Markdown
  * parser. Inspector M1 vocab (`comment|request_changes|approve`,
@@ -108,7 +107,7 @@ export type MstarReviewV1 = {
 export declare function validateMstarReviewV1(doc: unknown): GateResult;
 /**
  * Fold already-vetted findings into a complete `mstar.review/v1` envelope
- * (SP3 § synthesizeReview). Pure and synchronous — verdict/tally come ONLY
+ * . Pure and synchronous — verdict/tally come ONLY
  * from {@link computePrTally}; no I/O, no GitHub, no store, no seat
  * dispatch. `findings` pass through untouched; `target` is carried when
  * provided. When `summary_md` is omitted, {@link defaultReviewSummary}
@@ -126,11 +125,11 @@ export declare function synthesizeReview(input: {
  *
  * - `pr` — reviewed PR number `n`.
  * - `branch` — bare branch, `slug` is the pre-slugged `<branch-slug>`
- *   (caller slugs; the resolver only guards path safety).
+ * (caller slugs; the resolver only guards path safety).
  * - `diff` — arbitrary changeset. When `headSha` is a non-empty string its
- *   short form (first 7 hex chars) lands in the filename; when absent or an
- *   empty string the bare `-diff` stem is used — a missing SHA is **never
- *   fabricated** (pr-review.md § Local report archive, Filename bullet).
+ * short form (first 7 hex chars) lands in the filename; when absent or an
+ * empty string the bare `-diff` stem is used — a missing SHA is **never
+ * fabricated** (pr-review.md § Local report archive, Filename bullet).
  */
 export type PrReportTarget = {
     kind: "pr";
@@ -148,16 +147,16 @@ export type PrReportTarget = {
  * never writes and never overwrites):
  *
  * - `<YYYY-MM-DD>-pr<N>.md` for PR targets; bare branch →
- *   `<YYYY-MM-DD>-<branch-slug>.md`; diff with head SHA →
- *   `<YYYY-MM-DD>-diff-<short-head-sha>.md`; diff without →
- *   `<YYYY-MM-DD>-diff.md` (never fabricate a SHA).
+ * `<YYYY-MM-DD>-<branch-slug>.md`; diff with head SHA →
+ * `<YYYY-MM-DD>-diff-<short-head-sha>.md`; diff without →
+ * `<YYYY-MM-DD>-diff.md` (never fabricate a SHA).
  * - `stage: 1 | 2` requires `slug` (the seat Assignment's `<domain>-<seat>`
- *   slug) and produces the Stage 1/2 evidence-file stem
- *   `<stem>-stage<1|2>-<slug>.md`.
+ * slug) and produces the Stage 1/2 evidence-file stem
+ * `<stem>-stage<1|2>-<slug>.md`.
  * - Same day, same target (same final stem): scans ALL existing files in
- *   `reportsDir` with that stem and appends `-r2`, `-r3`, ... on collision —
- *   a prior report is never overwritten. Report files and evidence files
- *   escalate independently (different stems).
+ * `reportsDir` with that stem and appends `-r2`, `-r3`, ... on collision —
+ * a prior report is never overwritten. Report files and evidence files
+ * escalate independently (different stems).
  * - `date` defaults to the local calendar date and must be `YYYY-MM-DD`.
  */
 export declare function prReviewReportPath(opts: {
@@ -174,22 +173,22 @@ export declare function prReviewReportPath(opts: {
  *
  * - `type: pr-review` required.
  * - `verdict` exactly one of the three verdict tokens (§ Verdict synthesis)
- *   and CONSISTENT with the tally (any must_fix -> blocked; else any
- *   should_fix -> needs fixes; else ship it).
+ * and CONSISTENT with the tally (any must_fix -> blocked; else any
+ * should_fix -> needs fixes; else ship it).
  * - `score_pct` integer 0-100 and equal to the locked-formula recompute
- *   from the document's own tally via {@link computePrTally}
- *   (mismatch = hand-arithmetic drift — the exact defect class this gate
- *   exists to catch).
+ * from the document's own tally via {@link computePrTally}
+ * (mismatch = hand-arithmetic drift — the exact defect class this gate
+ * exists to catch).
  * - `tally` flow map with the four classes.
  * - `comments` tri-state: `posted` (alias `yes`) | `n/a-no-pr` | `failed`.
- *   The states are distinct: a FAILED POST IS `FAILED`, never
- *   `n/a-no-pr`; `review_url` must pair accordingly (`http(s)://` for
- *   posted, `n/a` for n/a-no-pr, a `failed: <gh error summary>` for failed).
+ * The states are distinct: a FAILED POST IS `FAILED`, never
+ * `n/a-no-pr`; `review_url` must pair accordingly (`http(s)://` for
+ * posted, `n/a` for n/a-no-pr, a `failed: <gh error summary>` for failed).
  * - `generated_at` must be `YYYY-MM-DD` (DATE_RE).
  * - `tier` optional: `quick | default | deep`; absent is valid (legacy
- *   reports without tier still pass — SP-A amendment).
+ * reports without tier still pass — SP-A amendment).
  * - `elapsed` optional: non-negative integer minutes; absent is valid
- *   (legacy reports without elapsed still pass).
+ * (legacy reports without elapsed still pass).
  */
 export declare function validatePrReviewReport(text: string): GateResult;
 /** One inline review comment: `path` + `line` in the three-dot diff, RIGHT
@@ -221,14 +220,14 @@ export type ReviewPostPlan = {
  * 422 fallback stay with the CLI, which owns the network):
  *
  * - Resolves the target from `gh pr view --json url,headRefOid` output:
- *   parse `owner/repo` from `url` ONLY — the BASE repo that owns the PR
- *   number. `headRepository` (fork head-repo data) is IGNORED: fork PRs
- *   are legal, and a fork's owner/name must never leak into the API path.
- *   It is never used as a fallback either.
+ * parse `owner/repo` from `url` ONLY — the BASE repo that owns the PR
+ * number. `headRepository` (fork head-repo data) is IGNORED: fork PRs
+ * are legal, and a fork's owner/name must never leak into the API path.
+ * It is never used as a fallback either.
  * - Missing/invalid `headRefOid` throws — there is no commit_id without
- *   it.
+ * it.
  * - `event` is always the literal `"COMMENT"`; no other value exists in
- *   this contract.
+ * this contract.
  * - Inline comments validated per-entry (path / positive line / RIGHT).
  */
 export declare function planReviewPost(prView: {
@@ -256,13 +255,13 @@ export type ReviewChangesetMode = "pr" | "branch" | "diff" | "working-tree" | "c
  * (pr-review.md § Worktree isolation Pre-flight bullet, all modes):
  *
  * - Named refs must resolve in modes that HAVE refs (pr / branch / commit);
- *   establish them with explicit refspecs first.
+ * establish them with explicit refspecs first.
  * - The changeset must be NON-empty in ALL modes — an empty changeset
- *   reports "no changes to review" and stops before any lens fan-out.
+ * reports "no changes to review" and stops before any lens fan-out.
  * - For working-tree input, untracked-only changes ARE a non-empty
- *   changeset: the caller folds `git ls-files --others
- *   --exclude-standard` output into `changesetEmpty: false` when anything
- *   is listed.
+ * changeset: the caller folds `git ls-files --others
+ * --exclude-standard` output into `changesetEmpty: false` when anything
+ * is listed.
  */
 export declare function preflightChangeset(mode: ReviewChangesetMode, probe: {
     refsResolve: boolean;
@@ -277,12 +276,12 @@ export type PrReviewSizing = {
     /** True for too-large (>~1000) — advise a split, never auto-blocked. */
     adviseSplit: boolean;
     /** Stage 1 collect seats (§ Scale-driven fan-out table). Kept-wave
-     * qualifier: these seats apply only when the deep collect wave is KEPT —
-     * by default (pinned diff pack present) the fold dispatches none
-     * (pr-review.md § Review pipeline fold default). */
+   * qualifier: these seats apply only when the deep collect wave is KEPT —
+   * by default (pinned diff pack present) the fold dispatches none
+   * (pr-review.md § Review pipeline fold default). */
     collectSeats: 2 | 3;
     /** File-size watch fired → advise extract/decompose ("decompose, then
-     * add"). Independent of the diff size. */
+   * add"). Independent of the diff size. */
     fileDecomposeAdvice: boolean;
 };
 /**
@@ -290,13 +289,13 @@ export type PrReviewSizing = {
  * (pr-review.md § Sizing & change shape + § Scale-driven fan-out):
  *
  * - ≤~300 reviewable/acceptable → band `small`; >~300 → `large`;
- *   >~1000 → `too-large` + split advice (a should-fix finding with split
- *   advice or a verdict note — never auto-`blocked`).
+ * >~1000 → `too-large` + split advice (a should-fix finding with split
+ * advice or a verdict note — never auto-`blocked`).
  * - Stage 1 collect seats: small → 2 (code + security); large/too-large →
- *   3 by domain.
+ * 3 by domain.
  * - `largestTouchedFileTotal` drives `fileDecomposeAdvice` INDEPENDENTLY
- *   of the diff size — a small diff materially growing a file past ~1000
- *   total lines gets "decompose, then add".
+ * of the diff size — a small diff materially growing a file past ~1000
+ * total lines gets "decompose, then add".
  */
 export declare function prReviewSizing(input: {
     changedLines: number;
@@ -310,23 +309,23 @@ export declare function prReviewSizing(input: {
  * includes everything. */
 export type PrReviewTier = "quick" | "default" | "deep";
 /**
- * Per-tier time budget for the `amazing-pr-review` pipeline (SP1 tier
+ * Per-tier time budget for the `amazing-pr-review` pipeline (tier
  * time-budget). Prose SSOT: pr-review.md § Review depth — its Budget column
  * carries the wall-clock minutes; the per-seat caps below are the engine
  * contract, rendered into seat prompts, never duplicated as numbers in prose.
  *
  * - `wallClockMinutes`: prompt-discipline target for the whole review,
- *   measured worktree-setup → local report saved by the main agent.
- *   Overruns are declared in the report `- notes:` — budgets are never a
- *   host-level hard kill.
+ * measured worktree-setup → local report saved by the main agent.
+ * Overruns are declared in the report `- notes:` — budgets are never a
+ * host-level hard kill.
  * - `maxSeats`: review seats only — Stage 2 domain seats + the independent
- *   cross-domain security seat; NOT Stage 1 collect seats (collect fan-out
- *   stays governed by pr-review.md § Scale-driven fan-out).
+ * cross-domain security seat; NOT Stage 1 collect seats (collect fan-out
+ * stays governed by pr-review.md § Scale-driven fan-out).
  * - `perSeatFindingsCap` / `evidenceTokensCap` / `fileOpenCap`: per-seat
- *   expansion stops (findings / evidence payload tokens / file opens; the
- *   pinned diff snapshot read does not count). Baseline assumption: 100
- *   tok/s output — wall-clock is dominated by reads/tool latency, which
- *   `fileOpenCap` bounds.
+ * expansion stops (findings / evidence payload tokens / file opens; the
+ * pinned diff snapshot read does not count). Baseline assumption: 100
+ * tok/s output — wall-clock is dominated by reads/tool latency, which
+ * `fileOpenCap` bounds.
  *
  * No new sizing bands: the table references tiers only (pr-review.md
  * § Sizing & change shape stays the only sizing SSOT). */
@@ -349,18 +348,18 @@ export type PrReviewSeatPromptOptions = {
     securitySeat?: boolean;
     tier?: PrReviewTier;
     /** Absolute path to the pinned diff snapshot written by `worktree-setup`
-     * (review artifact beside the sidecar). Non-empty → the prompt gains a
-     * read-first ingredient line pointing at it. */
+   * (review artifact beside the sidecar). Non-empty → the prompt gains a
+   * read-first ingredient line pointing at it. */
     diffFile?: string;
     /** Stage-2 only (`true` + `stage: 1` throws): the collect wave was folded
-     * onto this domain seat — the deep-tier fold default (pinned diff pack
-     * present; SSOT pr-review.md § Review pipeline; prose "collection folded
-     * in = seat reuse" = § Review depth default-tier row). Kept-wave
-     * exceptions dispatch collect seats instead. Requires a non-empty
-     * `diffFile`, and the independent cross-domain security seat is never
-     * folded — either contradiction throws. The prompt gains one bullet after
-     * the `## Budget` block telling the seat to do its own collection, staying
-     * within the budget block. Omitted/`false` → no line. */
+   * onto this domain seat — the deep-tier fold default (pinned diff pack
+   * present; SSOT pr-review.md § Review pipeline; prose "collection folded
+   * in = seat reuse" = § Review depth default-tier row). Kept-wave
+   * exceptions dispatch collect seats instead. Requires a non-empty
+   * `diffFile`, and the independent cross-domain security seat is never
+   * folded — either contradiction throws. The prompt gains one bullet after
+   * the `## Budget` block telling the seat to do its own collection, staying
+   * within the budget block. Omitted/`false` → no line. */
     collectFolded?: boolean;
 };
 /**
@@ -370,30 +369,30 @@ export type PrReviewSeatPromptOptions = {
  * Ingredients:
  *
  * - Absolute path to `references/pr-review.md` under `skillRoot` + the
- *   sections to read; absolute review `worktreePath`.
- * - Per-seat budget block (`## Budget`, SP1 tier time-budget): findings /
- *   evidence-token / file-open caps interpolated from `PR_REVIEW_TIER_BUDGETS`
- *   — expansion stops for the seat, never a host-level hard stop.
+ * sections to read; absolute review `worktreePath`.
+ * - Per-seat budget block (`## Budget`, tier time budget): findings /
+ * evidence-token / file-open caps interpolated from `PR_REVIEW_TIER_BUDGETS`
+ * — expansion stops for the seat, never a host-level hard stop.
  * - `collectFolded: true` (stage 2 only; stage 1, a missing `diffFile`, or
- *   the security seat throws): one bullet after the `## Budget` block — the
- *   collect wave folded onto this seat, so it collects itself (pinned diff
- *   snapshot/pack first, then in-domain changed files) within the budget
- *   block.
+ * the security seat throws): one bullet after the `## Budget` block — the
+ * collect wave folded onto this seat, so it collects itself (pinned diff
+ * snapshot/pack first, then in-domain changed files) within the budget
+ * block.
  * - Recon facts + decided tradeoffs.
  * - Hard Rules 4/5 VERBATIM.
  * - Payload-return contract (write-blocked-safe; main agent writes files).
  * - No-verdict / never-post clauses.
  * - Slug mandate `<domain>-<seat>`.
  * - Stage 2 adds finding-format.md (+ security-review.md for security
- *   seats) and the Merge-class instruction.
+ * seats) and the Merge-class instruction.
  * - Tier cuts (SP-A amendment): quick drops the cross-domain /
- *   independent-security block, the collect-wave wording AND shrinks the
- *   lens/prompt-ingredient set; default drops the same blocks (SSOT
- *   pr-review.md § Review depth, default-tier row: "collection folded in =
- *   seat reuse" — no separate Stage-1 wave, so collect-wave wording is
- *   deep-only); deep keeps everything.
- *   Tier omitted → `default` (pr-review.md § Review depth: the no-flag
- *   landing tier).
+ * independent-security block, the collect-wave wording AND shrinks the
+ * lens/prompt-ingredient set; default drops the same blocks (SSOT
+ * pr-review.md § Review depth, default-tier row: "collection folded in =
+ * seat reuse" — no separate Stage-1 wave, so collect-wave wording is
+ * deep-only); deep keeps everything.
+ * Tier omitted → `default` (pr-review.md § Review depth: the no-flag
+ * landing tier).
  */
 export declare function prReviewSeatPrompt(opts: PrReviewSeatPromptOptions): string;
 /** Options for {@link validateFindingDoc}: `prVariant` gates the Merge
@@ -407,18 +406,18 @@ export type ValidateFindingDocOptions = {
  * PR-only Merge class contract (pr-review.md § Merge class):
  *
  * - Every finding opens with `### [CATEGORY-NN] Title`; CATEGORY ∈
- *   `AUDIT_CATEGORIES` (case-insensitive read, canonical uppercase forms
- *   per category codes), NN numeric.
+ * `AUDIT_CATEGORIES` (case-insensitive read, canonical uppercase forms
+ * per category codes), NN numeric.
  * - Required fields: Evidence / Impact / Effort / Risk / Confidence —
- *   Effort / Risk / Confidence each validated as their LEADING token
- *   (Effort via `AUDIT_EFFORTS`, Risk via `AUDIT_RISKS`, Confidence via
- *   HIGH | MED | LOW with `MEDIUM` tolerated as the MED alias); free-text
- *   gloss after a separator is allowed and ignored.
+ * Effort / Risk / Confidence each validated as their LEADING token
+ * (Effort via `AUDIT_EFFORTS`, Risk via `AUDIT_RISKS`, Confidence via
+ * HIGH | MED | LOW with `MEDIUM` tolerated as the MED alias); free-text
+ * gloss after a separator is allowed and ignored.
  * - Each Evidence citation matches `path:line` (`\S+:\d+` — the path may
- *   but need not carry an extension).
+ * but need not carry an extension).
  * - `prVariant` (default false): every finding additionally carries
- *   **Merge class** ∈ {must-fix, should-fix, nit} placed IMMEDIATELY after
- *   Confidence.
+ * **Merge class** ∈ {must-fix, should-fix, nit} placed IMMEDIATELY after
+ * Confidence.
  */
 export declare function validateFindingDoc(text: string, opts?: ValidateFindingDocOptions): GateResult;
 /** Tier keywords the CLI may have matched from argv — the three explicit
@@ -441,16 +440,16 @@ export type ResolvePrReviewTierInput = {
  * (SP-A amendment; first hit wins):
  *
  * 1. Explicit keyword → that tier (user intent beats heuristics; a lone
- *    `default` returns `default` BEFORE the band/sensitive heuristics).
- *    Any two DISTINCT keywords (quick / default / deep) → hard-stop
- *    conflict error — never silently take a priority. (Empty/omitted =
- *    no flag.)
+ * `default` returns `default` BEFORE the band/sensitive heuristics).
+ * Any two DISTINCT keywords (quick / default / deep) → hard-stop
+ * conflict error — never silently take a priority. (Empty/omitted =
+ * no flag.)
  * 2. Too large (>~1000 / band too-large) → advise split; review anyway →
- *    deep.
+ * deep.
  * 3. Sensitive surface (auth / LLM / supply chain / data) → deep at any
- *    size.
+ * size.
  * 4. Large (>~300 / band large) → deep.
  * 5. Small: tiny-mechanical shape (docs-only / rename / formatting / pure
- *    deletion) → quick; anything else (real code change) → default.
+ * deletion) → quick; anything else (real code change) → default.
  */
 export declare function resolvePrReviewTier(input: ResolvePrReviewTierInput): PrReviewTier;

package/dist/roles.d.ts

@@ -47,14 +47,14 @@ export type RoleMappingOptions = {
  * layout (mstar-roles § Role Reference Mapping / § Parameter Table (SSOT)
  * / § Maintenance Rules):
  * - every mapped agent id resolves to `references/<role>.md` under
- *   `rolesDir`;
+ * `rolesDir`;
  * - shared families (`fullstack-dev*`, `qc-specialist*`) resolve to ONE
- *   shared reference file each;
+ * shared reference file each;
  * - every parameter row references a mapped role, exactly once;
  * - dev track values are `primary` / `parallel_secondary`;
  * - the QC parameter table contract holds: reviewer_index is exactly
- *   {1, 2, 3} across the three seats, each seat has a focus, and
- *   `report_suffix === qc<reviewer_index>`.
+ * {1, 2, 3} across the three seats, each seat has a focus, and
+ * `report_suffix === qc<reviewer_index>`.
  *
  * Violations:
  * - `roles.mapping.reference.missing` — mapped reference file not on disk
@@ -70,18 +70,28 @@ export type RoleMappingOptions = {
 export declare function validateRoleMapping(rolesDir: string, options?: RoleMappingOptions): GateResult;
 /**
  * Lint load-order declarations across skill texts (mstar-harness-core
- * § 加载约定: every `mstar-*` topic skill presumes the reader has Read core
- * first, so each must declare `mstar-harness-core` in its Load Order /
- * First action section).
+ * § 与其它 `mstar-*` skill 的加载契约 + mstar-roles § Load Order; Spec A2 —
+ * single load-selection authority).
  *
  * Input: `skillTexts` maps skill name → full SKILL.md text. `mstar-harness-
- * core` itself and non-`mstar-*` skills are exempt. Heuristic: a section
- * headed Load Order / Load order / First action must exist and mention
- * `mstar-harness-core` inside that section (mentions in later sections do
- * not count).
+ * core` itself and non-`mstar-*` skills are exempt.
+ *
+ * - Every `mstar-*` topic skill (reached by direct invocation) must have a
+ * Load Order / First action section (heading Load Order / Load order /
+ * First action) that names `mstar-harness-core` as its first dependency
+ * (mentions in later sections do not count).
+ * - The `mstar-roles` hub bootstrap is the ONE exception (narrow, keyed on
+ * the skill name — broad exemptions are rejected): it does not declare
+ * core-first; instead its Load Order section must declare the preset
+ * decision matrix (`roles.loadorder.hub.bootstrap.missing` when tokens
+ * are missing) and keep the conditional `mstar-harness-core`
+ * conflict-authority pointer (`roles.loadorder.core.missing`).
  *
  * Violations:
  * - `roles.loadorder.section.missing` — no Load Order / First action section
- * - `roles.loadorder.core.missing` — section exists without the core mention
+ * - `roles.loadorder.core.missing` — topic section without the core-first
+ * declaration, or hub section without the core conflict-authority pointer
+ * - `roles.loadorder.hub.bootstrap.missing` — hub section missing the
+ * identity→none/standard/methods/unknown-preset decision matrix
  */
 export declare function lintLoadOrder(skillTexts: Record<string, string>): GateResult;

package/dist/sdd.d.ts

@@ -1,3 +1,4 @@
+import { type GateResult } from "./core.js";
 /**
  * Error carrying the ported script exit code so the CLI can map validation
  * failures to identical non-zero exits.
@@ -18,17 +19,41 @@ export type SddWorkspaceOptions = {
     /** Working directory for git probes; default `process.cwd()`. */
     cwd?: string;
 };
-/** Options for `taskBrief` (mirrors `$SDD_DIR` for the default out path). */
+/**
+ * Options for `taskBrief` (mirrors `$SDD_DIR` for the default out path).
+ *
+ * Bound mode (spec A3): passing
+ * `context` makes the destination an artifact gate check (before any
+ * mkdir/write), defaults the destination to `{context.sddDir}/task-N-brief.md`
+ * and returns/emits an absolute path. Without `context` the legacy helper
+ * stays explicitly UNBOUND — a context-less call has no protection claim
+ * (A3: "context-less legacy helper calls remain explicitly unbound").
+ */
 export type TaskBriefOptions = {
     sddDir?: string;
+    /** Resolved SDD execution context — binds the artifact write (A3). */
+    context?: SddExecutionContext;
+    /** Observed invocation cwd for the artifact gate; default `process.cwd()`. */
+    cwd?: string;
 };
-/** Options for `reviewPackage` (mirrors `$SDD_DIR` + git probe cwd). */
+/**
+ * Options for `reviewPackage` (mirrors `$SDD_DIR` + git probe cwd).
+ *
+ * Bound mode (spec A3): passing `context` makes the destination an artifact
+ * gate check (before any mkdir/write), defaults the git probe cwd to the
+ * context's feature worktree ("feature Git cwd, control artifact out") and
+ * returns/emits an absolute path. Without `context` the legacy helper stays
+ * explicitly UNBOUND — no protection claim.
+ */
 export type ReviewPackageOptions = {
     sddDir?: string;
+    /** Git probe cwd; bound mode defaults to `context.featureCwd`. */
     cwd?: string;
+    /** Resolved SDD execution context — binds the artifact write (A3). */
+    context?: SddExecutionContext;
 };
 /**
- * Git capture ceiling for `gitOut` / `reviewPackage` (qc3 W-2): Node's
+ * Git capture ceiling for `gitOut` / `reviewPackage` : Node's
  * default 1 MiB `maxBuffer` ENOBUFS'd on large review ranges. 64 MiB keeps
  * realistic iteration-close ranges working while bounding memory; captures
  * beyond that fail as SddScriptError via the CLI.
@@ -39,13 +64,13 @@ export declare const GIT_CAPTURE_MAX_BYTES: number;
  * the absolute path). Resolution order:
  *
  * 1. fail-closed FIRST: a linked worktree without a control root never
- *    resolves or creates any SDD tree under the feature checkout (refuses a
- *    second SDD tree; no override or probe may bypass this guard);
+ * resolves or creates any SDD tree under the feature checkout (refuses a
+ * second SDD tree; no override or probe may bypass this guard);
  * 2. explicit harness-root override (`opts.harnessDir` / `MSTAR_HARNESS_DIR`)
- *    — plan finding 2026-08-08: covers repos the status.json probe misses;
- *    resolved relative to the established root;
+ * — plan finding 2026-08-08: covers repos the status.json probe misses;
+ * resolved relative to the established root;
  * 3. `.mstarc` `[config] harness_dir` at `root` (repo-declared root;
- *    resolved against the config file's directory);
+ * resolved against the config file's directory);
  * 4. `status.json` probe at root (`.mstar` → `.agents`);
  * 5. fallback: existing `.mstar`/`.agents` dir, else `.mstar`.
  *
@@ -61,6 +86,14 @@ export declare function sddWorkspace(planId: string, opts?: SddWorkspaceOptions)
  * EOF for the last task) — a later Task heading resets the section. A
  * missing task writes an empty file then fails with exit-3
  * (`SddScriptError.exitCode === 3`).
+ *
+ * Bound mode (`opts.context`, spec A3): the artifact destination is gated
+ * with `checkSddAction` BEFORE any mkdir/write — a refused destination
+ * writes nothing — and the returned path is absolute. The INPUT is bound
+ * too: the plan file must canonicalize to the context's `planFile`, and a
+ * mismatch is refused (exit 1) before any read or write — a foreign plan's
+ * content must never land in this plan's SDD dir. Context-less calls
+ * keep the legacy unbound behavior (no protection claim).
  */
 export declare function taskBrief(planFile: string, taskN: number, outFile?: string, opts?: TaskBriefOptions): string;
 /**
@@ -69,6 +102,14 @@ export declare function taskBrief(planFile: string, taskN: number, outFile?: str
  * Both refs are validated with `git rev-parse --verify --quiet` (any ref
  * the original accepted is accepted here; the SHA-only guard is
  * `assertBaseSha`).
+ *
+ * Bound mode (`opts.context`, spec A3): the review range is probed in the
+ * context's feature worktree (feature Git cwd) while the package lands in
+ * the plan's control artifacts — gated with `checkSddAction` BEFORE any
+ * mkdir/write (a refused destination writes nothing). The returned path is
+ * absolute. Context-less calls keep the legacy unbound behavior (no
+ * protection claim); an explicit `opts.cwd` still overrides the git probe
+ * cwd in both modes.
  */
 export declare function reviewPackage(base: string, head: string, outFile?: string, opts?: ReviewPackageOptions): string;
 /**
@@ -130,3 +171,152 @@ export type StickyRulesResult = {
  * resume — that rule lives in the PM flow, not the session ledger.
  */
 export declare function implementerSessionStickyRules(input: StickyRulesInput): StickyRulesResult;
+/**
+ * Resolved SDD execution context (spec A3): where control artifacts live,
+ * where feature source edits happen, and which branch the feature checkout
+ * must be on. All paths normalized absolute (canonicalized on resolve);
+ * `planFile` / `sddDir` must resolve within the control harness and match
+ * `planId`; the feature branch/worktree must match the verified lease when
+ * an active workflow supplies one (standalone non-iteration contexts remain
+ * possible under the existing branch policy — no new global lease mandate).
+ * A declared control root is authoritative: it is never re-inferred from
+ * the feature cwd (mstar-branch-worktree «Harness path SSOT»).
+ */
+export type SddExecutionContext = {
+    planId: string;
+    /** Control harness dir (`<control-worktree>/{HARNESS_DIR}`), absolute. */
+    controlHarnessRoot: string;
+    /** Feature worktree — the required cwd for product/source edits, absolute. */
+    featureCwd: string;
+    /** Assignment Working branch checked out at `featureCwd`. */
+    workingBranch: string;
+    /** Control plan file (`{PLAN_DIR}/<plan-id>.md`), absolute. */
+    planFile: string;
+    /** Control `{SDD_DIR}` = `{HARNESS_DIR}/sdd/<plan-id>/`, absolute. */
+    sddDir: string;
+};
+/** One action seam to gate with `checkSddAction` (spec A3). */
+export type SddAction = {
+    /**
+   * Observed invocation cwd — the real cwd at the seam, never an Assignment
+   * echo. Relative `target` values resolve from this cwd.
+   */
+    cwd: string;
+    /** Path the action would touch; optional for source/launch, required for artifact. */
+    target?: string;
+    kind: SddActionKind;
+};
+/** Action seam kinds (spec A3): feature source write, control artifact write, child-process launch. */
+export type SddActionKind = "source" | "artifact" | "launch";
+/**
+ * Resolve and validate a declared SDD execution context (spec A3) into a
+ * canonical context. Read-only — resolves/validates, never writes.
+ *
+ * Validation (reusing the existing machinery — never duplicated here):
+ * - shape: all paths absolute, `planId` a single safe path component
+ * (`assertSafePathComponent`);
+ * - `controlHarnessRoot` exists (declared root is authoritative — never
+ * re-inferred from the feature cwd);
+ * - `planFile` identity (basename stem = `planId`) + placement via
+ * `assertPlanWritingPath` (inside `{PLAN_DIR}` of the control harness,
+ * symlink escape checked against the canonical path);
+ * - `sddDir` canonicalizes (nearest existing ancestor on BOTH sides) to the
+ * same path as `resolveSddDir(controlHarnessRoot, planId)` — the path
+ * SSOT composition, `.mstarc` overrides included; equivalent string forms
+ * of one physical destination are valid. Composition equality on the
+ * canonical pair subsumes the escape case — a declared sddDir cannot
+ * equal the canonical composition and escape at the same time — so
+ * divergence is classified at one decision point: divergence because the
+ * declared path physically canonicalizes OUTSIDE the control harness
+ * (symlinked sdd segment routing out) is environmental →
+ * `sdd.context.sdd-dir-escape` gate fail (exit 1); any other divergence
+ * (wrong declaration) is usage (exit 2). A context matching a
+ * `.mstarc`-declared sdd base is honored wherever the repo's own path
+ * SSOT composes it — the engine never second-guesses a composition it
+ * would itself produce (`resolveSddDir` is authoritative);
+ * - `featureCwd` exists and never nests with the control checkout
+ * (`featureCwd` inside the control checkout, or the control harness
+ * inside the feature checkout, are both refused — L1 hard rules);
+ * - branch/lease: when the control harness's workflow snapshots supply a
+ * plan row from a REGISTERED ACTIVE workflow (v2 root `status.json`
+ * `workflows[]`; a retained terminal snapshot never satisfies lease
+ * enforcement, and a plan claimed by multiple active workflows fails
+ * closed), its lease is verified (`verifyPlanExecutionLease`) and the
+ * L1 checklist runs (`l1PreDispatchCheck` with the control checkout);
+ * the context must then match the verified lease exactly. Without an
+ * active lease (no row, or a non-InProgress row without lease), the
+ * standalone branch policy applies (`assertBranchAlignment`) — an
+ * InProgress row without lease is the orphan refusal.
+ *
+ * Throws `SddScriptError` — exit 2 when the declared context itself is
+ * malformed (non-absolute path, identity/composition mismatch, missing plan
+ * file), exit 1 when the environment fails the gate (missing dirs, branch
+ * mismatch, lease/orphan refusal, symlink escape). A rejected context never
+ * reaches an action check.
+ */
+export declare function resolveSddExecutionContext(input: SddExecutionContext): SddExecutionContext;
+/**
+ * Gate one action seam against a resolved context (spec A3). Read-only —
+ * a refused action performs no write and the check itself never writes.
+ *
+ * - `kind: "source"` — the observed `cwd` must sit inside the feature
+ * worktree (nested directories allowed); a relative `target` resolves from
+ * that actual cwd. Targets outside the feature — traversal, absolute
+ * elsewhere, wrong-cwd, or symlink escape — are refused before mutation.
+ * - `kind: "artifact"` — the `target` must stay inside the plan's control
+ * `sddDir` or equal the declared `planFile`; legitimate control artifact
+ * edits are allowed while arbitrary control source edits are not. A
+ * nonexistent leaf canonicalizes through its nearest existing ancestor
+ * (`canonicalizeNearestExisting`); symlink escapes are refused.
+ * - `kind: "launch"` — verifies the resolved launch destination
+ * `featureCwd` (exists + on `workingBranch` via the reused
+ * `assertBranchAlignment`); the parent's own cwd is not gated, because a
+ * launch may legitimately run from control/main — its purpose is to bind
+ * the child's starting cwd to the feature worktree. An optional `target`
+ * is checked as a source target relative to `featureCwd` (where the child
+ * will start).
+ *
+ * Violations minted here carry the `sdd.context.*` prefix; violations from
+ * the reused branch/lease helpers keep their own codes (`worktree.*`,
+ * `lease.*`, `plan-path.*`) — the rules stay single-sourced. A3 limits
+ * apply: this is a snapshot check, not a future-write lock, and offers no
+ * protection against a concurrent hostile symlink swap.
+ *
+ * API contract (task-1 review Minor 2): `context` must be a
+ * `resolveSddExecutionContext`-produced (or equivalently already-validated)
+ * context. This function gates the action seam only and does NOT
+ * re-validate the context declaration — identity, branch, lease and
+ * control/feature nesting checks run at resolve time — so a hand-assembled
+ * structurally-valid context gets no protection claim from this check
+ * alone.
+ */
+export declare function checkSddAction(context: SddExecutionContext, action: SddAction): GateResult;
+/**
+ * Bound argv launcher (spec A3):
+ * resolve + gate the context, then spawn a DIRECT executable argv — never
+ * a shell (no command-string interpolation; the argv array reaches the
+ * child literally, spaces/`$()`/backticks unchanged) — with
+ * cwd = the resolved feature worktree, inherited stdio and the inherited
+ * process environment unchanged (no HOME/CODEX_HOME edits, no credential
+ * copies). The parent's own cwd is deliberately not gated: a launch may
+ * run from control/main, and the `launch` seam validates the resolved
+ * launch destination (featureCwd + workingBranch) instead.
+ *
+ * Exit contract (Task 2 CLI mapping):
+ * - empty/invalid argv → `SddScriptError` exit 2 (usage);
+ * - context/gate failure → `SddScriptError` exit 1 (usage-class declaration
+ * errors from resolution keep their own exit 2);
+ * - spawn-not-found (ENOENT) → resolves 127;
+ * - numeric child exit → resolved unchanged (exit 7 returns 7);
+ * - child killed by signal n → resolves 128+n (SIGTERM → 143, SIGINT → 130).
+ *
+ * SIGINT/SIGTERM are forwarded to the running child; the listeners are
+ * removed once the child settles — the launcher leaves no handlers behind.
+ *
+ * A3 limits apply unchanged: the launcher binds the child's STARTING cwd;
+ * it is not a sandbox — a child can later chdir, pass an overriding cwd
+ * flag, write absolute paths elsewhere, or use host edit tooling. Other
+ * spawn errors (e.g. EACCES) reject; the CLI maps them to exit 1 with the
+ * cause in the message.
+ */
+export declare function runInSddContext(context: SddExecutionContext, argv: readonly string[]): Promise<number>;