@brainervirus/workit-core 0.11.0 → 1.0.0

package/src/core/youtrack.ts

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { readTemplate } from "./templates";
 import { resolveWorkspaceRoot } from "./scripts";
-import { configDir, isConfigObject } from "./config";
+import { configDir, isConfigObject, resolveConfigDir } from "./config";
+import { resolveInside } from "../core";
 
 const ISSUE_RE = /^[A-Z]+-\d+$/;
 const TOKEN_PLACEHOLDER = "YOUR_TOKEN_HERE";
@@ -12,6 +13,11 @@ const TOKEN_PLACEHOLDER = "YOUR_TOKEN_HERE";
 export const youTrackConfigPath = (): string =>
   process.env.WORKFLOW_YOUTRACK_CONFIG ?? path.join(configDir(), "youtrack.json");
 
+/** Config path for read-only context.  Unlike youTrackConfigPath(), this never
+ * calls configDir() and therefore cannot trigger legacy-config migration. */
+export const youTrackReadOnlyConfigPath = (): string =>
+  process.env.WORKFLOW_YOUTRACK_CONFIG ?? path.join(resolveConfigDir(), "youtrack.json");
+
 const youTrackTokenModeOk = (p: string): boolean => {
   if (process.platform === "win32") return true;
   const mode = fs.statSync(p).mode & 0o777;
@@ -42,6 +48,19 @@ function readYouTrackConfig(
   return { config: parsed as Record<string, any>, path: cfgPath };
 }
 
+const readYouTrackContextConfig = (): { data: Record<string, any> } | { error: string } => {
+  const cfgPath = youTrackReadOnlyConfigPath();
+  if (!fs.existsSync(cfgPath)) return { data: {} };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+  } catch {
+    return { error: "YouTrack configuration is unavailable" };
+  }
+  if (!isConfigObject(parsed)) return { error: "YouTrack configuration is unavailable" };
+  return { data: readOnlyYouTrackConfig(parsed as Record<string, any>) };
+};
+
 // RL-01: typed load result — malformed carries {ok:false, error, configPath}
 // mirroring vcsConfig, so risky consumers stop on the exact path.
 export type YouTrackConfigResult =
@@ -211,7 +230,7 @@ export function youTrackWorkDateMs(
   }
 }
 
-const youTrackToken = (): { token: string; base: string } | { error: string } => {
+export const youTrackToken = (): { token: string; base: string } | { error: string } => {
   const loaded = readYouTrackConfig(true);
   if ("error" in loaded) return loaded;
   const tokenFile = String(loaded.config.tokenFile ?? "");
@@ -237,7 +256,7 @@ const youTrackToken = (): { token: string; base: string } | { error: string } =>
 
 // fetch replaces the previous curl -fsS request helper: check res.ok,
 // surface HTTP errors without a token-bearing body, parse JSON on success.
-async function youTrackRequest(
+export async function youTrackRequest(
   url: string,
   init: { method: string; token: string; body?: unknown },
 ): Promise<{ status: number; stdout: string; stderr: string }> {
@@ -462,6 +481,13 @@ const defaultScripts: YouTrackScripts = {
   api: (args) => youTrackApi(args, process.env.WORKFLOW_YT_WRITE ?? ""),
 };
 
+const contextScripts: YouTrackScripts = {
+  config: readYouTrackContextConfig,
+  greeting: () => youTrackGreeting(youTrackReadOnlyConfigPath()),
+  parseDuration: (text) => youTrackParseDuration(text),
+  api: () => ({ error: "YouTrack context is read-only" }),
+};
+
 export function verifyYouTrackToken(
   scripts: YouTrackScripts = defaultScripts,
 ): Record<string, any> {
@@ -475,7 +501,12 @@ function resolveYouTrackFromPaths(
 ): string | null {
   const root = resolveWorkspaceRoot(workspace_root);
   for (const rel of [spec_path, plan_path].filter(Boolean) as string[]) {
-    const full = path.isAbsolute(rel) ? rel : path.join(root, rel);
+    let full: string;
+    try {
+      full = resolveInside(root, rel);
+    } catch {
+      continue;
+    }
     if (!fs.existsSync(full)) continue;
     const text = fs.readFileSync(full, "utf8");
     const m = text.match(/^\*\*YouTrack:\*\*\s*`?([A-Z]+-\d+)`?/m);
@@ -507,6 +538,50 @@ function meetingOptionsFromConfig(cfg: any): Record<string, any>[] {
   ];
 }
 
+const readOnlyYouTrackConfig = (cfg: Record<string, any>): Record<string, any> => {
+  const publicUrl = (value: unknown): string | undefined => {
+    if (typeof value !== "string") return undefined;
+    try {
+      const url = new URL(value);
+      if (url.username || url.password)
+        return `${url.protocol}//${url.host}${url.pathname}${url.search}${url.hash}`;
+      return value;
+    } catch {
+      return undefined;
+    }
+  };
+  const safe: Record<string, any> = {};
+  const baseUrl = publicUrl(cfg.baseUrl);
+  if (baseUrl) safe.baseUrl = baseUrl;
+  for (const key of ["timezone", "greetingCutoff", "defaultMention", "meetingIssue"])
+    if (typeof cfg[key] === "string") safe[key] = cfg[key];
+  if (cfg.greetings && typeof cfg.greetings === "object" && !Array.isArray(cfg.greetings)) {
+    const greetings: Record<string, string> = {};
+    for (const key of ["morning", "afternoon"])
+      if (typeof cfg.greetings[key] === "string") greetings[key] = cfg.greetings[key];
+    if (Object.keys(greetings).length) safe.greetings = greetings;
+  }
+  if (
+    cfg.meetingIssues &&
+    typeof cfg.meetingIssues === "object" &&
+    !Array.isArray(cfg.meetingIssues)
+  ) {
+    safe.meetingIssues = Object.fromEntries(
+      Object.entries(cfg.meetingIssues).flatMap(([key, value]) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+        const item = value as Record<string, any>;
+        const safeItem: Record<string, string> = {};
+        for (const field of ["issue", "label", "workItemText"])
+          if (typeof item[field] === "string") safeItem[field] = item[field];
+        const url = publicUrl(item.url);
+        if (url) safeItem.url = url;
+        return [[key, safeItem]] as const;
+      }),
+    );
+  }
+  return safe;
+};
+
 export function context(
   {
     spec_path,
@@ -525,7 +600,7 @@ export function context(
     mode?: string;
     workspace_root: string;
   },
-  scripts: YouTrackScripts = defaultScripts,
+  scripts: YouTrackScripts = contextScripts,
 ): Record<string, any> {
   const cfg = scripts.config();
   if (cfg.error) return { error: cfg.error };
@@ -535,11 +610,12 @@ export function context(
     return { error: (greeting.stderr || greeting.stdout || "greeting failed").trim() };
   }
 
-  const meetingOptions = meetingOptionsFromConfig(cfg.data);
+  const safeConfig = readOnlyYouTrackConfig(cfg.data);
+  const meetingOptions = meetingOptionsFromConfig(safeConfig);
 
   if (mode === "meetings" && !issue_id && !issue_url && !issue_ref) {
     return {
-      config: cfg.data,
+      config: safeConfig,
       greeting: greeting.stdout.trim(),
       mode: "meetings",
       requiresMeetingChoice: true,
@@ -554,7 +630,7 @@ export function context(
     if ("error" in parsed) return { error: parsed.error };
     issue = parsed.issueId;
   }
-  if (!issue && mode === "meetings") issue = meetingOptions[0]?.issue ?? cfg.data.meetingIssue;
+  if (!issue && mode === "meetings") issue = meetingOptions[0]?.issue ?? safeConfig.meetingIssue;
   if (!issue) issue = resolveYouTrackFromPaths(spec_path, plan_path, workspace_root) ?? undefined;
   if (!issue || !ISSUE_RE.test(issue)) {
     return {
@@ -564,13 +640,13 @@ export function context(
     };
   }
 
-  const base = (cfg.data.baseUrl || "").replace(/\/$/, "");
+  const base = (safeConfig.baseUrl || "").replace(/\/$/, "");
   const issueUrl = base ? `${base}/issue/${issue}` : null;
 
   const selectedMeeting = meetingOptions.find((m) => m.issue === issue);
 
   return {
-    config: cfg.data,
+    config: safeConfig,
     greeting: greeting.stdout.trim(),
     issueId: issue,
     issueUrl,
@@ -580,6 +656,65 @@ export function context(
   };
 }
 
+/** Fetch a YouTrack issue body for context.read (titles alone mislead).
+ * Creds failure degrades (offline keeps the link shape); request failure
+ * with creds fails closed so sessions never mistake titles for bodies. */
+export const fetchYouTrackIssueBody = async (
+  issue: string,
+  creds: () => { token: string; base: string } | { error: string } = youTrackToken,
+  request: typeof youTrackRequest = youTrackRequest,
+): Promise<
+  | {
+      data: {
+        idReadable: string;
+        summary: string;
+        description: string | null;
+        state: string | null;
+      };
+    }
+  | { error: string; kind: "creds" | "request" }
+> => {
+  const credentials = creds();
+  if ("error" in credentials) return { error: credentials.error, kind: "creds" };
+  const { token, base } = credentials;
+  const out = await request(
+    `${base}/api/issues/${encodeURIComponent(issue)}?fields=idReadable,summary,description,customFields(name,value(name))`,
+    { method: "GET", token },
+  );
+  if (out.status !== 0)
+    return { error: out.stderr || "YouTrack issue fetch failed", kind: "request" };
+  try {
+    const parsed = JSON.parse(out.stdout) as Record<string, unknown>;
+    const customFields = Array.isArray(parsed.customFields) ? parsed.customFields : [];
+    const stateField = customFields.find(
+      (field): field is { name: unknown; value: unknown } =>
+        typeof field === "object" &&
+        field !== null &&
+        (field as { name: unknown }).name === "State",
+    );
+    const stateValue = stateField?.value;
+    const stateName =
+      typeof stateValue === "object" && stateValue !== null
+        ? (stateValue as { name?: unknown }).name
+        : undefined;
+    return {
+      data: {
+        idReadable: String(parsed.idReadable ?? issue),
+        summary: String(parsed.summary ?? ""),
+        description: typeof parsed.description === "string" ? parsed.description : null,
+        state:
+          typeof stateValue === "string"
+            ? stateValue
+            : typeof stateName === "string" && stateName
+              ? stateName
+              : null,
+      },
+    };
+  } catch {
+    return { error: "invalid JSON from YouTrack API", kind: "request" };
+  }
+};
+
 export function parseDuration(
   text: string,
   _workspace_root: string,

package/src/core.ts

@@ -2,6 +2,132 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 
+export {
+  SCHEMA_VERSION,
+  POLICY_VERSION,
+  OPERATION_FAMILIES,
+  operationSchemas,
+  operationJsonSchema,
+  boundedOperationJsonSchema,
+  OPERATION_SCHEMA_DEPTH,
+  OPERATION_SCHEMA_MAX_DEPTH,
+  canonicalFieldsDescription,
+  parseOperation,
+  success,
+  failure,
+  canonicalJson,
+  sha256,
+  newId,
+  newRevision,
+  decisionDigest,
+  candidateDigest,
+  requirementId,
+} from "./core/task-contract";
+export type {
+  OperationFamily,
+  OperationRequest,
+  TaskStartRequest,
+  Caller,
+  Scope,
+  Ref,
+  Assessment,
+  Dimension,
+  Requirement,
+  Constraint,
+  Intent,
+  Progress,
+  Policy,
+  Candidate,
+  Capability,
+  Entry,
+  EvidenceEvaluation,
+  Evidence,
+  Outcome,
+  Decision,
+  Finding,
+  Assignment,
+  WorkerReport,
+  Worker,
+  TaskRecord,
+  WorkspaceRecord,
+  TaskView,
+  TaskSummary,
+  ExportBundle,
+  Result as ContractResult,
+} from "./core/task-contract";
+export { TaskStore } from "./core/task-store";
+export type { MetadataLock, ProcessEvidence, RecoveryInput } from "./core/task-store";
+export { compactTaskContext, reconcileResume } from "./core/task-context";
+export type {
+  CompactTaskContext,
+  ResumeObservation,
+  ResumeObservationInput,
+  ResumeReconciliation,
+} from "./core/task-context";
+export { METHODS, invariantBootstrap, selectMethods } from "./core/methods";
+export type { MethodId, SelectedMethod } from "./core/methods";
+export { applicableDecision, reserveAction, settleAction, reconcileAction } from "./core/authority";
+export {
+  createAuthorizedExternalActionRunner,
+  runAuthorizedExternalAction,
+} from "./core/external-action";
+export type {
+  AuthorizedActionInput,
+  ExternalActionResult,
+  ExternalActionRunner,
+  ExternalActionEffect,
+  ExternalActionBinding,
+  NativeExternalActionObservation,
+  ExternalActionRequest,
+  ExternalActionOperation,
+} from "./core/external-action";
+export {
+  approvedExternalAction,
+  externalActionState,
+  priorExternalAction,
+  externalActionRef,
+  externalActionDescriptor,
+  externalActionHelp,
+  externalActionRequest,
+  matchesNativeExternalAction,
+  nativeExternalActionObservation,
+  readNativeExternalActionObservation,
+} from "./core/external-action";
+export type {
+  ActionReservation,
+  NativeAuthorityContext,
+  NativeAuthorityVerifier,
+  NativeActionVerification,
+  NativeReconciliationVerification,
+  NativeDecisionVerification,
+  ReserveActionInput,
+  SettleActionInput,
+  ReconcileActionInput,
+} from "./core/authority";
+export {
+  captureCandidate,
+  evaluateEvidence,
+  evaluateRequirements,
+  evaluateClosure,
+} from "./core/task-evaluation";
+export type { CandidateEnvironment, ClosureEvaluation } from "./core/task-evaluation";
+export { WorkitCore } from "./core/task-engine";
+export type { OperationContext } from "./core/task-engine";
+export { assertProductWriteAllowed } from "./core/workers";
+export type {
+  CallerContext,
+  HostSession,
+  NativeWorkerDispatchVerification,
+  NativeWorkerObservation,
+  NativeWorkerVerification,
+  NativeWorkerVerifier,
+  ProductWriteInput,
+  WorkerDispatch,
+  WorkerDispatchCommit,
+  WorkerDispatchRequest,
+  WorkerDispatchStage,
+} from "./core/workers";
+
 export type Result<T> =
   | { ok: true; data: T; error: null }
   | { ok: false; data: T | null; error: string };

package/templates/execution-contract.md

@@ -1,73 +1,40 @@
-Load `using-superpowers`, `subagent-driven-development`, `test-driven-development`, and `verification-before-completion` through OpenCode's `skill` tool. Implement the existing plan; do not re-plan.
+Load resolved method skills through the host skill loader when policy selects them. Implement the existing plan; do not re-plan.
 
 **Spec:** <SPEC_PATH>
 **Plan:** <PLAN_PATH>
 **Branch:** <BRANCH>
-**SDD:** `<SDD_DIR>`
-
-## Handoff destination
-
-This session is a handoff destination for a continued plan. The originating session already recorded the post-plan menu choice; present exactly these four choices plus model deferral and never re-offer the originating handoff option:
-
-- Subagent-driven
-- Inline
-- Review spec first
-- Review plan first
-- Change model first
-
-<workflow-handoff-destination>true</workflow-handoff-destination>
 
 ## Hard gates
 
-- The parent is coordinator-only: it does not edit product code or perform delegated exploration.
-- Never use a worktree. Branch changes are in-place through `workit_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
-- Working state, briefs, ledgers, and review diffs live only under gitignored `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workit_sdd_*` tools.
-- Use native `todowrite` for visible task state as well as the gitignored ledger.
-- Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
-- Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workit_spec_approve` / `workit_plan_approve` / `workit_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`), Subagent-driven execution is supported through the one-time `coordinator_lease` and per-task `delegation_token` minted by `workit_delegate` (fail-closed validation; no `parentID` identity exists on Cursor), and Inline runs single-agent in the current session.
-- Delegated authority is direct-child-only: a worker is the session whose host `parentID` exactly equals the activating coordinator's recorded `coordinator_session_id`; missing, mismatched, or multi-owner lineage fails closed with `delegation_lineage_denied`, and nested `opencode` launches are denied during active delegated work. An authorized child receives only the compact worker contract (execute the supplied brief, follow TDD, land one contiguous non-empty commit range, report results) — never coordinator guidance, `wk-implement`, or ledger management; coordinator bookkeeping via `workit_sdd_*` stays with the coordinator session.
-- On Cursor, for every repository-scoped `workit_*` call, pass the active Cursor workspace as `workspace_root`; never rely on the MCP process default.
-- Use native `task` with only the built-in `explore` and `general` agents (OpenCode); on Cursor, Subagent-driven dispatches Cursor-native subagents with a task `delegation_token`, Inline runs single-agent in the current session.
-
-## Flow gates (HARD)
-
-- `wk-implement` refuses to run unless the plan is `approved` (flow.json) and the post-plan menu was presented.
-- `wk-handoff` refuses to run unless both spec and plan are `approved`.
-- Sequence is enforced by tools: `workit_spec_approve`, `workit_plan_approve`, `workit_plan_menu` — never skip a step (the spec/plan self-review runs automatically inside the transition; only the final approval asks for your confirmation).
+- Inspect task state before acting. On OpenCode, Cursor, Codex, and Pi use the eight shared `workit_*` families (`workit_task`, `workit_policy`, `workit_evidence`, `workit_finding`, `workit_decision`, `workit_worker`, `workit_writer`, `workit_state`). On the CLI host use `workit <family> <action>` with the same actions (hyphenated on the CLI).
+- Never use a worktree. Branch changes are in-place through the approved `git.branch_setup` external action (CLI: `workit action git.branch_setup --payload …`).
+- Task metadata lives under `.workit/`; never edit it directly. Record progress, evidence, findings, decisions, and worker state only through the shared operations.
+- Helpers cannot widen scope, record binding decisions, close or pause the task, assign further helpers, or resolve blockers for the lead.
+- On Cursor, pass the active workspace as `workspace_root` on every repository-scoped call.
 
 ## Setup
 
-0. Call `workit_docs_validate` with the linked spec/plan paths. Hard-fail on any error before todos or branch setup.
-1. Call `workit_sdd_context` with `<PLAN_PATH>` and initialize `todowrite` from returned tasks.
-2. Call `workit_plan_tasks`; cache each top-level task's `section_text`.
-3. Mark IDs in `completed_task_ids` completed and never redispatch them.
-4. Call `workit_resolve_branch`, then show the current branch, target branch, and stash behavior before any in-place checkout/setup mutation.
-5. Always use `question`: for a clean tree ask whether to proceed or cancel; for a dirty tree add the stash choice and describe what will be stashed.
-6. Call `workit_branch_setup` with `confirmed: true` only after approval.
+1. If there is no active or paused task, call `workit_task` with `action: "start"` then `workit_policy` with `action: "assess"` (CLI: `workit task start …` then `workit policy assess …`).
+2. Load `workit-plan`, list tasks with `workit_task` `action: "list"`, and mirror visible todo state to the host UI.
+3. When policy requires a feature branch, resolve it with read-only `context.read` and apply `git.branch_setup` only after native approval.
 
 ## Remaining-task loop
 
-For each top-level task absent from `completed_task_ids`:
+For each bounded plan task:
 
-1. Mark it `in_progress` with `todowrite`.
-2. Create a working-state brief with `workit_sdd_task_brief` and `confirmed: true`.
-3. Route by the approved execution mode: **Subagent-driven** delegates read-only discovery to an `explore` (OpenCode) agent, delegates implementation to a fresh `general` (OpenCode) agent (on Cursor, the coordinator mints a `delegation_token` with `workit_delegate` and the subagent prompt carries the raw token — the worker passes it as `delegation_token` on its mutation calls, and appending progress revokes it), and the coordinator never edits product code; **Inline** executes every task in the current agent with no dispatch and no token minting. Product changes follow TDD.
-4. Create a working-state diff with `workit_sdd_review_package` and `confirmed: true`.
-5. Delegate spec-compliance review and code-quality review to separate `general` agents.
-6. **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 with `workit_sdd_append_advisory` (`--task <id> --text <text>`, `confirmed: true`) instead of an unrestricted file edit.
-7. Append the validated ledger entry with `workit_sdd_append_progress` and `confirmed: true`; mark the todo completed.
+1. Mark the item in progress in the host todo UI and record boundary progress with `workit_task` `action: "progress"`.
+2. Route by policy: assign bounded workers with `workit_worker` `action: "assign"` when delegation is available; otherwise implement inline. Acquire product-write ownership with `workit_writer` `action: "acquire"` before repository mutations; release it when done.
+3. Record checks and artifacts with `workit_evidence` `action: "record"`. Record review concerns with `workit_finding` `action: "record"`; resolve or defer them with `finding.resolve`. Blocking findings may trigger at most **two** fix+re-review rounds per task; advisory taste/YAGNI items still use `finding.record` and never pause the loop by direct file edit.
+4. Never advance while a foreign writer is active or blocking findings remain open for the current candidate.
 
 ## Final gate
 
-Run a separate full-branch code review, then `workit_verify`. 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. Report exact check results and never infer success. Use `workit_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If working state contains a stash reference, preview reapplication through `question`, then call `workit_branch_setup` with `confirmed: true` after approval.
-
-**Mandatory:** end the run by calling `workit_plan_complete` (OpenCode/Cursor) or the CLI `workit flow complete` (CLI host) after the final task once the SDD ledger is complete (all task IDs appended) and `workit_verify` passes — a complete ledger and green verification are the tool's gates. Never finish the run while the plan is still `active`.
+Run repository verification (CLI: `workit doctor`; hosts: approved project verify when policy requires it). **Mandatory:** close the lead task with `workit_task` `action: "close"` (CLI: `workit task close --payload … [--confirm]`) once requirements are satisfied and verification passes — never finish while the task is still `active` or `paused`.
 
 ## Task order
 
 <TASK_LIST>
 
-## Quality gate (HARD)
+## Quality gate
 
-- Specs/plans are written from `templates/spec-template.md` / `templates/plan-template.md`.
-- After `workit_docs_validate`, surface `quality` findings (spec scan). Hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them. Warnings are advisory.
+- Specs/plans follow `templates/spec-template.md` / `templates/plan-template.md`.

package/templates/plan-template.md

@@ -1,6 +1,6 @@
 # <Feature> Implementation Plan
 
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. On Cursor the two paths are: **Subagent-driven** — Cursor-native subagents dispatched by the coordinator, each carrying a task-scoped `delegation_token` minted with `workit_delegate` from the one-time `coordinator_lease`; **Inline** — `executing-plans` in the current session, single-agent, no dispatch, no token minting. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **For agentic workers:** Load `workit-implement` when policy selects implementation. Use bounded `workit_worker` delegation when the host supports it; otherwise execute inline within writer scope. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Spec:** `docs/<slug>/spec.md`
 **Branch:** `feature/<slug>`
@@ -9,8 +9,8 @@
 
 ## Global Constraints
 
-- Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; each progress line records the task's real base..head shas.
-- The final task ends execution with `workit_plan_complete` (or the CLI `workit flow complete`) once the SDD ledger is complete and repository verification passes — a run never finishes while the plan is still `active`.
+- Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; record the real base..head shas in task progress.
+- The final task closes the lead Workit task with `workit_task` `action: "close"` (CLI: `workit task close --payload … [--confirm]`) once requirements are satisfied and repository verification passes — never finish while the task is still `active` or `paused`.
 - <project-wide requirements, one line each>
 
 ---

package/templates/spec-template.md

@@ -2,6 +2,9 @@
 
 **Branch:** `feature/<slug>`
 
+**Change:** ADDED|MODIFIED|REMOVED — <one-sentence intent>. (Small work with
+no durable agreement: `Spec: none (<reason>)`, no file.)
+
 ## Context
 
 <!-- Why does this exist? What problem does it solve? 1-3 sentences. -->
@@ -16,13 +19,14 @@
 
 ## Architecture
 
-<!-- REQUIRED if this spec has flows or architecture: render a mermaid diagram (workit_present_flow). -->
+<!-- May be `N/A (<reason>)` when the change has no flows or architecture. -->
+<!-- Otherwise REQUIRED: render a mermaid diagram (workit-diagram skill). -->
 ```mermaid
 flowchart TD
   A[Start] --> B[Step]
 ```
 
-<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workit_present_ascii). -->
+<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workit-mockup skill). -->
 ```text
 ┌──────────────┐
 │ Header       │
@@ -39,8 +43,16 @@ flowchart TD
 ## Acceptance criteria
 
 <!-- REQUIRED: enumerable, each verifiable. Numbered CA-01, CA-02, ... -->
+<!-- Requirements use SHALL/MUST (one per bullet, observable, no HOW); each
+     carries at least one GIVEN/WHEN/THEN, including the most-regretted edge. -->
 - CA-01 …
-- CA-02 …
+
+## Review checklist
+
+<!-- Before implementation: intent matches; nothing extra; each requirement
+     testable with an exercising scenario; most-cared case covered;
+     tasks trace to requirements; you would sign if built exactly as written. -->
+- [ ] …
 
 ## Decisions
 

package/templates/workit-contract.md

@@ -0,0 +1,12 @@
+# Workit contract
+
+Workit keeps one accountable lead and one shared task state. Inspect current
+task state before acting; use only the shared operations for task, policy,
+evidence, finding, decision, worker, writer, and state changes. Authority is
+bounded by the requested scope, current revision, caller/session provenance, and
+observed capabilities. Never claim host enforcement or evidence that the host
+cannot provide. Preserve unresolved requirements, gaps, and uncertain workers.
+
+Focused methods are loaded only when the resolved policy requires them. A method
+must call the shared operations and must not create a second lifecycle, approval
+chain, or task-state representation.

package/commands/wk-changelog.md

@@ -1,2 +0,0 @@
-Load the wk-changelog skill and follow it.
-$ARGUMENTS

package/commands/wk-commit.md

@@ -1,2 +0,0 @@
-Load the wk-commit skill and follow it.
-$ARGUMENTS

package/commands/wk-docs-refresh.md

@@ -1,2 +0,0 @@
-Load the wk-docs-refresh skill and follow it.
-$ARGUMENTS

package/commands/wk-handoff.md

@@ -1,2 +0,0 @@
-Load the wk-handoff skill and follow it.
-$ARGUMENTS

package/commands/wk-implement.md

@@ -1,2 +0,0 @@
-Load the wk-implement skill and follow it.
-$ARGUMENTS

package/commands/wk-init.md

@@ -1,2 +0,0 @@
-Load the wk-init skill and follow it.
-$ARGUMENTS

package/commands/wk-issue-update.md

@@ -1,2 +0,0 @@
-Load the wk-issue-update skill and follow it.
-$ARGUMENTS

package/commands/wk-meetings.md

@@ -1,2 +0,0 @@
-Load the wk-meetings skill and follow it.
-$ARGUMENTS

package/commands/wk-pr.md

@@ -1,2 +0,0 @@
-Load the wk-pr skill and follow it.
-$ARGUMENTS

package/commands/wk-release-notes.md

@@ -1,2 +0,0 @@
-Load the wk-release-notes skill and follow it.
-$ARGUMENTS

package/commands/wk-status.md

@@ -1,2 +0,0 @@
-Load the wk-status skill and follow it.
-$ARGUMENTS

package/commands/wk-verify.md

@@ -1,2 +0,0 @@
-Load the wk-verify skill and follow it.
-$ARGUMENTS