@mstar-harness/dsh 2.1.1

package/dist/gates/catalog.d.ts

@@ -0,0 +1,118 @@
+import { type Context } from '@deepseek-ai/cordis';
+import { type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { PreStepDecision } from '@deepseek-ai/dsh-agent';
+import type { MstarEngineStatusSource } from '../types.ts';
+import { HarnessResolver } from './_shared.ts';
+/** Default catalog cache refresh interval (ms) — see Config `catalogTtlMs`. */
+export declare const DEFAULT_CATALOG_TTL_MS = 60000;
+/** Catalog cache key for the explicit-`harnessDir` app-wide entry (one entry for every session). */
+export declare const EXPLICIT_CACHE_KEY = "\0explicit";
+/** One TTL cache entry: the unified source plus the build timestamp. */
+export interface CatalogCacheEntry {
+    sources: MstarEngineStatusSource;
+    builtAt: number;
+}
+/**
+ * The apply-scoped `harnessDir → cache key` reverse map + invalidation
+ * closure (plan `20260811-panel-f4-timeliness` Task 2, decision D3): the
+ * catalog cache is keyed by {@link EXPLICIT_CACHE_KEY} or the session cwd,
+ * while ledger records (dispatch/settle) identify the affected workspace by
+ * `{HARNESS_DIR}` — the reverse map bridges the two so a ledger change
+ * deletes EXACTLY the affected workspace's entry (no global clear; a
+ * multi-workspace deployment does not rebuild every workspace). BOTH the map
+ * and the closure are created per-apply by the entry (same lifetime as the
+ * cache): module-level state would survive an HMR fiber restart and point at
+ * a destroyed cache.
+ */
+export interface CatalogInvalidation {
+    /**
+     * Register `key` as the cache key of `harnessDir` — called by
+     * `catalogSourcesFor` on cache hit AND build, and pre-registered by the
+     * entry at apply for the explicit-config boot entry (a ledger record
+     * between apply and the first pre-step must still invalidate the
+     * pre-seeded entry). A null harness dir (no `{HARNESS_DIR}` resolved) has
+     * no cache entry to invalidate → no-op.
+     */
+    register(harnessDir: string | null, key: string): void;
+    /**
+     * Delete the cache entry of `harnessDir` (D3 — the ledger record path
+     * invokes this through the apply-bound hook). A missing mapping is a safe
+     * no-op, and a missing entry after a previous invalidation is a no-op too
+     * (the next pre-step rebuilds regardless). A throwing invalidation is
+     * contained by the record path (log-only — it never blocks the ledger
+     * record).
+     */
+    invalidate(harnessDir: string): void;
+}
+/** Create the apply-scoped invalidation bound to ONE catalog cache (entry-internal wiring — see {@link CatalogInvalidation}). */
+export declare function createCatalogInvalidation(cache: Map<string, CatalogCacheEntry>): CatalogInvalidation;
+/**
+ * Build the unified catalog source for one harness dir (boot for the
+ * explicit config, first-use per workspace otherwise, then TTL-refreshed —
+ * see `catalogSourcesFor`). Logs the manifest fallback once per build — a
+ * '0.0.0' version would watermark every catalog row wrongly, so the
+ * fallback is never silent.
+ * @param ctx - registrant context (logger for the manifest fallback).
+ * @param harnessDir - the resolved `{HARNESS_DIR}` (null when none found).
+ */
+export declare function buildCatalogSources(ctx: Context, harnessDir: string | null): MstarEngineStatusSource;
+/**
+ * Advisory `agent/pre-step` waterfall listener (agent
+ * catalog): delegates through `next()` (never `reject` — that would block the
+ * step — and never replaces the delegated messages) and appends the ONE
+ * unified `mstar-engine-status` catalog message to the composed step
+ * messages, so the durable session log carries it (model-visible ⟺ logged,
+ * MessageSource form): the `<mstar_engine_status>` block renders the
+ * watermark fields (version, harness dir, enforcement), plus the iteration
+ * phase-gate section when a steering compass + status.json resolve, plus
+ * the workspace-state digest section when the workspace has a status.json.
+ *
+ * Digest-gated re-emission (the documented P3 dedup, landed early): per
+ * agent+workspace, the row is injected ONCE per turn — later steps of the
+ * same turn append it again only when its rendered text CHANGED (a TTL
+ * refresh picked up new state). The durable session log therefore carries
+ * the row on the first step of every turn plus each change, not on every
+ * step; a 20-step turn shows the catalog once, not 20 times.
+ *
+ * An aborted step publishes nothing: the delegated decision
+ * is returned unchanged (tool-skill precedent; a narrowed abort race —
+ * an abort after delegation must not surface as a turn failure).
+ *
+ * Error containment: the append path is wrapped — a failure
+ * (e.g. a downstream decider returning a non-iterable `messages` set, or a
+ * throwing message factory) logs and returns the delegated decision
+ * unchanged; the advisory listener never aborts the very step it observes.
+ *
+ * simplify: dev-time stub — the digest is in-memory per app (the real
+ * dsh-session log is unavailable at dev time; digest state resets on
+ * fiber disposal, which is also HMR-correct).
+ * @param ctx - registrant context (logger for the containment path).
+ * @param resolver - the per-workspace `{HARNESS_DIR}` resolver (the probe
+ * never starts from the process cwd).
+ * @param explicitKey - the app-wide cache key when an explicit
+ * `harnessDir` config is set (undefined → per-session-cwd keys).
+ * @param cache - per-workspace TTL catalog sources cache (boot pre-seeded
+ * for the explicit-config case; otherwise built on first use of each
+ * workspace root and TTL-refreshed — Config `catalogTtlMs`).
+ * @param ttlMs - catalog refresh interval in milliseconds.
+ * @param register - the apply-scoped `harnessDir → cache key` reverse-map
+ * registration (plan `20260811-panel-f4-timeliness` Task 2 — keeps every
+ * workspace's entry invalidatable by a ledger change; see
+ * `createCatalogInvalidation`).
+ * @param digests - per agent+workspace turn digests (last rendered text)
+ * for the digest-gated re-emission.
+ * @param payload - the proposed step the loop is about to enter.
+ * @param next - the remaining pre-step chain; its value is the delegated decision.
+ */
+export declare function preStepCatalogListener(ctx: Context, resolver: HarnessResolver, explicitKey: string | undefined, cache: Map<string, CatalogCacheEntry>, ttlMs: number, register: (harnessDir: string | null, key: string) => void, digests: Map<string, TurnDigest>, payload: {
+    agent: unknown;
+    messages: UserMessage[];
+    turn: number;
+    step: number;
+    signal: AbortSignal;
+}, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>;
+/** Per agent+workspace turn digest: the rendered catalog text as of the last injection. */
+export interface TurnDigest {
+    turn: number;
+    text: string;
+}

package/dist/gates/dispatch.d.ts

@@ -0,0 +1,152 @@
+import { type Context } from '@deepseek-ai/cordis';
+import type { AssignmentFields, GateResult, ValidationResult } from '@mstar-harness/engine';
+import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools';
+import { HarnessResolver } from './_shared.ts';
+import type { Config } from './_shared.ts';
+import type { DshHostAdapter } from './adapter.ts';
+/** Logger label for the dispatch gate (dsh logger naming: `<scope>/<subject>`). */
+export declare const DISPATCH_LOGGER = "mstar/dispatch-gate";
+/**
+ * Default delegation tool names the dispatch gate matches (tool-subagent
+ * default id). Exported SHARED with the agent-flow settle pairing
+ * (`registerSettleListener` matches the same tool set — plan
+ * `20260811-panel-f4-timeliness` Task 1) so the default cannot drift between
+ * the gate and the settle seam.
+ */
+export declare const DEFAULT_DISPATCH_TOOLS: readonly ["subagent"];
+/**
+ * Advisory emitted on warn-mode dispatch-gate passes (the * `mstar/status-gate` decision reused for the dispatch gate — dsh's
+ * `agent/status` lifecycle event stays untouched). Consumers (later tasks,
+ * catalogs) observe this event for model-visible/session-log surfacing.
+ */
+export interface DispatchGateAdvisory {
+    /** The matched delegation tool name. */
+    tool: string;
+    /** The Assignment's declared `Execute as` ('' when missing). */
+    role: string;
+    /** The gate verdict (warn-mode: `hardBlocked` is false). */
+    result: GateResult;
+    /** Whether hard enforcement is on (advisory events are warn-mode by construction). */
+    hard: boolean;
+    /** True when the gate errored internally and degraded to allow (structured degraded advisory). */
+    degraded?: boolean;
+}
+/**
+ * True when the text looks like an Assignment (opencode parity: `## Assignment`
+ * heading or at least one core field line). Non-Assignment delegation prompts
+ * stay silent — no false-positive warnings. Callers MUST pass the engine
+ * `assignmentHeaderRegion` slice: a `## Assignment` heading or
+ * field line quoted in the task body must not shape a non-assignment prompt.
+ * Exported for the agent-flow ledger's shape guard (qc2 F-2 — the shared
+ * `DshHostAdapter.dispatchGate` core applies the SAME guard on both dispatch
+ * surfaces, so the exec-less host-hook path records nothing for
+ * non-Assignment text either).
+ */
+export declare function isAssignmentShaped(assignmentText: string): boolean;
+/**
+ * Resolve the hard-enforcement flag for one dispatch: explicit Config override
+ * wins, else the Assignment's OWN `Enforcement: hard` header flag (opencode
+ * parity — header region only, a body-quoted example never hardens), else the
+ * iteration compass frontmatter, else warn-only.
+ */
+export declare function resolveDispatchHard(harnessDir: string | null, config: Config, assignmentText: string): boolean;
+/** A header value that means "no value" (placeholder conventions). Type guard so callers narrow to `string`. Shared with the agent-flow ledger (qc1 F-003 — one grammar, no copy-paste drift). */
+export declare function isNaValue(value: string | undefined): value is undefined;
+/**
+ * Resolve the target plan id from the Assignment HEADER region: `Plan Path`
+ * basename (`.md` stripped), else `SDD dir` basename, else a `plan_id` field.
+ * Exported for the agent-flow ledger's dispatch derivation (the ledger
+ * records the same plan identity the gate resolved — one grammar).
+ * @param headerRegion - `assignmentHeaderRegion(assignmentText)` (
+ * only the header is read — a plan path quoted in the task body never
+ * resolves a plan id).
+ */
+export declare function planIdOf(headerRegion: string): string | undefined;
+/**
+ * The dispatching session's stable id, when the seam exposes it (dsh
+ * Agent.id). Exported for the agent-flow ledger's dispatch derivation (the
+ * ledger records the same agent identity the lease gate compares — one
+ * grammar).
+ */
+export declare function sessionIdOf(exec: ToolExecution): string | undefined;
+/**
+ * Lease gate — ADDITIVE beyond the opencode parity field set:
+ * opencode's `validateDispatchAssignment` does NOT run lease checks at
+ * dispatch, so every violation emitted here is dsh-only and clearly scoped:
+ * the check fires ONLY for WRITABLE dispatches whose Assignment declares
+ * `Execution mode: sdd` (engine `executionModeToN` semantics — sdd maps to
+ * N=3; the function's violation path is intentionally unused so
+ * `dispatch.execution-mode.*` codes stay out of the parity field set) OR
+ * whose plan row is `InProgress`.
+ *
+ * Contract (status-and-residuals.md § Pre-dispatch re-verify): before any
+ * writable implement dispatch, reread `{HARNESS_DIR}/status.json` and confirm
+ * the session still passes verify-held-lease — `holder`, `worktree_path` and
+ * `working_branch` must match the Assignment; mismatch or absent lease →
+ * STOP. Engine `verifyPlanExecutionLease` + `validateExecutionLease` carry
+ * the presence/shape checks (missing / orphan / dual-write / non-ssot /
+ * invalid fields); the dispatch-context comparisons (holder vs the
+ * dispatching session, worktree and branch vs the Assignment) are dsh-side.
+ *
+ * Degrade-allow cases (no false positives): no harness dir, unresolvable plan
+ * id, and non-SDD assignments whose plan row is absent or not InProgress.
+ * Unverifiable lease states (malformed status.json, MISSING status.json, plan
+ * row not registered) are violations ONLY for sdd dispatches (the lease state
+ * cannot be confirmed — the status gate already guards the next write);
+ * unreadable docs never harden a soft workflow. Missing status.json is NOT a
+ * silent fail-open for sdd: the claim-before-InProgress red line
+ * needs the plan's execution_lease, and a missing status file cannot confirm
+ * it — `lease.dispatch.unverifiable` fires (advisory in warn, deny under hard).
+ */
+export declare function leaseGateViolations(harnessDir: string | null, exec: ToolExecution, writable: boolean | undefined, prompt: string): ValidationResult[];
+/**
+ * The dispatch-gate validation core — the engine's SINGLE dispatch-gate
+ * composition (`dispatch.composeDispatchGate`, opencode/omp/CLI parity — the
+ * SAME composition, so violation codes are identical by construction): shape
+ * guard + field gate (read-only roles skip the branch gate) +
+ * anti-recursion precheck (Config binding) + default-branch gate +
+ * header-region enforcement. The dsh-side additions layer ON TOP: the
+ * worktree L1/L2 checks (additive beyond opencode parity; the
+ * lease gate is exec-bound and joins via {@link DshHostAdapter.dispatchGate}).
+ * Extracted from `gateDispatch` so the `tools/pre-execute` listener and the
+ * host adapter's `beforeDispatch` share ONE code path.
+ *
+ * Header-region scoping: the engine `assignmentHeaderRegion`
+ * slice is computed ONCE and feeds the composition AND the worktree parsers
+ * (fields, branch forms, direct-on exception, worktree tracks) — body-quoted
+ * field examples after a `# Task` / `# Target` / `---` marker never leak
+ * into the header fields the gate validates (the same discipline
+ * enforcement / plan-id / lease already honor). Well-formed assignments
+ * (fields in the header) slice to the full text, so their verdicts are
+ * unchanged. The composition never throws: unexpected failures degrade to
+ * the silent non-shaped result.
+ *
+ * @returns the violations plus the writable flag (false for read-only
+ * roles — the listener feeds it to the lease gate).
+ */
+export declare function dispatchGateCore(config: Config, harnessDir: string | null, prompt: string): {
+    violations: ValidationResult[];
+    writable: boolean | undefined;
+};
+/**
+ * `tools/pre-execute` listener. The waterfall refusal channel is the returned
+ * decision: a deny is returned WITHOUT calling `next()` (short-circuits the
+ * chain — downstream listeners and the registry default never run); every
+ * other path calls `next()` to delegate (the registry's default is
+ * `{ kind: 'allow' }`). Engine failures degrade to allow in BOTH modes (hard
+ * gates are opt-in — an engine failure must not harden a workflow that was
+ * soft; opencode parity) but the degrade is NEVER silent: the
+ * catch path emits the plugin-owned `mstar/dispatch-gate` advisory with
+ * `degraded: true` + an error log, so a hard deployment can detect a dead
+ * control instead of only finding it in logs. `next()` itself is invoked
+ * outside the guard so a downstream rejection propagates untouched.
+ */
+export declare function preExecuteListener(ctx: Context, resolver: HarnessResolver, config: Config, adapter: DshHostAdapter, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>;
+/**
+ * Rebuild the canonical Assignment HEADER text from parsed fields (the
+ * engine's OWN header grammar — `parseAssignmentFields` reads exactly these
+ * labels — so the engine parsers round-trip losslessly). The host hook's
+ * engine-typed input is `AssignmentFields`; the shared gate core validates
+ * assignment TEXT, so the fields form is normalized to text before gating.
+ */
+export declare function assignmentTextFromFields(fields: AssignmentFields): string;

package/dist/gates/seams.d.ts

@@ -0,0 +1,152 @@
+import { type Context } from '@deepseek-ai/cordis';
+import type { GateResult, SecretFinding, ValidationResult } from '@mstar-harness/engine';
+import type { FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs';
+import { HarnessResolver } from './_shared.ts';
+import type { Config } from './_shared.ts';
+/** The four artifact seams (design-md / audit / compound / roles). */
+export type SeamId = 'design-md' | 'audit' | 'compound' | 'roles';
+/**
+ * Advisory emitted on seam-gate decisions (the `mstar/status-gate` /
+ * `mstar/skill-lint` advisory pattern reused for the design-md / audit /
+ * compound / roles artifact gates — one event with a `seam` discriminator,
+ * consumers filter on it). Emitted when an in-scope artifact write-intent
+ * finds violations in the pre-write on-disk document (warn mode), when hard
+ * mode allows an ALREADY-invalid document as a repair escape, and when the
+ * gate degrades to allow after an unexpected internal error. Clean passes
+ * stay silent.
+ *
+ * The gate NEVER throws on the listener path (status-gate repair-escape
+ * semantics): the intent waterfall carries no incoming content, so the only
+ * lint signal is the pre-write on-disk state; the typed hard veto lives on
+ * the known-document branch (`lintSeamWrite` + friends, `SeamVetoError`).
+ */
+export interface SeamLintAdvisory {
+    /** The artifact seam that decided this intent. */
+    seam: SeamId;
+    /** Which intent slot passed the gate (write-intent only — no linted edit slot). */
+    operation: 'write';
+    /** `displayPath` of the guarded file. */
+    target: string;
+    /** The gate verdict (warn-mode: `hardBlocked` false; hard repair escape: `hardBlocked` true). */
+    result: GateResult;
+    /** Resolved enforcement flag: false for warn-mode advisories, true for hard-mode repair escapes. */
+    hard: boolean;
+    /** True when hard mode allowed a write to an ALREADY-invalid document (repair escape). */
+    repair?: boolean;
+    /** True when the gate errored internally and degraded to allow (error-containment envelope). */
+    degraded?: boolean;
+}
+/**
+ * Validate a DESIGN.md / DESIGN.dark.md document: token frontmatter plus
+ * light/dark parity against the on-disk sibling when it exists (parity is
+ * inherently cross-file — the sibling is read at validation time; a dark
+ * write with no light sibling skips parity). Shared by the content-blind
+ * listener and the known-document branch.
+ */
+export declare function validateDesignDoc(doc: string, path: string): GateResult;
+/**
+ * Validate an audit plan document: Status-block contract + secret scan.
+ * The findings summary (line + type only — mstar-audit Hard Rule 4 never
+ * reproduces secret values) rides along for the validate tool's `secrets`
+ * output field; the gate path reads only `ok`/`violations`.
+ */
+export declare function validateAuditDoc(doc: string, path: string): GateResult & {
+    findings: SecretFinding[];
+};
+/**
+ * Validate a knowledge doc: schema.yaml frontmatter contract + referenced
+ * path/module existence. The repo root for `referenceExists` is derived as
+ * the parent of `{HARNESS_DIR}` — the plan-conventions discovery layout
+ * always places the harness dir directly under the repo root
+ * (`<repo>/.mstar`, `<repo>/.agents`, `<repo>/plans`).
+ * simplify: single-level harness layout — revisit if a nested harness root
+ * becomes an observed deployment.
+ */
+export declare function validateCompoundDoc(doc: string, _path: string, harnessDir: string | null): GateResult;
+/**
+ * Validate the mstar-roles skill-dir state: role mapping / parameter tables
+ * against the on-disk references layout, plus load-order declarations
+ * across every sibling `mstar-*` skill (unreadable sibling SKILL.md files
+ * are skipped — best-effort reads for a lint that must never take the gate
+ * down). The `skillsRoot` override exists for the validate tool (its
+ * explicit `skills_root` parameter); the gate path keeps the default
+ * (the parent of the roles dir).
+ * @param rolesDir - the mstar-roles skill directory.
+ * @param skillsRoot - directory scanned for sibling `mstar-*` skills
+ * (default: `dirname(rolesDir)`).
+ */
+export declare function validateRolesState(rolesDir: string, skillsRoot?: string): GateResult;
+/**
+ * `fs/write-intent` listener for one seam gate. Registered with `prepend`
+ * for the same reachability reason as the status gate: the slot is
+ * first-wins by registration order (dsh-fs-policy README), so without
+ * prepend a policy plugin mounted earlier would make this gate unreachable.
+ * Every gate decision (warn advisory, repair escape, degraded allow) calls
+ * `next()` — the seam gates never own the intent decision and must not
+ * terminate the chain (fs-policy's observed-state CAS stays live in
+ * composed deployments).
+ */
+export declare function seamWriteIntentListener(ctx: Context, resolver: HarnessResolver, config: Config, seam: SeamId, target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>;
+/**
+ * Typed hard-mode veto for the seam gates (the dsh fs-policy veto channel:
+ * "veto = throw"; the write tool turns the throw into an isError tool
+ * result carrying `{ name, code }`). Thrown ONLY by {@link lintSeamWrite} —
+ * the entry that lints a KNOWN incoming document (the brief's "hard veto
+ * via throw where the slot semantics allow" branch). The content-blind
+ * `fs/write-intent` listeners never throw: they cannot distinguish a repair
+ * from a re-violation, so hard mode degrades to the repair escape there
+ * (see {@link gateSeamIntent}).
+ */
+export declare class SeamVetoError extends Error {
+    /** Stable code for tool-result serialization (the `{ name, code }` convention). */
+    readonly code: "seam.veto";
+    /** The seam whose gate vetoed the write. */
+    readonly seam: SeamId;
+    /** The violations that caused the veto. */
+    readonly violations: readonly ValidationResult[];
+    constructor(seam: SeamId, target: string, violations: readonly ValidationResult[]);
+}
+/**
+ * Enforce one seam's lints over a KNOWN document (the brief's "incoming
+ * doc when available" branch): `Enforcement: hard` + violations → throw the
+ * typed {@link SeamVetoError} (fs-policy veto channel); warn mode → return
+ * the gate for advisory logging. A repairing write carries a VALID incoming
+ * document and passes by construction — no repair escape is needed on this
+ * branch. The content-blind listener paths (where the incoming doc is never
+ * visible) route through {@link gateSeamIntent} instead, which applies the
+ * repair-escape decision.
+ * @param seam - the artifact seam whose validator runs.
+ * @param doc - the document about to be written (roles: ignored — the
+ * validator checks the whole mstar-roles dir state).
+ * @param options - target display path (veto message) + resolved hard flag
+ * + the plugin harness dir (compound reference checks; null-tolerant).
+ */
+export declare function lintSeamWrite(seam: SeamId, doc: string, options: {
+    target: string;
+    hard: boolean;
+    harnessDir?: string | null;
+}): GateResult;
+/** {@link lintSeamWrite} bound to the design-md seam. */
+export declare function lintDesignMdWrite(doc: string, options: {
+    target: string;
+    hard: boolean;
+    harnessDir?: string | null;
+}): GateResult;
+/** {@link lintSeamWrite} bound to the audit seam. */
+export declare function lintAuditWrite(doc: string, options: {
+    target: string;
+    hard: boolean;
+    harnessDir?: string | null;
+}): GateResult;
+/** {@link lintSeamWrite} bound to the compound seam. */
+export declare function lintCompoundWrite(doc: string, options: {
+    target: string;
+    hard: boolean;
+    harnessDir?: string | null;
+}): GateResult;
+/** {@link lintSeamWrite} bound to the roles seam. */
+export declare function lintRolesWrite(doc: string, options: {
+    target: string;
+    hard: boolean;
+    harnessDir?: string | null;
+}): GateResult;

package/dist/gates/skill-lint.d.ts

@@ -0,0 +1,87 @@
+import { type Context } from '@deepseek-ai/cordis';
+import type { GateResult, ValidationResult } from '@mstar-harness/engine';
+import type { FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs';
+import { HarnessResolver } from './_shared.ts';
+import type { Config } from './_shared.ts';
+/**
+ * Advisory emitted on skill-lint gate decisions (the `mstar/status-gate`
+ * advisory pattern reused for the skill-authoring gate). Emitted
+ * when a `SKILL.md` write-intent under a configured skill root finds lint
+ * violations in the pre-write on-disk document (warn mode), when hard mode
+ * allows an ALREADY-invalid document as a repair escape, and when the gate
+ * degrades to allow after an unexpected internal error. Clean passes stay
+ * silent.
+ *
+ * The gate NEVER throws on the listener path (status-gate repair-escape
+ * semantics): the intent waterfall carries no incoming content, so the only
+ * lint signal is the pre-write on-disk state; the typed hard veto lives on
+ * the incoming-document branch (`lintSkillWrite`, `SkillLintVetoError`).
+ */
+export interface SkillLintAdvisory {
+    /** Which intent slot passed the gate (write-intent only — skills have no linted edit slot). */
+    operation: 'write';
+    /** `displayPath` of the guarded SKILL.md. */
+    target: string;
+    /** Canonical skill-root form of the target (`resolveSkillRoot('dsh', …)` form). */
+    canonical: string;
+    /** The lint verdict (warn-mode: `hardBlocked` false; hard repair escape: `hardBlocked` true). */
+    result: GateResult;
+    /** Resolved enforcement flag: false for warn-mode advisories, true for hard-mode repair escapes. */
+    hard: boolean;
+    /** True when hard mode allowed a write to an ALREADY-invalid document (repair escape). */
+    repair?: boolean;
+    /** True when the gate errored internally and degraded to allow (error-containment envelope). */
+    degraded?: boolean;
+}
+/**
+ * Typed hard-mode veto for the skill lint gate (the dsh fs-policy veto
+ * channel: "veto = throw"; the write tool turns the throw into an isError
+ * tool result carrying `{ name, code }`). Thrown ONLY by
+ * {@link lintSkillWrite} — the entry that lints a KNOWN incoming document
+ * (the brief's "against the incoming doc when available" branch). The
+ * content-blind `fs/write-intent` listener never throws: it cannot
+ * distinguish a repair from a re-violation, so hard mode degrades to the
+ * status-gate repair escape there (see {@link gateSkillIntent}).
+ */
+export declare class SkillLintVetoError extends Error {
+    /** Stable code for tool-result serialization (the `{ name, code }` convention). */
+    readonly code: "skill-lint.veto";
+    /** The lint violations that caused the veto. */
+    readonly violations: readonly ValidationResult[];
+    constructor(target: string, violations: readonly ValidationResult[]);
+}
+/**
+ * Lint one SKILL.md document with the engine skill-authoring lints
+ * (`lintFrontmatter` + `lintFiveQuestion` — the CLI `mstar skill lint`
+ * combination; violation codes `lint.frontmatter.*` /
+ * `skill-authoring.five-question.*`). Pure: no enforcement, no I/O.
+ * @param doc - the full SKILL.md text.
+ */
+export declare function lintSkillDoc(doc: string): GateResult;
+/**
+ * Enforce the skill-authoring lints over a KNOWN document (the brief's
+ * "incoming doc when available" branch): `Enforcement: hard` + violations →
+ * throw the typed {@link SkillLintVetoError} (fs-policy veto channel); warn
+ * mode → return the gate for advisory logging. A repairing write carries a
+ * VALID incoming document and passes by construction — no repair escape is
+ * needed on this branch. The content-blind listener path (where the
+ * incoming doc is never visible) routes through {@link gateSkillIntent}
+ * instead, which applies the status-gate repair-escape decision.
+ * @param doc - the document about to be written (the write's content).
+ * @param options - target display path (veto message) + resolved hard flag.
+ */
+export declare function lintSkillWrite(doc: string, options: {
+    target: string;
+    hard: boolean;
+}): GateResult;
+/**
+ * `fs/write-intent` listener for the skill lint gate. Registered with
+ * `prepend` for the same reachability reason as the status gate: the slot
+ * is first-wins by registration order (dsh-fs-policy README), so without
+ * prepend a policy plugin mounted earlier would make this gate unreachable.
+ * Every gate decision (warn advisory, repair escape, degraded allow) calls
+ * `next()` — the skill lint gate never owns the intent decision and must
+ * not terminate the chain (fs-policy's observed-state CAS on skill files
+ * stays live in composed deployments).
+ */
+export declare function skillWriteIntentListener(ctx: Context, resolver: HarnessResolver, config: Config, target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>;

package/dist/gates/status.d.ts

@@ -0,0 +1,81 @@
+import { type Context } from '@deepseek-ai/cordis';
+import type { GateResult } from '@mstar-harness/engine';
+import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs';
+import { HarnessResolver } from './_shared.ts';
+import type { Config } from './_shared.ts';
+import type { DshHostAdapter } from './adapter.ts';
+/**
+ * Advisory emitted on status-gate decisions (the plan's "emit `agent/status`
+ * (advisory)" step). Named `mstar/status-gate` instead: the dsh `agent/status`
+ * event is a lifecycle-only channel (`{ agent, status }`, idle ⇄ running, with
+ * an invariant rejecting no-op transitions) — emitting gate warnings on it
+ * would violate the seam contract. Consumers (later tasks, catalogs) observe
+ * this event for model-visible/session-log surfacing.
+ *
+ * The status gate NEVER throws: the fs intent waterfall
+ * carries no incoming content, so the only hard-mode decision this seam can
+ * make about an ALREADY-invalid document is to allow the write as a repair
+ * escape. Every decision surfaces through this advisory; unexpected internal
+ * errors degrade to an allow with `degraded: true`.
+ */
+export interface StatusGateAdvisory {
+    /** Which intent slot passed the gate. */
+    operation: 'write' | 'edit';
+    /** `displayPath` of the guarded file. */
+    target: string;
+    /** The gate verdict (warn-mode: `hardBlocked` false; hard repair escape: `hardBlocked` true). */
+    result: GateResult;
+    /** Resolved enforcement flag: false for warn-mode advisories, true for hard-mode repair escapes. */
+    hard: boolean;
+    /** True when hard mode allowed a write/edit to an ALREADY-invalid document (repair escape). */
+    repair?: boolean;
+    /** True when the gate errored internally and degraded to allow (error-containment envelope). */
+    degraded?: boolean;
+}
+/**
+ * Validate a PARSED status document through the status-gate pipeline
+ * (engine `validateStatus` + `findingsCleanupGate` per plan row that
+ * CONFIGURES a mode). Shared by {@link validateStatusDoc} (the on-disk
+ * single-read path) and the host adapter's `beforeStatusWrite` (the
+ * incoming document) — the fs-intent gate, the adapter hook and the repair
+ * escape all surface the SAME violation codes.
+ */
+export declare function validateStatusValue(doc: unknown): GateResult;
+/**
+ * Run the status gate over the CURRENT on-disk document. The fs intent
+ * waterfall carries only `(target, actor)` — never the incoming content — so
+ * the vetoable check is the pre-write state (the opencode hook's fallback for
+ * the same reason). `findingsCleanupGate` runs per plan row that CONFIGURES a
+ * mode (`plans[].metadata.findings_cleanup`); schema violations short-circuit
+ * it (the doc must parse for the cleanup gate to be meaningful).
+ *
+ * Single-read contract: the file is parsed exactly once and the
+ * parsed doc is passed to {@link validateStatusValue} — the previous
+ * path-first read then `readJson` re-read was a TOCTOU window (a concurrent
+ * writer between the two reads threw a raw error from inside the gate).
+ * Malformed JSON is contained here with the engine's `status.invalid-json`
+ * shape; never throws. Missing files are guarded by the callers
+ * (`gateStatusIntent`, {@link DshHostAdapter.statusGate}) — first create has
+ * no document to validate and passes before this function runs.
+ */
+export declare function validateStatusDoc(statusPath: string): GateResult;
+/**
+ * `fs/write-intent` listener. Registered with `prepend` so this decider runs
+ * BEFORE dsh-fs-policy regardless of mount order: the slot is first-wins by
+ * registration order (dsh-fs-policy README), so without prepend a policy
+ * plugin mounted earlier would make this gate unreachable. Every gate
+ * decision (warn advisory, repair escape, degraded allow) calls `next()` —
+ * delegating the observed-state intent decision to the remaining chain
+ * (fs-policy when mounted; the bare `undefined` default otherwise) rather
+ * than terminating the slot with `undefined` (which would silently disable
+ * fs-policy's CAS for status.json in composed deployments).
+ */
+export declare function writeIntentListener(ctx: Context, resolver: HarnessResolver, config: Config, adapter: DshHostAdapter, target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>;
+/** `fs/edit-intent` listener — same gate and delegation contract as {@link writeIntentListener}. */
+export declare function editIntentListener(ctx: Context, resolver: HarnessResolver, config: Config, adapter: DshHostAdapter, target: FsTarget, actor: object | undefined, next: () => {
+    version: FsVersion;
+} | undefined | Promise<{
+    version: FsVersion;
+} | undefined>): Promise<{
+    version: FsVersion;
+} | undefined>;

package/dist/gates/tools.d.ts

@@ -0,0 +1,37 @@
+import { type Context } from '@deepseek-ai/cordis';
+import { HarnessResolver } from './_shared.ts';
+/**
+ * Register the v2 seam model-facing tools: `mstar sdd …` / `mstar iteration gate` equivalents operating
+ * in-app against control-path artifacts.
+ *
+ * The registrations are deferred with `ctx.inject(['tools'], …)` — the same
+ * optional-unit pattern as dsh-tool-todo — so the plugin boots without the
+ * tools service (gates stay active) and registers when the composed dsh app
+ * provides `ctx.tools`. The fs-mutating tools declare
+ * `isConcurrencySafe: () => false` (exclusive — never overlap with sibling
+ * calls, matching the real registry's exclusive default).
+ * @param ctx - registrant context carrying the tool registry.
+ * @param resolver - the per-workspace `{HARNESS_DIR}` resolver (the tools
+ * resolve per the calling session's workspace — never the process cwd;
+ * explicit config wins).
+ */
+export declare function registerSddIterationTools(ctx: Context, resolver: HarnessResolver): void;
+/**
+ * Register the on-demand seam validation tools (
+ * 20260808-dsh-seams-bundle): `mstar design-md validate` / `mstar compound
+ * validate` CLI mirrors plus the audit / roles validators — thin wrappers
+ * running the engine in-app. The registrations are deferred with
+ * `ctx.inject(['tools'], …)` (same optional-unit pattern as the sdd tools),
+ * so the plugin boots without the tools service (gates stay active).
+ *
+ * `mstar_compound_validate` adds one `repo_root` param beyond the CLI
+ * (`mstar compound validate` has no reference-existence check) — the
+ * compound-refresh Phase 2 check the seam gate runs per write, offered
+ * on-demand. All tools are read-only evaluations — exclusive anyway
+ * (registry default; the engine results are pure functions of the docs).
+ * @param ctx - registrant context carrying the tool registry.
+ * @param resolver - the per-workspace `{HARNESS_DIR}` resolver (the
+ * compound default root resolves per the calling session's workspace —
+ * never the process cwd; explicit config wins).
+ */
+export declare function registerSeamTools(ctx: Context, resolver: HarnessResolver): void;