@brainervirus/workit-core 0.4.0

package/skills/wk-commit/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: wk-commit
+description: Preview and create a structured local commit without staging.
+disable-model-invocation: true
+---
+
+# Commit
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the read-only `workflow_git_context` context tool with any selected paths; its result is ground truth.
+3. Draft the exact Conventional Commit message and the already-staged file set.
+4. Use native `question` with concise choices and allow a custom answer before committing.
+5. Call `workflow_commit` only after approval with `confirmed: true` and the reviewed `message`.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Never stage files automatically: `workflow_commit` commits the current index only. Stop for an empty index, partial staging ambiguity, unrelated staged files, secrets, protected branches, or failed hooks. Never push, bypass hooks, use `--no-verify`, or claim files were committed unless the result proves it. Keep related code, tests, and docs in one coherent commit; do not invent extra commit groups. `todowrite` and `task` are unnecessary here.

package/skills/wk-docs-refresh/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: wk-docs-refresh
+description: Refresh stale repository documentation from structured change context.
+---
+
+# Docs refresh
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the read-only `workflow_docs_context` context tool; its result is ground truth.
+3. Draft the smallest factual documentation edit from structured facts.
+4. Use native `question` with concise choices and allow a custom answer only if the requested edit scope is ambiguous.
+5. Apply approved edits with normal OpenCode file tools, then call `workflow_verify`.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Prefer README changes when stale, then directly related tracked documentation. Preserve tone and structure; do not invent features, commands, environment variables, screenshots, or install steps. Do not make stylistic rewrites, commit, or modify product code. Report verification exactly. Use `todowrite` only when multiple requested documents need tracking; `task` is unnecessary.

package/skills/wk-handoff/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: wk-handoff
+description: Create and optionally select a seeded OpenCode continuation session.
+disable-model-invocation: true
+---
+
+# Handoff
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the automatic `workflow_handoff_session` tool with the full user message as `message`; its result is ground truth.
+3. The tool resolves the tracked spec, plan, and SDD context and seeds the continuation session.
+4. This workflow needs no `question`: the explicit invocation is approval.
+5. Pass only `message`; the tool itself recognizes an exact `--stay` flag and otherwise selects the new session.
+6. Report the structured success, failure stage, or partial result; never infer success.
+7. After any `workflow_handoff_session` result—success, partial, or failure—end the originating turn immediately after one status message. Never create todos, execute the plan inline, modify files, retry handoff, or call another tool.
+
+Never emit a continuation prompt, use the clipboard, or ask the user to copy text. If selected, report the session ID only if the current session remains visible. If staying, report the seeded session ID. On failure, report `stage` and `error`; preserve any returned session for the session picker and never recreate it automatically. `todowrite` and `task` are unnecessary here.

package/skills/wk-implement/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: wk-implement
+description: Coordinate a tracked Superpowers plan with delegated implementation and reviews.
+disable-model-invocation: true
+---
+
+# Implement
+
+The parent agent is coordinator-only. It must not edit product code or perform delegated exploration.
+
+## Native setup
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call read-only `workflow_plan_tasks` and `workflow_sdd_context`; their structured results are ground truth.
+3. Call `workflow_flow_status` with the plan path and hard-stop unless `spec.status === "approved"`, `plan.status === "approved"`, and `menu.presented === true`. If any gate is missing, run the required approval flow (`workflow_spec_approve`/`workflow_plan_approve` after the user's native-question approval, `workflow_plan_menu` after the post-plan menu) and re-check — never start tasks on a draft or unapproved plan.
+4. Initialize native `todowrite` from returned tasks and mark ledger-completed task IDs completed.
+5. Call `workflow_resolve_branch`, then show the current branch, target branch, and stash behavior before any branch checkout/setup mutation.
+6. Always use native `question` before that mutation. For a clean tree, ask whether to proceed or cancel. For a dirty tree, add the stash choice and state what will be stashed; allow a custom answer.
+7. Call `workflow_branch_setup` with `confirmed: true` only after approval; never use worktrees.
+8. Report any setup failure stage or partial result; never infer success.
+9. Fill specs/plans from the quality templates: `templates/spec-template.md` for specs, `templates/plan-template.md` for plans. After `workflow_docs_validate`, surface the returned `quality` findings: hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them; warnings are advisory.
+
+State lives only in tracked `docs/<slug>/sdd/<slug>/`. Never use an untracked or legacy SDD directory. Load the package-neutral execution contract by name, not an installation-specific path.
+
+## Per-task loop
+
+For every plan task whose ID is absent from `completed_task_ids`:
+
+1. Mark it `in_progress` with `todowrite`.
+2. Create its brief with `workflow_sdd_task_brief` using `confirmed: true` and the parsed `section_text`.
+3. Use `task` with the built-in `explore` agent for read-only discovery when needed, then a fresh built-in `general` agent to implement from the brief. The parent remains coordinator-only.
+4. Require product changes to follow TDD: failing check first, minimal implementation, passing focused check.
+5. Create the review package with `workflow_sdd_review_package` using `confirmed: true`.
+6. Dispatch separate `general` agents for spec-compliance review and code-quality review. **Blocking findings** (Critical, Important, or spec-compliance) may trigger at most **two** fix+re-review rounds per task. **Advisory** findings (Minor, style, YAGNI, taste) never pause the loop — append them to `<SDD_DIR>/advisories.md` with the task id.
+7. Append the validated ledger line with `workflow_sdd_append_progress` using `confirmed: true`, then mark the task completed with `todowrite`.
+
+Never redispatch completed task IDs. Pass task briefs and review diffs to agents; do not make them reparse the plan. Keep commits on the in-place feature/bugfix branch.
+
+## Final gate
+
+After all remaining tasks, dispatch a final full-branch code review, run `workflow_verify`, and report exact per-check results. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Only then may advisory fixes run. Use `workflow_git_context` for the final commit preview and the `wk-commit` skill for any approved commit. If a tracked stash reference exists, preview reapplication with `question`, then call `workflow_branch_setup` with `confirmed: true` only after approval.

package/skills/wk-init/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: wk-init
+description: Preview and apply one-time workit configuration.
+disable-model-invocation: true
+---
+
+# Init
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the read-only `workflow_toolkit_init_status` context tool; its result is ground truth.
+3. Draft an exact preview of each missing scaffold and the active VCS provider.
+4. For each guarded mutation, use native `question` with concise choices and allow a custom answer.
+5. Call `workflow_toolkit_init_apply` only after approval with `confirmed: true` and the chosen action.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Never ask for or accept tokens in chat. For missing YouTrack configuration, preview `youtrack_scaffold`; for missing VCS configuration, ask GitLab or GitHub, preview `vcs_scaffold`, and pass `vcs_provider`. Both provider token placeholders may be created, but identify which one is active. Show the returned token-create URL and local edit path after apply. Verification remains a separate `wk-status` run. `todowrite` and `task` are unnecessary here.
+
+## Guided config (action: "config")
+
+When the user wants to personalize the toolkit (locale, timezone, branch policy), ask native questions one at a time:
+
+1. **Locale** — present a combobox of `localeOptions` (en, es-CL, es-MX, es-AR, pt-BR) + custom answer; validate the answer against BCP-47 (`^[a-z]{2,3}(-[A-Z]{2})?$`) before passing it.
+2. **Timezone** — e.g. `America/Santiago`, custom allowed.
+3. **Branch policy preset** — gitflow / github-flow / trunk-based / custom.
+4. **Custom branch lists** (only when preset = custom): allowed patterns (`feature/*`, `codex/*`, …) and protected names (`main`, …).
+
+Then call `workflow_toolkit_init_apply` with `action: "config"`, `confirmed: true`, and the answered values. Report the written `config.json` path and its contents.
+
+After config, call `workflow_toolkit_init_apply` with `action: "gitignore"` and `confirmed: true` to ensure the project `.gitignore` covers `docs/*/sdd/` and common OS/editor entries (creates it if missing, preserves existing entries).
+
+After gitignore, call `workflow_toolkit_init_apply` with `action: "hygiene"`, `confirmed: true`, and `include_open_source: true` for open-source repos — creates CHANGELOG.md (Keep a Changelog), README.md, .editorconfig, .gitattributes, and optionally LICENSE + CONTRIBUTING.md. Never overwrites existing files.

package/skills/wk-issue-update/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: wk-issue-update
+description: Draft and post a reviewed es-CL YouTrack task update with time.
+disable-model-invocation: true
+---
+
+# Issue update
+
+Read [references/youtrack-update-style.md](references/youtrack-update-style.md) before drafting. Chat follows the user's language; the comment body is manager-friendly Spanish (`es-CL`).
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Ask in plain prose for the user-provided issue URL or ID, call `workflow_youtrack_parse_issue`, then read-only `workflow_youtrack_context`; structured results are ground truth.
+3. Gather the user's notes, call `workflow_youtrack_parse_duration`, polish only supported facts, and call `workflow_youtrack_draft` for the exact comment preview.
+4. Use native `question` with concise choices and allow a custom answer to approve the reviewed comment and time entry.
+5. Call `workflow_youtrack_post` only after approval with `confirmed: true`, `issueId`, `markdown`, and `minutes`.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Never guess the issue, compute minutes, pass a date, expose tokens, or post Git/file details as the update. Never present a clickable `question` option whose label is an instruction to type free text (e.g. "Type the issue URL/ID"): clicking an option returns the label literal, not the typed value, so ask for free text in prose instead, with the custom answer field enabled. Preserve the user's paragraph voice, explain technical terms plainly, and avoid robotic status bullets. `todowrite` and `task` are unnecessary here.
+
+Consume the standard Result envelope:
+
+- If `result.ok` is true, report only effects proven by `result.data`.
+- If false, use `result.data.postedComment` and `result.data.loggedMinutes` to distinguish completed effects.
+- If `result.data.retry === "workflow_youtrack_post"`, use native `question` to ask whether to retry the unchanged reviewed `issueId`, `markdown`, and `minutes`. On approval, call `workflow_youtrack_post` with `confirmed: true` at most once; never loop.
+- If `result.data.retry === "workflow_youtrack_log_time"`, use native `question` to ask whether to retry the same `issueId` and `minutes`. On approval, call `workflow_youtrack_log_time` with `confirmed: true`, `issueId`, `minutes` at most once; never repost a known posted comment.
+- If the second attempt fails, stop and report its structured result. Never switch retry tools or infer that either effect succeeded.
+- If outcome is `unknown` or `result.data.retry` is absent, show `result.data.instructions` when present, reconcile manually, and do not retry either mutation.

package/skills/wk-issue-update/references/youtrack-update-style.md

@@ -0,0 +1,81 @@
+# YouTrack update style (Cristhofer / es-CL)
+
+Use when writing or polishing the comment body before `workflow_youtrack_draft`. **Preserve the author's voice** — like the ChatGPT revision thread: grammar, flow, and light structure, not a changelog.
+
+## Audience
+
+**@Alejandra.Flores is the primary reader — she is not a developer.** Write for a technical project manager:
+
+- Lead with **what you worked on and why it mattered**, not implementation mechanics.
+- If you mention something technical (OpenAPI, flags, component names, GUAS, MFE), add **one short plain-language clause** so the reader understands impact without knowing the stack.
+- Prefer product/feature language: *data sources*, *integración con el backend*, *selector de color*, *vista del segundo factor*.
+
+### Technical detail — clarify, don't drop
+
+| Too dev (avoid alone) | Better for manager |
+|-----------------------|-------------------|
+| overlays fuera del shadow DOM en el host | el selector de color no se veía bien cuando el reporte está embebido en la web principal |
+| `replaceUrl: true` en el interceptor | para que al volver atrás no se repitiera el mismo error en bucle |
+| Migré a `daisy-overlay-tokens` | ajusté los estilos del overlay para que respeten el tema de la web |
+
+Only include dev terms the user actually brought up — then **translate or contextualize** in the same breath.
+
+## Shape
+
+1. `# Actualización` (single H1)
+2. Blank line
+3. `@Alejandra.Flores` + greeting (`Hola, buenos días.` / `Hola, buenas tardes.`) — same line or next paragraph OK
+4. **Body: paragraphs**, not bullet dumps
+
+Optional second H1 when the user has a long tangent block:
+
+- `## Off-topic` — only when the user's material is clearly a side topic (tooling, proceso, ideas). Keep the main work under `# Actualización`.
+
+## Openers (only if the user's material implies it)
+
+- `Hoy estuve trabajando en…` / `Hoy por la tarde he estado full con…`
+- `Hoy estuve full con <proyecto>.`
+- `Dado lo que conversamos,…`
+
+Do **not** force an opener.
+
+## Voice
+
+- First person, Chilean Spanish: *harto*, *darle una vuelta*, *al día*, *trasteando*, *ojalá*.
+- Honest: *al parecer*, *creo que*, *imagino que*, *no alcancé a*, *entiendo que*.
+- Explain **why** and **what's next**, not file trees.
+- Close with forward look when relevant: *Mañana…*, *me falta…*, *de momento va bien*.
+
+## Tangents
+
+Natural bridges: `Por otro lado,…`, `Como comentario adicional,…`, `Como punto aparte,…`, `Quiero comentar algo que puede ser interesante.`
+
+Long tooling/process tangents → `## Off-topic` (exemplar 4).
+
+## Allowed formatting
+
+- Backticks for product/component names the user mentioned: `` `color-picker` ``, `` `button` ``
+- Links and screenshots the user attached
+- Short inline lists **only** when comparing options the manager needs to understand (exemplar 4: OpenAPI vs backend vs frontend) — as **prose or one flowing sentence**, not a task checklist
+
+## Forbidden (unless user wrote them verbatim)
+
+- Branch names, SHAs, `src/...` paths
+- Nested `###` subsections for work items
+- Bullet lists of completed tasks (PR style)
+- Stacked changelog verbs: *Implementé*, *Migré*, *Alineé*
+- Invented work or metrics
+- Pasting `git log`, agent session, or `facts.*` into the comment
+- Jargon without a plain-language gloss
+
+## Polish level (ChatGPT-thread)
+
+1. Grammar and spelling.
+2. Smooth sentences; similar length to input.
+3. Split wall-of-text into paragraphs; add bridges only when needed.
+4. **Do not** add facts the user did not supply.
+5. **Do** add a brief gloss when the user used opaque tech terms.
+
+## Length
+
+Match the user. Never pad.

package/skills/wk-meetings/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: wk-meetings
+description: Log meeting time only to the configured YouTrack meeting issue.
+disable-model-invocation: true
+---
+
+# Meetings
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call read-only `workflow_youtrack_context` with `mode: "meetings"`; its sole configured target is ground truth.
+3. Ask for duration text, call `workflow_youtrack_parse_duration`, and draft the exact IRPT-12 time entry only.
+4. Use native `question` with concise choices and allow a custom answer to approve the shown issue, minutes, and work-item text.
+5. Call `workflow_youtrack_log_time` only after approval with `confirmed: true`, `issueId`, `minutes`, `text`.
+6. If `result.data.outcome` is `unknown`, tell the user to reconcile manually and do not retry. Retry `workflow_youtrack_log_time` at most once only when `result.data.outcome` is `not_applied` and `result.data.retry` names that tool; follow `result.data.instructions` and correct invalid input before retrying.
+7. Report the structured success or failure stage; never infer success.
+
+Use the configured meeting issue even if its default label is IRPT-12. Never compute minutes, pass a date, ask for a meeting type, post a comment, or call `workflow_youtrack_post`. `todowrite` and `task` are unnecessary here.

package/skills/wk-pr/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: wk-pr
+description: Preview and create a pull or merge request from branch-exclusive facts.
+disable-model-invocation: true
+---
+
+# Pull request
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the read-only `workflow_pr_context` context tool for branch-exclusive commits and changes; its result is ground truth.
+3. Call `workflow_verify`, then draft the exact title, body, base, head, and draft state from structured facts.
+4. **Show** the exact title and body in chat before any create question.
+5. Use native `question` with concise choices and allow a custom answer before creation.
+6. Call `workflow_pr_create` only after approval with `confirmed: true` and the reviewed fields.
+7. Report the structured success, failure stage, or partial result; never infer success.
+
+## GitHub issue linking
+
+When the resolved workspace is github with `link_on_pr` — `bash scripts/vcs/config.sh resolve` returns `issues_provider: "github"` and `link_on_pr: true` — and no issue is derivable (no `WORKFLOW_GH_ISSUE` env, no numeric branch id like `feature/42-title`, which auto-links without asking), ask with native `question` before creation, exactly three options:
+
+1. **Use an existing issue** — the user provides the number (extract it from a URL if pasted); verify it exists with `gh issue view <n>` before proceeding.
+2. **Create a new issue** — via `gh issue create --title "<title>" --body "<body>"`; on success pass the returned number. Reuse the missing-CLI guard: if `gh` is not installed, surface the structured error with the install link and ask the user to confirm once installed.
+3. **Skip linking** — no issue line in the PR body.
+
+Pass the chosen issue to pr-create via env: `WORKFLOW_GH_ISSUE=<n>` and, when the PR does NOT resolve the issue, `WORKFLOW_GH_ISSUE_RELATION=related` (default `closes`). The youtrack linking flow (`youtrack.link_issues`) for work workspaces is unchanged.
+
+Only feature or bugfix branches may target the configured base; never create from a protected branch. The body must describe only branch-exclusive changes, follow the repository template when present, and disclose failed or skipped verification. Never expose tokens, edit product files, or fall back to provider CLIs. `todowrite` and `task` are unnecessary here.

package/skills/wk-release-notes/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: wk-release-notes
+description: Draft user-facing release notes for an explicit range.
+---
+
+# Release notes
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Require an exact version, tag, or commit range, then call the read-only `workflow_release_notes_context`; its result is ground truth.
+3. Draft notes from structured facts and include both requested and resolved range metadata.
+4. Use native `question` only when the exact range must be supplied or corrected; allow a custom answer.
+5. This workflow has no mutation tool.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Write for users: supported highlights, fixes, upgrade notes, and known issues only. Omit empty sections except Highlights, and say directly when the resolved range contains no user-facing changes. Do not edit files, publish a release, or infer a range. `todowrite` and `task` are unnecessary here.

package/skills/wk-status/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: wk-status
+description: Report workit, YouTrack, and VCS health.
+disable-model-invocation: true
+---
+
+# Status
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the read-only `workflow_toolkit_status` context tool once; its result is ground truth.
+3. Draft the health report from structured facts.
+4. This workflow has no guarded mutation and does not need `question`.
+5. Do not call any mutation tool.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Show every `items[]` result, the resolved YouTrack settings and verification, the VCS provider and verification, and the exact `ready` verdict. For placeholders, point to the returned token creation and edit paths; never request tokens in chat. Use only `workflow_toolkit_status` and report its structured state. Do not run shell, Git, direct HTTP, isolated token verification, or any mutation. `todowrite` and `task` are unnecessary for this read-only workflow.

package/skills/wk-verify/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: wk-verify
+description: Discover and run project validation with workflow_verify.
+disable-model-invocation: true
+---
+
+# Verify
+
+1. Load this skill explicitly through OpenCode's `skill` tool.
+2. Call the read-only `workflow_verify` context tool with `dry_run: true`; its result is ground truth.
+3. Draft the discovered checks and the proposed selected run from structured facts.
+4. When the user must choose checks, use native `question` with concise choices and allow a custom answer.
+5. Call `workflow_verify` with `dry_run: false` only for the approved run.
+6. Report the structured success, failure stage, or partial result; never infer success.
+
+Do not edit files or fix failures. Report every check exactly as pass, fail, or skipped, including its command, exit code, and skip reason. Success requires every executed check to exit 0. If the user's message says `--dry-run`, stop after discovery.

package/src/core/branch.ts

@@ -0,0 +1,246 @@
+import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { gitContext } from "./git";
+import { readConfig, resolveBranchPolicy } from "./config";
+
+const policy = () => resolveBranchPolicy(readConfig());
+const allowedBranch = (name: string) => policy().allowed.some((r) => r.test(name));
+const isProtected = (name: string) => policy().protected.has(name.toLowerCase());
+const DECLARE_RE = /^\s*\*+Branch:\*+\s*`?([^`\s|]+)`?\s*$/gim;
+const USE_CURRENT_RE = /^\s*\*+Branch:\*+\s*use-current\s*$/im;
+const readSafe = (p: string): string | null => {
+  try { return readFileSync(p, "utf8"); } catch { return null; }
+};
+
+const normalizeBranch = (name: string): string | null => {
+  const n = name.trim().replace(/`/g, "").replace(/\.+$/, "");
+  if (isProtected(n)) return null;
+  if (!allowedBranch(n)) return null;
+  const parts = n.toLowerCase().split("/").map((p) =>
+    p.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-"));
+  if (parts.some((p) => !p)) return null;
+  return parts.join("/");
+};
+
+const deriveSlug = (planPath: string): string => {
+  // New layout: plan lives at docs/<slug>/plan.md — slug is the dir name.
+  const dirName = path.basename(path.dirname(planPath));
+  return dirName === "." || dirName === "/" || dirName === "" ? "" : dirName;
+};
+
+const deriveKind = (planPath: string, fallback: "feature" | "bugfix" = "feature"): "feature" | "bugfix" => {
+  const slug = deriveSlug(planPath);
+  const text = readSafe(planPath) ?? "";
+  let kind = fallback;
+  if (/\bbugfix\b/i.test(slug) || /^fix-/i.test(slug)) {
+    kind = "bugfix";
+  } else {
+    const goal = text.split("\n").find((line) => line.startsWith("**Goal:**"))?.toLowerCase() ?? "";
+    if (/\b(bugfix|bug fix)\b/.test(goal) && !/\b(feat|feature|upgrade|add)\b/.test(goal)) {
+      kind = "bugfix";
+    }
+  }
+  return kind;
+};
+
+// Port of scripts/lib/resolve-handoff-branch.sh
+export const resolveBranch = ({
+  spec_path,
+  plan_path,
+  workspace_root,
+}: { spec_path: string; plan_path: string; workspace_root: string }) => {
+  const cwd = path.resolve(workspace_root);
+  const abs = (p: string) => (path.isAbsolute(p) ? p : path.join(cwd, p));
+  const spec = abs(spec_path);
+  const plan = abs(plan_path);
+  const git = gitContext(cwd);
+  const current = git.branch;
+
+  const finish = (branch: string, source: string) => ({
+    branch,
+    source,
+    current_branch: current,
+    dirty: Boolean(git.status_short.trim()),
+    needs_checkout: current !== branch,
+  });
+
+  for (const file of [spec, plan]) {
+    const text = readSafe(file);
+    if (!text) continue;
+    if (USE_CURRENT_RE.test(text)) {
+      if (!current || !allowedBranch(current) || isProtected(current)) {
+        return { error: `use-current but HEAD ${current} is not an allowed branch` };
+      }
+      return finish(current, "use-current");
+    }
+  }
+
+  if (current && allowedBranch(current) && !isProtected(current)) return finish(current, "keep-current");
+
+  let declaredButInvalid: string | null = null;
+  for (const file of [spec, plan]) {
+    const text = readSafe(file);
+    if (!text) continue;
+    for (const match of text.matchAll(DECLARE_RE)) {
+      const normalized = normalizeBranch(match[1]);
+      if (normalized) return finish(normalized, file === spec ? "spec" : "plan");
+      declaredButInvalid ??= match[1];
+    }
+  }
+  if (declaredButInvalid) {
+    return { error: `declared branch ${JSON.stringify(declaredButInvalid)} is not allowed by the branch policy` };
+  }
+
+  const slug = deriveSlug(plan);
+  if (!slug) return { error: `cannot derive branch slug from plan ${plan}` };
+  const kind = deriveKind(plan);
+  return finish(`${kind}/${slug}`, "derived");
+};
+
+// Port of scripts/lib/resolve-docs-branch.sh
+export const docsBranch = ({
+  plan_path,
+  kind,
+  workspace_root,
+}: { plan_path?: string; kind?: string; workspace_root: string }) => {
+  const cwd = path.resolve(workspace_root);
+  const git = gitContext(cwd);
+  const current = git.branch;
+  const kindArg = (kind ?? "feature").toLowerCase();
+
+  if (current && allowedBranch(current) && !isProtected(current)) {
+    return { branch: current, action: "keep", current_branch: current, base: "develop", dirty: Boolean(git.status_short.trim()) };
+  }
+  if (current === "main" || current === "master" || current === "develop") {
+    let slug = "";
+    if (plan_path) {
+      const plan = path.isAbsolute(plan_path) ? plan_path : path.join(cwd, plan_path);
+      slug = deriveSlug(plan);
+    }
+    if (!slug) {
+      return { error: "plan_path required to derive branch slug when not on feature/* or bugfix/*" };
+    }
+    const branchKind = kindArg === "bugfix" ? "bugfix" : "feature";
+    return { branch: `${branchKind}/${slug}`, action: "create_from_develop", current_branch: current, base: "develop", dirty: Boolean(git.status_short.trim()) };
+  }
+  return { error: `cannot resolve docs branch from HEAD ${JSON.stringify(current)}` };
+};
+
+// Port of scripts/lib/ensure-develop-base.sh
+export const ensureDevelopBase = (cwd: string): { ok: boolean; error?: string } => {
+  const git = gitContext(cwd);
+  if (!git.branch || git.branch === "unknown") return { ok: false, error: "not in a git repository" };
+  const run = (args: string[]) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  try {
+    try {
+      run(["fetch", "origin", "develop", "--prune"]);
+    } catch {
+      run(["fetch", "origin", "--prune"]);
+    }
+    let hasOriginDevelop = true;
+    try { execFileSync("git", ["show-ref", "--verify", "--quiet", "refs/remotes/origin/develop"], { cwd, stdio: "pipe" }); } catch { hasOriginDevelop = false; }
+    if (!hasOriginDevelop) return { ok: false, error: "origin/develop missing — push develop before creating feature/* or bugfix/* branches" };
+    let hasLocalDevelop = true;
+    try { execFileSync("git", ["show-ref", "--verify", "--quiet", "refs/heads/develop"], { cwd, stdio: "pipe" }); } catch { hasLocalDevelop = false; }
+    if (hasLocalDevelop) {
+      run(["checkout", "develop"]);
+      try { run(["merge", "--ff-only", "origin/develop"]); } catch { /* non-fast-forward: keep local */ }
+    } else {
+      run(["checkout", "-b", "develop", "--track", "origin/develop"]);
+    }
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "ensure-develop-base failed" };
+  }
+};
+
+// Port of scripts/branch/setup-branch.sh
+export const branchSetup = ({
+  action,
+  sdd_dir,
+  target_branch,
+  stash,
+  workspace_root,
+}: { action?: string; sdd_dir?: string; target_branch?: string; stash?: string; workspace_root: string }) => {
+  const cwd = path.resolve(workspace_root);
+  const exec = (args: string[]): string =>
+    execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  const current = gitContext(cwd).branch;
+  if (!current || current === "unknown") return { error: "not in a git repository" };
+  const sdd = sdd_dir ?? "docs";
+  const manifestPath = path.isAbsolute(sdd) ? path.join(sdd, "manifest.json") : path.join(cwd, sdd, "manifest.json");
+  mkdirSync(path.dirname(manifestPath), { recursive: true, mode: 0o755 });
+  const readManifest = (): Record<string, unknown> => {
+    try { return JSON.parse(readFileSync(manifestPath, "utf8")); } catch { return {}; }
+  };
+  const writeManifest = (data: Record<string, unknown>) =>
+    writeFileSync(manifestPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+
+  if (action === "reapply_stash") {
+    const manifest = readManifest();
+    const ref = manifest.stash_ref;
+    if (!ref) return { error: "no stash_ref in manifest" };
+    try { exec(["stash", "pop", String(ref)]); } catch (error) {
+      return { error: error instanceof Error ? error.message : "stash pop failed" };
+    }
+    delete manifest.stash_ref;
+    delete manifest.stash_created_at;
+    writeManifest(manifest);
+    return { action: "reapply_stash", ok: true };
+  }
+
+  const target = target_branch ?? "";
+  if (!target) return { error: "target branch required" };
+  if (isProtected(target)) return { error: `protected branch ${target}` };
+  if (!allowedBranch(target)) return { error: `target branch ${target} is not allowed by the branch policy` };
+
+  let stash_ref: string | undefined;
+  if (current !== target) {
+    const dirty = Boolean(gitContext(cwd).status_short.trim());
+    if (dirty) {
+      if (stash !== "yes") {
+        return { error: "dirty working tree — ask with native question, then call workflow_branch_setup with stash=yes" };
+      }
+      try {
+        exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`, "--", ":!docs/*/sdd"]);
+      } catch (error) {
+        return { error: error instanceof Error ? error.message : "stash push failed" };
+      }
+      stash_ref = "stash@{0}";
+    }
+    try {
+      exec(["checkout", target]);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "checkout failed";
+      if (/worktree/i.test(message)) {
+        return { error: `branch ${target} is locked by an existing git worktree — remove it first (we do not use worktrees)` };
+      }
+      try {
+        // Branch does not exist yet: base it on develop (never main/master).
+        const current = gitContext(cwd).branch;
+        if (current === "main" || current === "master") {
+          const baseResult = ensureDevelopBase(cwd);
+          if (!baseResult.ok) return { error: baseResult.error };
+        } else {
+          // Already on develop or another feature branch: still require origin/develop to exist.
+          const baseResult = ensureDevelopBase(cwd);
+          if (!baseResult.ok) return { error: baseResult.error };
+        }
+        exec(["checkout", "-b", target]);
+      } catch (createError) {
+        return { error: createError instanceof Error ? createError.message : "branch create failed" };
+      }
+    }
+  }
+
+  const manifest = readManifest();
+  manifest.branch = target;
+  manifest.previous_branch = current;
+  if (stash_ref) {
+    manifest.stash_ref = stash_ref;
+    manifest.stash_created_at = new Date().toISOString();
+  }
+  writeManifest(manifest);
+  return { action: "setup", ok: true, branch: target, previous_branch: current, stash_ref: stash_ref ?? null, manifest: manifestPath };
+};