@llman-sdd/core 0.7.0 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {

package/src/archive/freeze.ts

@@ -147,6 +147,8 @@ export async function runList(io: FreezeIo, sz: SevenZipPort, rootAbs: string):
   if (io.exists(archiveAbs)) {
     // Legacy/unexpected entries present only inside the 7z (no card on disk).
     const entries = (await sz.listEntries(archiveAbs)).map((n) => n.replace(/\/$/u, ''));
+    // 7z entry names always use '/' per archive contract — POSIX by contract, not
+    // platform-native; do not switch to node:path here.
     const top = (n: string): string => n.split('/')[0] ?? n;
     for (const e of entries.map(top).filter((n) => DATED_RE.test(n))) {
       if (!names.has(e)) names.add(e);

package/src/change/lifecycle.ts

@@ -5,7 +5,9 @@ import {
   defaultBranch,
   dirtyCount,
   isCleanTree,
+  localBranchExists,
   mergeBase,
+  probeForkSource,
   revParseHead,
   worktreeList,
   type GitLike,
@@ -64,11 +66,42 @@ export function newChange(
 export interface StartResult {
   branch: string;
   baseBranch: string;
+  /** Where the recorded base_branch came from (r95 deviation warning input). */
+  baseSource: 'flag' | 'worktree' | 'default';
   baseSha: string;
   /** Absolute worktree path when started with --worktree (r68); undefined on the classic path. */
   worktreePath?: string;
 }
 
+/** r95: where attach's recorded base_branch came from. */
+export type AttachBaseSource = 'flag' | 'config' | 'upstream' | 'default';
+
+export interface AttachResult {
+  branch: string;
+  baseBranch: string;
+  baseSource: AttachBaseSource;
+  baseSha: string;
+}
+
+/** r95: shared --base gate — local branches only (finalize cannot switch to a
+ * remote-tracking ref; recording one is an end-to-end dead end). */
+function assertLocalBase(
+  git: GitLike,
+  base: string,
+  forbidden: string,
+  kind: 'new' | 'bound',
+): void {
+  if (!localBranchExists(git, base)) {
+    throw new LifecycleError(
+      `base branch \`${base}\` does not exist as a local branch; --base must name a local branch ` +
+        '(remote-tracking refs are rejected — use the local branch name)',
+    );
+  }
+  if (base === forbidden) {
+    throw new LifecycleError(`--base must differ from the ${kind} branch \`${forbidden}\``);
+  }
+}
+
 /**
  * r68 worktree path (design D2): `<root>/<repo-basename>-<name>` where root is
  * `sdd.worktree_root` (absolute, or repo-root-relative; default = the repo
@@ -84,6 +117,8 @@ function resolveWorktreePath(
   naming: 'id' | 'hash' | undefined,
 ): string {
   const toplevel = git.run(['rev-parse', '--show-toplevel']);
+  // git rev-parse --show-toplevel emits forward-slash paths even on win32
+  // (git-for-Windows normalizes) — POSIX by contract; keep '/'-splitting.
   const cut = toplevel.lastIndexOf('/');
   const basename = toplevel.slice(cut + 1);
   const name =
@@ -145,29 +180,23 @@ export function startChange(
   const branch = `${branchPrefix}${id}`;
 
   if (opts.base !== undefined) {
-    if (
-      git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${opts.base}`]) === null &&
-      git.runOpt(['show-ref', '--verify', '--quiet', `refs/remotes/${opts.base}`]) === null
-    ) {
-      throw new LifecycleError(
-        `base branch \`${opts.base}\` does not exist; --base records the fork source branch for merge-target resolution`,
-      );
-    }
-    if (opts.base === branch) {
-      throw new LifecycleError(`--base must differ from the new branch \`${branch}\``);
-    }
+    assertLocalBase(git, opts.base, branch, 'new');
   }
 
   // r68 fork-source resolution: --base explicit > current branch (worktree
   // mode records the actual source, which may be a non-default branch) >
   // default branch. The classic path keeps the r14 default-branch gate.
   let baseBranch: string;
+  let baseSource: StartResult['baseSource'];
   if (opts.base !== undefined) {
     baseBranch = opts.base;
+    baseSource = 'flag';
   } else if (opts.worktree) {
     baseBranch = here;
+    baseSource = 'worktree';
   } else {
     baseBranch = defaultBranch(git);
+    baseSource = 'default';
     if (here !== baseBranch) {
       throw new LifecycleError(
         `already on non-default branch \`${here}\`; use \`change attach\` to bind it, or switch to the default branch before \`change start\``,
@@ -199,13 +228,13 @@ export function startChange(
     }
     const baseSha = mergeBase(gitAt(git, worktreePath), 'HEAD', baseBranch);
     wtIo.writeText(path, writeBinding(wtIo.readText(path), { branch, baseBranch, baseSha }));
-    return { branch, baseBranch, baseSha, worktreePath };
+    return { branch, baseBranch, baseSource, baseSha, worktreePath };
   }
   git.run(['switch', '-c', branch]);
   const baseSha =
     currentBranch(git) !== null ? mergeBase(git, 'HEAD', baseBranch) : revParseHead(git);
   io.writeText(path, writeBinding(io.readText(path), { branch, baseBranch, baseSha }));
-  return { branch, baseBranch, baseSha };
+  return { branch, baseBranch, baseSource, baseSha };
 }
 
 /** `change attach`: bind the current branch — same branch gate family as start (r31). */
@@ -214,7 +243,7 @@ export function attachChange(
   io: FsIo,
   id: string,
   opts: { force?: boolean; base?: string } = {},
-): { branch: string; baseBranch: string; baseSha: string } {
+): AttachResult {
   const path = proposalPath(id);
   if (!io.exists(path)) throw new LifecycleError(`proposal not found: ${path}`);
   const existing = readBinding(io.readText(path));
@@ -223,35 +252,31 @@ export function attachChange(
       `change \`${id}\` already attached to branch \`${existing.branch}\` (base ${existing.baseSha}); pass --force to rebind`,
     );
   }
-  const configuredBase = opts.base ?? defaultBranch(git);
   const branch = currentBranch(git);
   if (branch === null || branch === '') {
     throw new LifecycleError(detachedHead('change attach'));
   }
   if (opts.base !== undefined) {
-    if (
-      git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${opts.base}`]) === null &&
-      git.runOpt(['show-ref', '--verify', '--quiet', `refs/remotes/${opts.base}`]) === null
-    ) {
-      throw new LifecycleError(
-        `base branch \`${opts.base}\` does not exist; --base records the fork source branch for merge-target resolution`,
-      );
-    }
-    if (opts.base === branch) {
-      throw new LifecycleError(`--base must differ from the bound branch \`${branch}\``);
-    }
+    assertLocalBase(git, opts.base, branch, 'bound');
   }
-  if (branch === configuredBase) {
+  // r95 fork-source resolution: --base explicit > probeForkSource
+  // (branch.<name>.base > local upstream) > default branch. No signal means
+  // status quo (issue #7 compatibility: "无法推导维持现状").
+  const fork =
+    opts.base !== undefined
+      ? { branch: opts.base, source: 'flag' as const }
+      : (probeForkSource(git, branch) ?? {
+          branch: defaultBranch(git),
+          source: 'default' as const,
+        });
+  if (branch === fork.branch) {
     throw new LifecycleError(
       `${onDefaultBranch('change attach', branch)}; create or switch to a feature branch, or use \`change start\``,
     );
   }
-  const baseSha = mergeBase(git, branch, configuredBase);
-  io.writeText(
-    path,
-    writeBinding(io.readText(path), { branch, baseBranch: configuredBase, baseSha }),
-  );
-  return { branch, baseBranch: configuredBase, baseSha };
+  const baseSha = mergeBase(git, branch, fork.branch);
+  io.writeText(path, writeBinding(io.readText(path), { branch, baseBranch: fork.branch, baseSha }));
+  return { branch, baseBranch: fork.branch, baseSource: fork.source, baseSha };
 }
 
 export interface FinalizeResult {
@@ -387,14 +412,25 @@ function mergeRenameCommit(
     execIo = ioAt(io, holder);
     executedIn = holder;
   }
+  // r96: in-place close-out — merging a branch into itself is always a no-op
+  // ("Already up to date."), so skip the merge and say so instead of running a
+  // silent self-merge. The switch still runs (a no-op when already there) so
+  // escape hatches like `archive --force` from a foreign branch land the
+  // rename and close-out commit on the bound branch, not the current one.
   execGit.run(['switch', target]);
-  const mergeArgs =
-    method === 'ff' ? ['merge', '--ff-only', featureBranch] : ['merge', '--squash', featureBranch];
-  if (execGit.runOpt(mergeArgs) === null) {
-    execGit.runOpt(['merge', '--abort']);
-    warnings.push(
-      `merge ${method} failed — resolve manually, e.g. \`git merge ${method === 'ff' ? '--ff-only' : '--squash'} ${featureBranch}\``,
-    );
+  if (target === featureBranch) {
+    warnings.push('in-place close-out: merge target is the bound branch itself; merge skipped');
+  } else {
+    const mergeArgs =
+      method === 'ff'
+        ? ['merge', '--ff-only', featureBranch]
+        : ['merge', '--squash', featureBranch];
+    if (execGit.runOpt(mergeArgs) === null) {
+      execGit.runOpt(['merge', '--abort']);
+      warnings.push(
+        `merge ${method} failed — resolve manually, e.g. \`git merge ${method === 'ff' ? '--ff-only' : '--squash'} ${featureBranch}\``,
+      );
+    }
   }
 
   const date = today;

package/src/config/schema.ts

@@ -26,7 +26,7 @@ export const specsSchema = z.object({
     .string()
     .nullish()
     .describe(
-      'Spec verification command executed by validate for spec targets (skip with --no-check). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once). Legacy `bdd.run_command` is elevated onto this key at load time.',
+      'Spec verification command executed by validate for spec targets (opt-in via --check; default skips). Placeholders: {feature_path}, {feature_dir}, {feature_name}; without placeholders it runs once per validate invocation (batch-once). Legacy `bdd.run_command` is elevated onto this key at load time.',
     ),
   verify_prompt: z.string().nullish().describe('Extra prompt text injected during verify phase.'),
 });

package/src/git/spawnGit.ts

@@ -54,12 +54,27 @@ export function isCleanTree(git: GitLike): boolean {
   return git.run(['status', '--porcelain']) === '';
 }
 
-/** Local-first default branch resolution: main → master → origin/HEAD → origin/*. */
+/** True when the named LOCAL branch (refs/heads/<name>) exists. */
+export function localBranchExists(git: GitLike, name: string): boolean {
+  return git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null;
+}
+
+/**
+ * Local-first default branch resolution: init.defaultBranch (only when it
+ * names an existing local branch) → main → master → origin/HEAD → origin/*.
+ * A valid preference wins outright — including over an existing local main
+ * (r16 resolution order, not a tie-breaker) — because the user explicitly
+ * configured it; anything else falls through to the chain untouched.
+ */
 // Deliberately NOT shared with defaultBranchNameFn() in validation/staleness.ts
 // (that probe is local-only with a 'main' fallback — predecessor staleness parity). Do not merge.
 export function defaultBranch(git: GitLike): string {
+  const preferred = git.runOpt(['config', '--get', 'init.defaultBranch']);
+  if (preferred !== null && preferred !== '' && localBranchExists(git, preferred)) {
+    return preferred;
+  }
   for (const candidate of ['main', 'master']) {
-    if (git.runOpt(['show-ref', '--verify', '--quiet', `refs/heads/${candidate}`]) !== null) {
+    if (localBranchExists(git, candidate)) {
       return candidate;
     }
   }
@@ -78,6 +93,32 @@ export function defaultBranch(git: GitLike): string {
   );
 }
 
+export interface ForkSource {
+  branch: string;
+  source: 'config' | 'upstream';
+}
+
+/**
+ * r95: read-only fork-source probes for attach — explicit signals only, local
+ * branches only. Order: `branch.<name>.base` (stacked-PR tool convention, the
+ * value must name an existing local branch) > local upstream
+ * (branch.<name>.remote = "." → @{upstream} resolves to refs/heads/*). A
+ * remote-tracking upstream is the branch's own push destination, not a fork
+ * source. null means "not derivable" — the caller falls back to defaultBranch.
+ */
+export function probeForkSource(git: GitLike, branch: string): ForkSource | null {
+  const configured = git.runOpt(['config', '--get', `branch.${branch}.base`]);
+  if (configured !== null && configured !== branch && localBranchExists(git, configured)) {
+    return { branch: configured, source: 'config' };
+  }
+  const upstream = git.runOpt(['rev-parse', '--symbolic-full-name', `${branch}@{upstream}`]);
+  if (upstream !== null && upstream.startsWith('refs/heads/')) {
+    const name = upstream.slice('refs/heads/'.length);
+    if (name !== branch) return { branch: name, source: 'upstream' };
+  }
+  return null;
+}
+
 export function revParseHead(git: GitLike): string {
   return git.run(['rev-parse', 'HEAD']);
 }

package/src/index.ts

@@ -1,5 +1,3 @@
-export * from './ports.ts';
-
 export {
   EXTRA_SKILLS,
   archiveSchema,
@@ -136,14 +134,17 @@ export {
   GitError,
   defaultBranch,
   isCleanTree,
+  localBranchExists,
   makeSpawnGit,
   currentBranch,
   worktreeList,
   probeMainCheckout,
+  probeForkSource,
   nonMainCheckoutWarning,
   type GitLike,
   type WorktreeEntry,
   type MainCheckoutProbe,
+  type ForkSource,
 } from './git/spawnGit.ts';
 export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId } from './change/id.ts';
 export { parseTaskCheckboxes, type ParsedTaskCheckboxes } from './change/tasks.ts';
@@ -164,6 +165,8 @@ export {
   finalizeChange,
   newChange,
   startChange,
+  type AttachBaseSource,
+  type AttachResult,
   type FinalizeResult,
   type FsIo,
   archiveChange,

package/src/spec/migrateNative.ts

@@ -141,8 +141,7 @@ export function migrateNativeSource(source: string): MigrateResult {
   for (const b of blocks) {
     if (!b.isRule) continue;
     rules++;
-    out.push(`  @req:${b.reqIds[0] ?? ''}`);
-    out.push(`  ${kw.rule}: ${b.title}`);
+    out.push(`  @req:${b.reqIds[0] ?? ''}`, `  ${kw.rule}: ${b.title}`);
     for (const line of b.descriptionLines) {
       const text = stripBullet(line);
       if (text !== '') out.push(`    ${text}`);

package/src/spec/parser.ts

@@ -96,7 +96,8 @@ function extractHeader(source: string): CapabilityHeader {
 }
 
 interface RawTags {
-  names: string[]; // without leading '@'
+  // Tag names are stored here without the leading '@'.
+  names: string[];
   reqId: string;
 }
 

package/src/validation/harness.ts

@@ -57,6 +57,8 @@ export interface HarnessRunOutcome {
 
 /** Plain-text placeholder expansion — capability ids are kebab-constrained. */
 export function expandRunCommand(command: string, target: HarnessTarget): string {
+  // featurePath is a repo-relative spec path (llmanspec/specs/x.feature), POSIX by
+  // contract on every host — keep '/'-splitting, do not switch to node:path here.
   const dirEnd = target.featurePath.lastIndexOf('/');
   const featureDir = dirEnd === -1 ? target.featurePath : target.featurePath.slice(0, dirEnd);
   return command
@@ -74,7 +76,7 @@ interface CacheEntry {
 const OUTPUT_TAIL = 200;
 
 /**
- * Trigger matrix (r13): --no-check skips silently; a nested invocation skips
+ * Trigger matrix (r13): default skips; a nested invocation skips
  * with a per-spec INFO; an explicit --check without a configured check_command
  * yields a single INFO on the first spec; otherwise every expanded command
  * executes at most once (cache keyed by the expanded string).

package/templates/en/skills/llman-sdd-apply.md

@@ -75,9 +75,16 @@ Run the project gates as appropriate:
 - Edit `llmanspec/specs/<capability>.feature` on the branch as needed (flat or directory main file; canonical native layout: `@req:<id>` on the `规则:` block header, nested `场景:` as executable examples); run `llman-sdd validate --specs` after spec edits; commit on the branch freely.
 - SDD validation: `llman-sdd validate <id> --strict`
 
+**Verification ladder (opt-in discipline, escalate by cost)**:
+- L1 minimal unit: `bun test tests/unit/<relevant>` (<1s, direct import), covers only the current change point.
+- L2 targeted behavior: `bun test tests/bdd -t "<scenario/rule title pattern>"` — exercises only the relevant real-CLI path.
+- L3 explicit full harness: `llman-sdd validate --check` (with `specs.check_command` configured; plain `validate` no longer runs the harness).
+- L4 close-out backstop: `change finalize` runs the real harness pre-merge — at least one full run per close-out.
+- Self-heal loops default to L1/L2 for fast reproduction; use L3 only when full-acceptance evidence is needed; avoid paying full-suite cost needlessly.
+
 **Gate evidence**:
-- Close-out runs the configured `specs.check_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
-- Gate verdicts MUST come from the real harness: MUST NOT obtain a "pass" via `--no-check`; on harness failure, find the root cause first (leaked env vars, nested-invocation guards, wrong cwd …) — MUST NOT label it an "inherent/self-referential property" and bypass it.
+- Plain `validate` is structure/state-only and claims no harness evidence; harness evidence MUST come from explicit `--check` or close-out acceptance.
+- Gate verdicts MUST come from the real harness: claiming a harness pass requires `--check` (or close-out); the default structural gate is not a pass; on harness failure, find the root cause first (leaked env vars, nested-invocation guards, wrong cwd …) — MUST NOT label it an "inherent/self-referential property" and bypass it.
 - Before/after criteria (counts, baselines) MUST be measured on the change branch (against the freshly computed merge-base); a value measured on the default branch is usually trivially the baseline and proves nothing.
 - Refactors and bulk replacements: MUST compare the test count before and after; all-green gates with fewer tests is a failure.
 

package/templates/en/skills/llman-sdd-archive.md

@@ -7,7 +7,7 @@ metadata:
 
 # LLMAN SDD Archive
 
-Archive completed changes. Prerequisites: verify all-green, and the change is branch-bound with specs landed (or `needs_specs_change: false`). `change finalize` **auto-merges** into the base branch (target: `--into` > binding `base_branch` > default branch; method: `--method` > config `sdd.merge_method`, squash by default — feature diff + rename collapse into ONE commit on the target), **renames** change docs into `changes/archive/`, then **auto-commits** `archive(sdd): <change-id>` (`--no-commit` skips). `git push` / PR are optional.
+Archive completed changes. Prerequisites: verify all-green, and the change is branch-bound with specs landed (or `needs_specs_change: false`). `change finalize` **auto-merges** into the base branch (target: `--into` > binding `base_branch` > default branch; when the target is the bound branch itself the merge is skipped for an in-place close-out with a notice in the output; method: `--method` > config `sdd.merge_method`, squash by default — feature diff + rename collapse into ONE commit on the target), **renames** change docs into `changes/archive/`, then **auto-commits** `archive(sdd): <change-id>` (`--no-commit` skips). `git push` / PR are optional.
 
 ## Pipeline Position
 

package/templates/en/skills/llman-sdd-explore.md

@@ -46,7 +46,7 @@ flowchart LR
    - Write decisions back: resolved decisions go into the change's `proposal.md` "Open Questions" section.
    - Completion criterion: every pending decision is resolved or explicitly deferred. When not triggered, the default (ask 1–3 questions) behavior is unchanged.
 4. If a change id is relevant, read its artifacts under `llmanspec/changes/<id>/`.
-   - When diagnosing validation errors, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `specs.check_command` is configured, validate executes that harness by default (`--no-check` skips it). Failing items are pinned down in the default TOON output's `items[].issues[]`; `--output human` prints `FAIL <item_type>/<id>` lines.
+   - When diagnosing validation errors, run `llman-sdd validate <spec> --strict` first for the structural gates (Gherkin / `@req` linkage / dual-write / req_id uniqueness); when `specs.check_command` is configured, validate only executes that harness with explicit `--check` (default skips). Failing items are pinned down in the default TOON output's `items[].issues[]`; `--output human` prints `FAIL <item_type>/<id>` lines.
 5. Explore options and tradeoffs (2–3 options).
 6. Assess change scale to determine if full SDD is needed.
 7. When something crystallizes, offer to capture it (don't auto-write):

package/templates/en/skills/llman-sdd-propose.md

@@ -72,7 +72,7 @@ If the user just wants to **capture an idea** ("draft a proposal", "note down X"
 - Flesh out `proposal.md` (Why / What Changes / Capabilities / Impact); write `design.md` only when tradeoffs/migrations matter.
 - **Confirm seams before writing tasks.md**: list the seams to be tested and confirm with the user. A seam = the public boundary driven by `*.feature` GWT steps (CLI subprocess or public interface) — MUST reuse existing harness seams, MUST NOT invent seams detached from `.feature`; without `.feature`, the seam is the CLI subcommand or public function boundary under test.
 - `tasks.md`: split into **vertical slices** (each task cuts a narrow but complete path through schema→API→UI→tests, independently verifiable), with `[blocked-by: <task-id>]` dependency markers. **Wide-refactor exception** (one mechanical change sweeping the codebase, a single edit breaking many call sites): sequence as expand-contract (add new beside old → migrate call sites in batches → delete old); don't force vertical slices. **tasks.md lists implementation and verification tasks only**: close-out (`change finalize` / `change archive`) is a pipeline step and MUST NOT be listed as a task — its task gate requires every task checked, so a close-out task is self-contradictory (checking it lies, leaving it blocks close-out, and `validate --strict` stays red during implementation). Before/after completion criteria (counts, baselines) MUST state they are measured on the change branch (against merge-base) — a value taken on the default branch is usually trivially the baseline.
-- **First** `llman-sdd change start <change-id>` (recommended; clean tree on the default branch; `--worktree` to keep the current checkout, `--base <branch>` for a non-default fork source) or manually create a branch then `change attach <change-id>`.
+- **First** `llman-sdd change start <change-id>` (recommended; clean tree on the default branch; `--worktree` to keep the current checkout, `--base <branch>` (local branches only) for a non-default fork source) or manually create a branch then `change attach <change-id>` (attach derives the fork source from runtime signals by default and warns on deviation).
 - **Then** edit `llmanspec/specs/<capability>.feature` (flat, or directory `llmanspec/specs/<capability>/` main file) on the bound non-default branch and commit (land specs). **Do not** edit specs before start; **do not** commit specs to the default branch just to satisfy the clean-tree gate. If already attached, do not re-run `start` (recover lost specs by checkout/recreate + `attach --force`).
 - For changes with no contract edits, set frontmatter `needs_specs_change: false`. Enter apply when `llman-sdd show <id> --output json` shows `stage=full` with the specs-landed gate green; `readyToImplement=true` (all gates) is the completion signal gating verify/finalize.
 - **Breaking contract changes** (removed/renamed fields, commands, tags, or stage values) MUST plan the upgrade path: write a `migrations/v<from>-v<to>/README` (upgrade guidance; a one-shot script SHALL ship with the repo when feasible) — include it in the proposal's What Changes.
@@ -85,7 +85,7 @@ This MUST pass before proceeding; failing items are listed one by one in the val
 
 ### 4a) Optional BDD runner (`specs:` block)
 - Read `llmanspec/config.yaml`. Is there a `specs:` block?
-  - **Yes**: `specs.check_command` declares the project's BDD execution entry; validate executes it by default when its target set includes specs (`--no-check` skips). Authoring follows 4b regardless.
+  - **Yes**: `specs.check_command` declares the project's BDD execution entry; validate runs it only via explicit `--check` (default skips — structure-only). Authoring follows 4b regardless.
   - **No**: if this change involves executable behavior scenarios (Given/When/Then the user will want to run), ask **once, up front** whether to enable a `specs:` verification runner block (adds a `specs:` block to `config.yaml` — runner only, does not change the lifecycle). If **yes**: show the exact `specs:` block to add (pick a `check_command` matching the project's test framework — `cargo test --features bdd` for rstest-bdd, `pytest {feature_dir} -k {feature_name} -v` for pytest-bdd), let the user confirm or edit, write it to `config.yaml`, then proceed with 4b. If **no**: features still validate structurally; BDD execution responsibility stays with the project test suite.
 - **Do NOT silently add the `specs:` block** — always ask first. Adding it declares the project-wide BDD execution entry.
 

package/templates/en/skills/llman-sdd-validate.md

@@ -16,7 +16,7 @@ Validate change/spec format and staleness.
 3. **BDD checks**:
    - Validate `.feature` Gherkin and `@req` / dual-write gates on the **bound branch**; `.feature` is the harness authority — executable GWT lives only there.
    - Lifecycle gates: `change start` / `attach` (bind branch), `finalize` (close-out; auto commit `archive(sdd): <id>`, `--no-commit` to skip) / `diff` (read-only).
-   - `llman-sdd validate --specs` enforces structural and contract gates; when `specs.check_command` is configured it also executes that harness by default (`--no-check` skips it, `--check` is a compat alias); a placeholder-free command runs at most once per invocation.
+   - `llman-sdd validate --specs` enforces structural and contract gates; when `specs.check_command` is configured the full harness runs only with explicit `--check` (default skips — structure-only); a placeholder-free command runs at most once per invocation.
    - `list --specs --json` shows `morphology` (requirementCount / requirementBoundCount / requirementUnboundCount / acceptanceCount / featureScenarioCount).
    - Change JSON status fields: `stage` (draft/designed/planned/full) / `specsLanded` / `needsSpecsChange` / `readyToImplement` (`show --output json`).
 {% endif %}

package/templates/en/skills/llman-sdd-verify.md

@@ -25,8 +25,8 @@ flowchart LR
 
 - **Apply must be all-green first**: don't verify unimplemented changes.
 - **CRITICAL must be fixed**: zero CRITICAL before archive.
-- **Rerun the gates yourself**: MUST rerun `llman-sdd validate <id> --strict` (real harness) and the project gates; MUST NOT trust gate verdicts in the implementer's report — a mismatch is CRITICAL.
-- **`--no-check` is not evidence**: gate evidence obtained with `--no-check` → CRITICAL. Close-out runs the configured `specs.check_command`, so do not run that command again just before close-out; the skip line printed by `--no-check` is not a pass.
+- **Rerun the gates yourself**: MUST rerun `llman-sdd validate <id> --check --strict` (real harness evidence) and the project gates; MUST NOT trust gate verdicts in the implementer's report — a mismatch is CRITICAL.
+- **Harness evidence requires `--check`**: plain `validate` does not run the harness; claiming full-harness evidence MUST use explicit `--check` — the default structural gate is not a pass. Close-out runs the configured `specs.check_command`, so do not run it again just before close-out.
 - **Don't ask "should I continue?"**: run the full verification flow and output a complete report.
 
 {{ unit("skills/stage-guard") }}
@@ -34,7 +34,7 @@ flowchart LR
 ## Steps
 1. Select the change id (or ask the user to pick from `llman-sdd list --json`).
 2. Fast validation gate: `llman-sdd validate <id> --strict`.
-   - When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / req_id uniqueness), run the structural validation first (when `specs.check_command` is configured, validate executes that harness by default — `--no-check` skips it; a harness failure lands as an ERROR on its spec item). Failing items are listed one by one in the default TOON output's `items[].issues[]` (`--output human` prints `FAIL <item_type>/<id>` lines above the `Totals` line).
+   - When diagnosing structural issues (Gherkin parse / `@req` linkage / dual-write / req_id uniqueness), run the structural validation first (the full harness only runs via explicit `--check`; plain `validate` no longer runs it by default; a harness failure lands as an ERROR on its spec item). Failing items are listed one by one in the default TOON output's `items[].issues[]` (`--output human` prints `FAIL <item_type>/<id>` lines above the `Totals` line).
 3. Read: `llmanspec/specs/**` (`<capability>.feature`, the single source of truth) on the branch, `proposal.md` and `design.md` (if present), `tasks.md`; ignore residual old docs under `changes/<id>/specs/`.
 4. **Dual-axis review (kept separate so neither masks the other)** — diff against `git diff <merge-base>...HEAD` (merge-base is COMPUTED via `git merge-base <local-default> HEAD`; the stored base_sha is audit-only and MUST NOT feed range math):
    - **Spec axis**: does the implementation satisfy the `规则:` block requirement statement (free-text description, judged by its semantics) and the nested `场景:` GWT steps? Missing/partial behaviors, wrong implementations, and scope creep not asked for by the spec → suggest minimal fixes or artifact updates. Check where before/after evidence (counts, baselines) was taken: it MUST be measured on the change branch (against the freshly computed merge-base); a value measured on the default branch is usually trivially the baseline and proves nothing.
@@ -57,7 +57,7 @@ flowchart LR
    - The two axes may be reviewed in parallel (sub-agents); the report MUST present them separately, MUST NOT merge or cross-rerank (one axis passing must not mask the other failing).
 5. **BDD verification** — only when `config.yaml` has a `specs:` block:
    - Confirm the change is branch-bound and you are on that branch.
-   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; when `specs.check_command` is configured the harness runs by default (`--no-check` skips it) and a failure maps to an ERROR on the matching spec item.
+   - `llman-sdd validate --specs`: Gherkin + `@req`/dual-write gates; the full harness only runs via explicit `--check` (default skips) and a failure maps to an ERROR on the matching spec item.
    - Optional read-only review: `llman-sdd change diff <id>` (or `--export-patch <path>`) — review/export only, never an apply step.
    - Next step after verify passes: `llman-sdd-archive` (not inline finalize here).
 {% if specs_verify_prompt %}

package/templates/en/units/skills/git-native-flow-brief.md

@@ -7,4 +7,4 @@ Hard rules:
 2. No contract edits → `needs_specs_change: false`. Enter apply when `stage=full` and the specs-landed gate passes; `readyToImplement=true` (all gates green) is the completion signal gating verify/finalize.
 3. Close-out: `change finalize` (auto commit `archive(sdd): <id>`; `--no-commit` to skip).
 4. **Do not** commit specs on the default branch; if already attached, do not re-run `start`.
-5. Worktree (optional): `change start --worktree` creates the branch in a dedicated worktree without hijacking the current checkout (`--base <branch>` records a non-default fork source); finalize runs in place when the target is held by another worktree (location annotated in output).
+5. Worktree (optional): `change start --worktree` creates the branch in a dedicated worktree without hijacking the current checkout (`--base <branch>`, local branches only) records a non-default fork source; attach derives the fork source from runtime signals by default and warns on deviation from the default branch; finalize skips the merge for an in-place close-out when the target is the bound branch, and runs in place when the target is held by another worktree (location annotated in output).

package/templates/en/units/skills/git-native-flow.md

@@ -44,7 +44,7 @@ Worktree decision table:
 | Working style | Command | Criteria |
 |---|---|---|
 | Single checkout | `llman-sdd change start <id>` | On the default branch with a clean tree; switches this checkout to the new branch |
-| Keep current checkout / parallel changes | `llman-sdd change start <id> --worktree` | Branch lives in a dedicated worktree (`sdd.worktree_root` / `sdd.worktree_naming` config; default sibling of the repo root), current checkout untouched, output includes the worktree path; pair with `--base <branch>` for a non-default fork source |
-| Already on a feature branch (incl. manual wt/git-worktree) | `llman-sdd change attach <id>` | Branch already exists; `--base <branch>` records the fork source explicitly |
+| Keep current checkout / parallel changes | `llman-sdd change start <id> --worktree` | Branch lives in a dedicated worktree (`sdd.worktree_root` / `sdd.worktree_naming` config; default sibling of the repo root), current checkout untouched, output includes the worktree path; pair with `--base <branch>` (local branches only) for a non-default fork source |
+| Already on a feature branch (incl. manual wt/git-worktree) | `llman-sdd change attach <id>` | Branch already exists; fork source resolves as `--base` > `branch.<name>.base` / local upstream probe > default branch, with a WARNING when it deviates from the default; `--base` accepts local branches only |
 
-finalize target location: when the target branch is held by another worktree, `llman-sdd change finalize <id>` / `llman-sdd change archive <id>` run the merge, rename and commit inside that worktree (output includes `executed in target worktree <path>`); a dirty holding worktree aborts with disposal options and zero writes.
+finalize target location: when the target is the bound branch itself the merge is skipped for an in-place close-out (output carries an in-place close-out notice); when the target branch is held by another worktree, `llman-sdd change finalize <id>` / `llman-sdd change archive <id>` run the merge, rename and commit inside that worktree (output includes `executed in target worktree <path>`); a dirty holding worktree aborts with disposal options and zero writes.

package/templates/zh-Hans/skills/llman-sdd-apply.md

@@ -75,9 +75,16 @@ flowchart LR
 - 分支上按需编辑 `llmanspec/specs/<capability>.feature`（扁平或目录主文件；统一原生分层：`@req:<id>` 挂 `规则:` 块头、嵌套 `场景:` 为可执行示例），spec 改动后跑 `llman-sdd validate --specs`；分支上可自由提交。
 - SDD 校验：`llman-sdd validate <id> --strict`
 
+**验证阶梯（opt-in 纪律，按成本逐级扩大）**：
+- L1 最小单元：`bun test tests/unit/<相关>`（<1s，直接导入），仅覆盖当前改动点。
+- L2 定向行为：`bun test tests/bdd -t "<场景/规则标题模式>"`——只跑相关场景的真实 CLI 链路。
+- L3 显式全量：`llman-sdd validate --check`（配置 `specs.check_command` 时执行全量 harness；缺省 validate 不再执行 harness）。
+- L4 收口兜底：`change finalize` 预合并强制真实 harness——每次收口至少 1 次全量。
+- 自修复循环默认用 L1/L2 快速复现；只有需要全量验收时才 L3；避免无谓白付全量成本。
+
 **门禁证据**：
-- 收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
-- 门禁结论 MUST 来自真实 harness：MUST NOT 以 `--no-check` 取得「通过」；harness 失败 MUST 先查根因（环境变量泄漏、嵌套调用守卫、工作目录错误等），MUST NOT 以「固有/自指属性」定性后绕过。
+- 缺省 `validate` 只做结构/状态门，不声明 harness 证据；harness 证据 MUST 经显式 `--check` 或收口验收取得。
+- 门禁结论 MUST 来自真实 harness：声称 harness 合格时 MUST 已用 `--check`（或收口）；缺省结构门的通过不是通过；harness 失败 MUST 先查根因（环境变量泄漏、嵌套调用守卫、工作目录错误等），MUST NOT 以「固有/自指属性」定性后绕过。
 - 前后对比类判据（计数、基线）MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
 - 重构或批量替换类 task：MUST 对比改动前后测试用例数；门禁全绿但用例数下降视为失败。
 

package/templates/zh-Hans/skills/llman-sdd-archive.md

@@ -7,7 +7,7 @@ metadata:
 
 # LLMAN SDD 归档
 
-归档已完成的变更。前置：verify 全绿，且 change 已绑定分支、specs 已落地（或 `needs_specs_change: false`）。`change finalize` **自动合并**到基准分支（目标：`--into` > 绑定 `base_branch` > 默认分支；方式：`--method` > 配置 `sdd.merge_method`，默认 squash——feature diff + 改名收敛为目标分支单个 commit）、**改名** change 文档到 `changes/archive/`、**自动提交** `archive(sdd): <change-id>`（`--no-commit` 跳过）。`git push` / PR 仅可选。
+归档已完成的变更。前置：verify 全绿，且 change 已绑定分支、specs 已落地（或 `needs_specs_change: false`）。`change finalize` **自动合并**到基准分支（目标：`--into` > 绑定 `base_branch` > 默认分支；目标即绑定分支时跳过合并就地收口，输出含 in-place close-out 提示；方式：`--method` > 配置 `sdd.merge_method`，默认 squash——feature diff + 改名收敛为目标分支单个 commit）、**改名** change 文档到 `changes/archive/`、**自动提交** `archive(sdd): <change-id>`（`--no-commit` 跳过）。`git push` / PR 仅可选。
 
 ## Pipeline 位置
 

package/templates/zh-Hans/skills/llman-sdd-explore.md

@@ -46,7 +46,7 @@ flowchart LR
    - 决策回写：已解决的决策写进该 change 的 `proposal.md`「Open Questions」段。
    - 完成判据：每个待定决策都已解决或显式推迟。未触发时保持默认（问 1–3 个问题）。
 4. 涉及某个 change id 时，读 `llmanspec/changes/<id>/` 下的工件。
-   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `specs.check_command` 时 validate 缺省执行该 harness（`--no-check` 跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
+   - 诊断校验错误先跑 `llman-sdd validate <spec> --strict` 过结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性）；配置了 `specs.check_command` 时 validate 仅经显式 `--check` 执行该 harness（缺省跳过）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条指明；`--output human` 输出人读 `FAIL <item_type>/<id>` 行。
 5. 探索 2–3 个选项与权衡。
 6. 判断变更规模，确定是否走完整 SDD。
 7. 结论清晰时建议用户记录（勿自动写）：

package/templates/zh-Hans/skills/llman-sdd-propose.md

@@ -72,7 +72,7 @@ flowchart LR
 - 充实 `proposal.md`（Why / What Changes / Capabilities / Impact）；仅当有权衡/迁移时写 `design.md`。
 - **写 tasks.md 前确认测试边界（seam）**：列出要测的 seam 并与用户确认。seam = 由 `*.feature` GWT 步骤驱动的公共边界（CLI 子进程或公共接口）——MUST 复用既有 harness seam，MUST NOT 脱离 `.feature` 凭空发明；没有 `.feature` 时，seam = 被测的 CLI 子命令或公共函数边界。
 - `tasks.md` 按**垂直切片**拆（每个 task 打穿 schema→API→UI→tests 一条窄而完整的路径，可独立验证），带 `[blocked-by: <task-id>]` 依赖标记。**大范围重构例外**（一个机械改动扫全库、单点编辑牵动大量调用处）：按先加后删排序（新的加在旧的旁边 → 分批迁移调用处 → 删旧的），不强拆垂直切片。**tasks.md 只列实现与验证任务**：收口（`change finalize` / `change archive`）是流水线步骤，MUST NOT 列为任务——收口的任务门要求全部任务已勾，列了必然自相矛盾（勾选即虚报、不勾则收口被拒，实施期 `validate --strict` 永红）。前后对比类完成判据（计数、基线）MUST 注明在 change 分支上测量（相对 merge-base）——默认分支测得的值通常恒为基线。
-- **先** `llman-sdd change start <change-id>`（推荐；默认分支上工作树干净时；保留当前检出用 `--worktree`，非默认分叉源用 `--base <branch>`）或手动建分支后 `change attach <change-id>`。
+- **先** `llman-sdd change start <change-id>`（推荐；默认分支上工作树干净时；保留当前检出用 `--worktree`，非默认分叉源用 `--base <branch>`（仅本地分支））或手动建分支后 `change attach <change-id>`（attach 缺省按运行时信号推导分叉源，偏离默认分支时输出 WARNING）。
 - **再**在绑定的非默认分支编辑 `llmanspec/specs/<capability>.feature`（扁平，或目录 `llmanspec/specs/<capability>/` 内主文件）并 commit（落地 specs）。**不要**在 start 前改 specs；**不要**为过干净树门禁把 specs commit 到默认分支。已 attach 勿重复 `start`（specs 丢失用 checkout/重建 + `attach --force` 恢复）。
 - 无合约编辑的 change 设 frontmatter `needs_specs_change: false`。`llman-sdd show <id> --output json` 显示 `stage=full` 且 specs-landed 门通过即可进 apply；`readyToImplement=true`（全门）是 verify/finalize 的完成信号。
 - **破坏性合约变更**（移除/重命名字段、命令、tag 或 stage 值域）MUST 规划升级路径：`migrations/v<from>-v<to>/` 下写 README（升级提示；一次性脚本可行时随仓库提供）——写进提案 What Changes。
@@ -85,7 +85,7 @@ MUST 通过才能继续；失败项在 validate 输出的 `items[].issues[]` 逐
 
 ### 4a) 可选 BDD runner（`specs:` 段）
 - 读 `llmanspec/config.yaml` 是否含 `specs:` 段：
-  - **有**：`specs.check_command` 是项目的 BDD 执行入口；validate 在目标集含 spec 时缺省执行它（`--no-check` 跳过）。撰写仍按 4b。
+  - **有**：`specs.check_command` 是项目的 BDD 执行入口；validate 仅在显式 `--check` 时执行它（缺省跳过，仅结构/状态门）。撰写仍按 4b。
   - **无**：若本次 change 含可执行行为场景（用户会想运行的 Given/When/Then），**一次性前置**询问是否启用 `specs:` 验证 runner 段（会向 `config.yaml` 加一个 `specs:` 段——仅 runner，不改生命周期）。**是**：展示要加的精确 `specs:` 段（`check_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`），用户确认或修改后写入 `config.yaml`，再按 4b 继续。**否**：feature 仍做结构校验；BDD 执行责任始终在项目测试套件。
 - **MUST NOT 静默添加 `specs:` 段**——总是先问。添加它会向全项目声明 BDD 执行入口。
 

package/templates/zh-Hans/skills/llman-sdd-validate.md

@@ -16,7 +16,7 @@ metadata:
 3. **Spec 校验**：
    - 在**绑定分支**上验证 `.feature` Gherkin 与 `@req` / 双写门禁；`.feature` 是 harness 权威——可执行 GWT 只在其中维护。
    - 生命周期门禁：`change start` / `attach`（绑定分支）、`finalize`（收口；自动提交 `archive(sdd): <id>`，`--no-commit` 跳过）/ `diff`（只读）。
-   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `specs.check_command` 时缺省执行该 harness（`--no-check` 跳过，`--check` 为兼容别名），无占位符的命令每次调用至多执行一次。
+   - `llman-sdd validate --specs` 做结构与合约门禁；配置 `specs.check_command` 时全量 harness 仅经显式 `--check` 执行（缺省跳过，仅结构/状态门），无占位符的命令每次调用至多执行一次。
    - `list --specs --json` 查看 `morphology`（requirementCount / requirementBoundCount / requirementUnboundCount / acceptanceCount / featureScenarioCount）。
    - change JSON 状态字段：`stage`（draft/designed/planned/full）/ `specsLanded` / `needsSpecsChange` / `readyToImplement`（`show --output json`）。
 {% endif %}

package/templates/zh-Hans/skills/llman-sdd-verify.md

@@ -25,8 +25,8 @@ flowchart LR
 
 - **必须先 apply 全绿**：未完成实现的 change 跳过验证。
 - **CRITICAL 必须修复**：归档前清零。
-- **亲自复跑门禁**：MUST 亲自重跑 `llman-sdd validate <id> --strict`（真实 harness）与项目门禁，MUST NOT 采信实现者报告的门禁结论；复跑结果与报告不符 → CRITICAL。
-- **`--no-check` 不是证据**：以 `--no-check` 取得的门禁证据 → CRITICAL。收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍；`--no-check` 打出的跳过说明不是通过。
+- **亲自复跑门禁**：MUST 亲自重跑 `llman-sdd validate <id> --check --strict`（真实 harness 证据）与项目门禁，MUST NOT 采信实现者报告的门禁结论；复跑结果与报告不符 → CRITICAL。
+- **harness 证据必须 `--check`**：缺省 `validate` 不执行 harness，声称全量 harness 证据 MUST 经显式 `--check`（缺省结构门的通过不是通过）；收口会执行已配置的 `specs.check_command`，收口前不必再跑一遍。
 - **不要问「要不要继续」**：跑完整验证流程，输出完整报告。
 
 {{ unit("skills/stage-guard") }}
@@ -34,7 +34,7 @@ flowchart LR
 ## 步骤
 1. 确定 change id（不明确时让用户从 `llman-sdd list --json` 选）。
 2. 快速校验门禁：`llman-sdd validate <id> --strict`。
-   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（配置 `specs.check_command` 时 validate 缺省执行该 harness，`--no-check` 跳过；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
+   - 诊断结构问题（Gherkin 解析 / `@req` 链接 / 双写 / req_id 唯一性）先跑结构校验（全量 harness 仅经显式 `--check` 执行，缺省不再自动执行；harness 失败以 ERROR 落在对应 spec 条目）。失败项在缺省 TOON 输出的 `items[].issues[]` 逐条列出（`--output human` 输出 `FAIL <item_type>/<id>` 行，位于 `Totals` 上方）。
 3. 阅读：分支上的 `llmanspec/specs/**`（`<capability>.feature`，唯一事实来源）、`proposal.md` 与 `design.md`（如有）、`tasks.md`；`changes/<id>/specs/` 若有残留旧文档可忽略。
 4. **双轴审查（两轴分离，互不掩盖）**——对比 diff（`git diff <merge-base>...HEAD`，merge-base 现算 `git merge-base <本地默认分支> HEAD`；存储的 base_sha 仅审计、MUST NOT 参与范围计算）：
    - **合约轴**：实现是否满足 `规则:` 块的需求表述(描述为自由文本,以其语义为准)与嵌套 `场景:` 的 GWT 步骤？缺失/部分实现、错误实现、spec 未要求的超范围改动 → 给最小修复建议或建议更新工件。前后对比类证据（计数、基线）核对测量位置：MUST 在 change 分支上测量（相对现算 merge-base）；默认分支测得的值通常恒为基线，不构成证据。
@@ -57,7 +57,7 @@ flowchart LR
    - 两轴可并行（sub-agent）审查；报告 MUST 分离呈现，MUST NOT 合并或交叉重排（一轴通过不能掩盖另一轴失败）。
 5. **Spec 验证**——仅当 `config.yaml` 含 `specs:` 段：
    - 确认 change 已绑定分支且当前在该分支上。
-   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；配置 `specs.check_command` 时缺省执行该 harness（`--no-check` 跳过），失败映射为对应 spec 条目的 ERROR。
+   - `llman-sdd validate --specs`：Gherkin + `@req`/双写门禁；全量 harness 仅经 `--check` 显式执行（缺省跳过），失败映射为对应 spec 条目的 ERROR。
    - 可选只读审查：`llman-sdd change diff <id>`（或 `--export-patch <path>`）——仅审查/导出，绝不当作 apply 步骤。
    - verify 通过后下一步 `llman-sdd-archive`（勿在此 inline finalize）。
 {% if specs_verify_prompt %}

package/templates/zh-Hans/units/skills/git-native-flow-brief.md

@@ -7,4 +7,4 @@
 2. 无合约编辑 → `needs_specs_change: false`。`stage=full` 且 specs-landed 门通过即可进 apply；`readyToImplement=true`（全门绿）是 verify/finalize 前的完成信号。
 3. 收口用 `change finalize`（自动提交 `archive(sdd): <id>`；`--no-commit` 跳过）。
 4. **禁止**在默认分支 commit specs；已 attach 勿重复 `start`。
-5. worktree（可选）：`change start --worktree` 在独立 worktree 建分支、不动当前检出（`--base <branch>` 记录分叉源）；finalize 目标被其他 worktree 持有时自动在该 worktree 内执行（输出标注位置）。
+5. worktree（可选）：`change start --worktree` 在独立 worktree 建分支、不动当前检出（`--base <branch>` 仅本地分支）记录分叉源；attach 缺省按运行时信号推导分叉源、偏离默认分支时输出 WARNING；finalize 目标即绑定分支时跳过合并就地收口，目标被其他 worktree 持有时自动在该 worktree 内执行（输出标注位置）。

package/templates/zh-Hans/units/skills/git-native-flow.md

@@ -44,7 +44,7 @@ Worktree 决策表：
 | 工作形态 | 命令 | 判据 |
 |---|---|---|
 | 单检出 | `llman-sdd change start <id>` | 在默认分支且树干净；直接切到新分支 |
-| 保留当前检出 / 并行 change | `llman-sdd change start <id> --worktree` | 分支建于独立 worktree（`sdd.worktree_root` / `sdd.worktree_naming` 可调，缺省仓库根兄弟目录），当前检出不动，输出含 worktree 路径；配 `--base <branch>` 记录非默认分叉源 |
-| 已在 feature 分支（含手工 wt/git-worktree） | `llman-sdd change attach <id>` | 分支已存在；`--base <branch>` 显式记录分叉源 |
+| 保留当前检出 / 并行 change | `llman-sdd change start <id> --worktree` | 分支建于独立 worktree（`sdd.worktree_root` / `sdd.worktree_naming` 可调，缺省仓库根兄弟目录），当前检出不动，输出含 worktree 路径；配 `--base <branch>`（仅本地分支）记录非默认分叉源 |
+| 已在 feature 分支（含手工 wt/git-worktree） | `llman-sdd change attach <id>` | 分支已存在；分叉源按 `--base` > `branch.<name>.base` / 本地 upstream 推导 > 默认分支，偏离默认分支时输出 WARNING；`--base` 仅接受本地分支 |
 
-finalize 目标定位：目标分支被其他 worktree 持有时，`llman-sdd change finalize <id>` / `llman-sdd change archive <id>` 自动在该 worktree 内完成合并、改名与提交（输出含 `executed in target worktree <path>`）；持有 worktree 脏时中止报错并列出处置选项（零写入）。
+finalize 目标定位：目标即绑定分支时跳过合并就地收口（输出含 in-place close-out 提示）；目标分支被其他 worktree 持有时，`llman-sdd change finalize <id>` / `llman-sdd change archive <id>` 自动在该 worktree 内完成合并、改名与提交（输出含 `executed in target worktree <path>`）；持有 worktree 脏时中止报错并列出处置选项（零写入）。

package/src/ports.ts

@@ -1,14 +0,0 @@
-/**
- * Ports (spec monorepo-structure r3): domain logic must not touch the
- * filesystem, git subprocesses, or the terminal directly — side effects are
- * injected through these interfaces. Nothing under packages/core may import
- * `node:fs`, `Bun.$`, or prompt libraries; runtimes wire adapters in.
- */
-
-/** Interaction port. predecessor ships an @inquirer/prompts adapter; a future ink TUI
- * ships its own adapter (the two must never run in the same process). */
-export interface PromptDriver {
-  select<T extends string>(message: string, choices: readonly T[]): Promise<T>;
-  multiselect<T extends string>(message: string, choices: readonly T[]): Promise<T[]>;
-  confirm(message: string): Promise<boolean>;
-}