abelworkflow 1.1.3 → 1.2.1

package/lib/providers/skills.mjs

@@ -3,100 +3,120 @@ import { join } from "node:path";
 import * as p from "@clack/prompts";
 import { readDotenvFile, updateDotenvFile } from "../config/store.mjs";
 import { pathToLabel } from "../paths.mjs";
+import { normalizeHttpBaseUrl } from "./url.mjs";
 
 const grokDefaults = Object.freeze(JSON.parse(readFileSync(
   new URL("../../skills/grok-search/defaults.json", import.meta.url),
   "utf8"
 )));
 
-function readSkillEnvFile(path) {
-  return readDotenvFile(path, { sensitive: true });
+function readSkillEnvFile(path, safeRoot) {
+  return readDotenvFile(path, { safeRoot, sensitive: true });
 }
 
-async function updateSkillEnvFile(path, updates) {
-  return updateDotenvFile(path, updates, { sensitive: true });
+async function updateSkillEnvFile(path, updates, safeRoot) {
+  return updateDotenvFile(path, updates, { safeRoot, sensitive: true });
 }
 
-async function configureGrokSearchEnv(paths, ensureSkillPresent = async () => {}, promptApi) {
+function validateHttpBaseUrl(value) {
+  try {
+    normalizeHttpBaseUrl(value);
+  } catch (error) {
+    return error.message;
+  }
+}
+
+async function configureGrokSearchEnv(paths, withSkillPresent, promptApi, runtime = {}) {
   const {
     assertNotCancelled,
     confirmOrCancel,
     passwordOrExisting,
     required
   } = promptApi;
-  await ensureSkillPresent(paths);
-  const envPath = join(paths.agentsDir, "skills", "grok-search", ".env");
-  const existing = await readSkillEnvFile(envPath);
-  const baseUrl = await p.text({
-    message: "Grok API URL",
-    initialValue: existing.GROK_API_URL || "https://api.x.ai/v1",
-    validate: required()
-  });
-  assertNotCancelled(baseUrl);
+  const text = runtime.text ?? p.text;
+  const log = runtime.log ?? p.log;
+  return withSkillPresent(paths, async (guard) => {
+    await guard();
+    const envPath = join(paths.agentsDir, "skills", "grok-search", ".env");
+    const existing = await readSkillEnvFile(envPath, paths.agentsDir);
+    const baseUrlInput = await text({
+      message: "Grok API URL",
+      initialValue: existing.GROK_API_URL || "https://api.x.ai/v1",
+      validate: validateHttpBaseUrl
+    });
+    assertNotCancelled(baseUrlInput);
+    const baseUrl = normalizeHttpBaseUrl(baseUrlInput);
 
-  const finalApiKey = await passwordOrExisting({
-    message: "Grok API Key",
-    existingValue: existing.GROK_API_KEY,
-    requiredMessage: "Grok API Key 不能为空"
-  });
+    const finalApiKey = await passwordOrExisting({
+      message: "Grok API Key",
+      existingValue: existing.GROK_API_KEY,
+      requiredMessage: "Grok API Key 不能为空"
+    });
 
-  const model = await p.text({
-    message: "Grok 默认模型",
-    initialValue: existing.GROK_MODEL || grokDefaults.model,
-    validate: required()
-  });
-  assertNotCancelled(model);
+    const model = await text({
+      message: "Grok 默认模型",
+      initialValue: existing.GROK_MODEL || grokDefaults.model,
+      validate: required()
+    });
+    assertNotCancelled(model);
 
-  const useTavily = await confirmOrCancel({
-    message: "是否同时配置 Tavily 作为额外搜索源？",
-    initialValue: Boolean(existing.TAVILY_API_KEY)
-  });
+    const useTavily = await confirmOrCancel({
+      message: "是否同时配置 Tavily 作为额外搜索源？",
+      initialValue: Boolean(existing.TAVILY_API_KEY)
+    });
 
-  const tavilyUrl = useTavily
-    ? await p.text({
-        message: "Tavily API URL",
-        initialValue: existing.TAVILY_API_URL || "https://api.tavily.com",
-        validate: required()
-      })
-    : null;
-  if (useTavily) assertNotCancelled(tavilyUrl);
-
-  const finalTavilyKey = useTavily
-    ? await passwordOrExisting({
-        message: "Tavily API Key",
-        existingValue: existing.TAVILY_API_KEY,
-        requiredMessage: "Tavily API Key 不能为空"
-      })
-    : null;
-
-  await updateSkillEnvFile(envPath, {
-    GROK_API_URL: baseUrl,
-    GROK_API_KEY: finalApiKey,
-    GROK_MODEL: model,
-    TAVILY_API_URL: tavilyUrl,
-    TAVILY_API_KEY: finalTavilyKey,
-    TAVILY_ENABLED: useTavily ? "true" : null
-  });
+    const tavilyUrl = useTavily
+      ? await text({
+          message: "Tavily API URL",
+          initialValue: existing.TAVILY_API_URL || "https://api.tavily.com",
+          validate: validateHttpBaseUrl
+        })
+      : null;
+    if (useTavily) assertNotCancelled(tavilyUrl);
+    const normalizedTavilyUrl = useTavily ? normalizeHttpBaseUrl(tavilyUrl) : null;
 
-  p.log.step(`已写入 ${pathToLabel(envPath)}`);
+    const finalTavilyKey = useTavily
+      ? await passwordOrExisting({
+          message: "Tavily API Key",
+          existingValue: existing.TAVILY_API_KEY,
+          requiredMessage: "Tavily API Key 不能为空"
+        })
+      : null;
+
+    await guard();
+    await updateSkillEnvFile(envPath, {
+      GROK_API_URL: baseUrl,
+      GROK_API_KEY: finalApiKey,
+      GROK_MODEL: String(model).trim(),
+      TAVILY_API_URL: normalizedTavilyUrl,
+      TAVILY_API_KEY: finalTavilyKey,
+      TAVILY_ENABLED: useTavily ? "true" : null
+    }, paths.agentsDir);
+
+    log.step(`已写入 ${pathToLabel(envPath)}`);
+  });
 }
 
-async function configureContext7Env(paths, ensureSkillPresent = async () => {}, promptApi) {
+async function configureContext7Env(paths, withSkillPresent, promptApi, runtime = {}) {
   const { passwordOrExisting } = promptApi;
-  await ensureSkillPresent(paths);
-  const envPath = join(paths.agentsDir, "skills", "context7-auto-research", ".env");
-  const existing = await readSkillEnvFile(envPath);
-  const finalApiKey = await passwordOrExisting({
-    message: "Context7 API Key（可选）",
-    existingValue: existing.CONTEXT7_API_KEY,
-    requiredMessage: null
-  });
+  const log = runtime.log ?? p.log;
+  return withSkillPresent(paths, async (guard) => {
+    await guard();
+    const envPath = join(paths.agentsDir, "skills", "context7-auto-research", ".env");
+    const existing = await readSkillEnvFile(envPath, paths.agentsDir);
+    const finalApiKey = await passwordOrExisting({
+      message: "Context7 API Key（可选）",
+      existingValue: existing.CONTEXT7_API_KEY,
+      requiredMessage: null
+    });
 
-  await updateSkillEnvFile(envPath, {
-    CONTEXT7_API_KEY: finalApiKey
-  });
+    await guard();
+    await updateSkillEnvFile(envPath, {
+      CONTEXT7_API_KEY: finalApiKey
+    }, paths.agentsDir);
 
-  p.log.step(`已写入 ${pathToLabel(envPath)}`);
+    log.step(`已写入 ${pathToLabel(envPath)}`);
+  });
 }
 
 export {

package/lib/providers/url.mjs

@@ -0,0 +1,35 @@
+const invalidBaseUrlMessage = "Base URL 必须是无凭据的有效绝对 HTTP(S) URL";
+
+function parseHttpBaseUrl(value) {
+  const input = String(value || "").trim();
+  if (!/^https?:\/\/\S+$/iu.test(input)) throw new TypeError(invalidBaseUrlMessage);
+
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new TypeError(invalidBaseUrlMessage);
+  }
+  if (!url.hostname
+    || (url.protocol !== "http:" && url.protocol !== "https:")
+    || url.username
+    || url.password) {
+    throw new TypeError(invalidBaseUrlMessage);
+  }
+  return { input, url };
+}
+
+function normalizeHttpBaseUrl(value) {
+  return parseHttpBaseUrl(value).input;
+}
+
+function normalizeOpenAiBaseUrl(value) {
+  const { url } = parseHttpBaseUrl(value);
+  let pathname = url.pathname.replace(/\/+$/u, "")
+    .replace(/\/v1\/(?:chat\/completions|responses)$/u, "/v1");
+  if (!pathname.endsWith("/v1")) pathname = `${pathname}/v1`;
+  url.pathname = pathname;
+  return url.toString();
+}
+
+export { normalizeHttpBaseUrl, normalizeOpenAiBaseUrl };

package/lib/templates/workflow/commands/abel-design.md

@@ -1,175 +1,37 @@
 ---
 name: abel-design
-description: Transform requirements into implementation-ready, traceable specs via gated clarification.
+description: Transform requirements into implementation-ready OpenSpec artifacts.
 category: abel
-tags: [abel, design, constraints, PBT, subagents]
+tags: [abel, design, openspec]
 argument-hint: [requirement | --change <change_name>]
 ---
 
 <!-- ABEL:START -->
+# abel-design
 
-# abel-design — Gated Design Mode (Specs Only, No Implementation)
+Turn a requirement into a validated, traceable OpenSpec change. This command is design only; do not implement product code.
 
-## Non-Negotiable Rules (Highest Priority)
-1. DESIGN MODE ONLY — you MUST NOT generate implementation code.
-2. WRITE SCOPE:
-   - Before Gate A: strictly read-only; persist nothing.
-   - After Gate A: write ONLY inside the resolved `changeRoot`. Create only ready artifacts; edit a done artifact only when an approved loop-back/consistency repair explicitly targets it.
-3. NEVER assume or guess — every blocking decision goes to the user (see Decision Model).
-4. Final output: a schema-valid, fully traceable OpenSpec change with BLOCKING_DECISIONS = 0, READY_TO_IMPLEMENT.
+## Rules
 
-**Skill Integration**: See `Stage Skill Matrix` (Design column)
+- Follow the repository instructions and the Design column of its Stage Skill Matrix.
+- Before any write, state assumptions and unknowns explicitly. If a critical unknown could change scope, behavior, architecture, data handling, security, or an irreversible action, stop and ask the user.
+- Retrieve project context with `rg`, `rg --files`, `git grep`, and direct file reads. Use only project evidence and research sources allowed by the repository instructions.
+- Use unified diff patches for proposed and applied changes. Write only inside the resolved OpenSpec `changeRoot`.
+- Do not create runtime approval or resume state.
 
----
-
-## Decision Model
-- Maintain an in-session Decision Ledger with: `id`, `class`, `question`, `evidence`, `options`, `recommendation`, `resolution`, `status`, `affected_artifacts`.
-- `BLOCKING_DECISIONS` is the count of unresolved, non-mechanical decisions in that ledger.
-- Behavior decisions answer WHAT: observable outcomes, scope/non-goals, scenarios, failure behavior, data/security/privacy/compatibility policies and success criteria.
-- Technical decisions answer HOW: interfaces, data flow, dependencies, storage/algorithms, implementation error mechanisms and key technical parameters.
-- MUST be approved by the user: goal, scope, non-goals and observable success behavior; data, security, privacy, compatibility and migration rules; new dependencies, cross-module architecture, irreversible changes; any technical choice with substantive trade-offs, including key parameters.
-- MAY be decided mechanically by the agent: naming, file locations and local structure uniquely determined by existing repo conventions; easily reversible details with no external behavior change; test placement and execution order derived directly from the approved design.
-- Record mechanical decisions and never re-ask them. Two or more viable options with substantive differences → escalate to a blocking decision.
-- Do NOT create a runtime ledger or approval-state file. Materialize approved decisions only in schema artifacts.
-
-## Phase 0 — Entry, Mode & Readiness (read-only)
-- Verify an initialized OpenSpec root and the required CLI capabilities: `new change`, `list --json`, `schemas --json`, `schema which --json`, `schema validate --json`, `templates --json`, `status --json`, `instructions --json`, and `validate --strict`. If unavailable, STOP with actionable `/abel-init` remediation; do not initialize or update from this command.
-- Resolve mode:
-  - Explicit `--change <name>` → Resume. If that change does not exist, STOP and ask the user to correct the name or choose New mode.
-  - Otherwise, an exact existing-change match → Resume.
-  - Otherwise → New mode; do not silently interpret an explicit/resume-like typo as a requirement.
-- Resolve the effective schema by precedence: explicit schema choice, existing change metadata, project config, then `spec-driven`; verify it appears in `openspec schemas --json`.
-- Before creating a change, run `openspec schema which <schema> --json` and `openspec schema validate <schema> --json`, inspect its definition and `openspec templates --schema <schema> --json`, and perform a preliminary behavior/technical/mixed dependency check. Implementation compatibility also requires a non-empty concrete `apply.tracks` that matches exactly one artifact's `generates`. An incompatible schema must fail closed before creation.
-- New mode minimum intake before ANY exploration:
-  - Problem/goal statement, AND
-  - Scope anchor (which module/directory is involved).
-- If either intake item is missing, ask the user concisely before proceeding.
-- Generate a provisional kebab-case change name and check `openspec list --changes --json`. Recompute and confirm it from the final Gate A scope before creation. Persist nothing yet.
-
-## Phase 1 — Evidence Exploration (read-only)
-- Use local codebase retrieval with `rg`, `rg --files`, `git grep`, and direct file reads.
-- Single context boundary → main agent explores directly.
-- Multiple independent context boundaries, when the platform permits → dispatch parallel Explore subagents:
-  - Divide by context boundary (NOT functional role); each boundary self-contained.
-  - Each subagent receives: mandatory use of the codebase retrieval policy, a clear scope, and the mandatory JSON output schema:
-{
-  "module_name": "所探索的上下文边界",
-  "existing_structures": ["关键结构/模式"],
-  "existing_conventions": ["约定/标准"],
-  "constraints_discovered": ["硬约束"],
-  "open_questions": ["需用户输入的歧义"],
-  "dependencies": ["跨模块依赖"],
-  "risks": ["风险/阻碍"],
-  "success_criteria_hints": ["可观察的成功行为"]
-}
-- Validate every subagent JSON before aggregation; aggregate constraints, dependencies, risks, conflicts and questions into the Decision Ledger.
-- Audit existing codebase patterns:
-  Use `rg`, `rg --files`, `git grep`, and direct file reads to validate against existing codebase patterns.
-- On-demand /context7-auto-research: verify candidate libraries/APIs against official contracts.
-- On-demand /grok-search: architectural patterns and best practices for candidate directions.
-- PBT boundary screening: probe empty input, idempotency, ordering, size/value bounds, state-transition legality → feed the question list for Phase 2.
-- Reference: Inspect codebase structure with `rg --files`, `git grep`, and direct file reads.
-
-## Phase 2 — Behavior Clarification Loop (multiple rounds allowed)
-- Cover WHAT only: goal, scope, non-goals, observable scenarios/success criteria, failure behavior, and data/security/privacy/compatibility policies.
-- Do not choose libraries, protocols, algorithms, storage, topology or implementation parameters in this phase; route them to Phase 4.
-- Each round asks ONLY the current highest-impact blocking questions, grouped concisely, each with evidence, impact and a recommended default.
-- Anti-patterns (flag and reject):
-  - Observable behavior deferred to implementation ("error behavior decided while coding")
-  - Technical mechanisms smuggled in as product requirements
-- Target behavior patterns:
-  - "Lock the account for 30 minutes after 5 consecutive failed logins."
-  - "Retain audit records for 30 days and never expose secrets in responses."
-  - "For an empty query, return an empty result within the approved latency bound."
-- An answer that widens modules, scenarios or data boundaries → return to Phase 1 for INCREMENTAL exploration only.
-- Loop until unresolved behavior decisions = 0.
-
-## ⛔ Gate A — Approve Behavior Contract
-- Present the behavior contract and affected Decision Ledger entries; the user explicitly approves goal, scope/non-goals, scenarios/success criteria and policies.
-- Recompute the change name from the approved scope and recheck duplicates.
-- New mode: ONLY NOW create the change with `openspec new change <change-name>` (add `--schema <schema>` only for an explicit non-default choice).
-- Build the Artifact Plan, then materialize only behavior-class artifacts that are safe and ready.
-
-## Artifact Plan & Write Protocol
-- Before New-mode creation, build a preliminary compatibility map from the resolved schema definition/templates. After creation or in Resume mode, build the final Artifact Plan from `status --json` and available `instructions --json`. Record the schema's `apply.tracks`; for every artifact record capture id/output paths, dependencies/status, substantive decision class (`behavior|technical|mixed`), write Gate, and affected decisions. Mechanical impact information alone does not make an artifact mixed.
-- Classify by the decisions the artifact carries, never by a hardcoded artifact name:
-  - behavior → Gate A
-  - technical or mixed → Gate B
-  - behavior depending on a Gate B artifact → defer until after Gate B and then follow the DAG
-- If the schema requires a write before Gate A, a write outside `changeRoot`, or an unapproved technical decision to unlock behavior, STOP before New-mode creation and ask the user to select a compatible schema/mapping. Schema order never overrides decision approval.
-- Mandatory loop for EVERY artifact write:
-  1. Run `openspec status --change <change-name> --json`; verify `schemaName`, `changeRoot`, `artifactPaths`, status/dependencies and `applyRequires`. `existingOutputPaths` may be empty and is not a new-file target.
-  2. Run `openspec instructions <artifact-id> --change <change-name> --json`; follow its template/rules/dependencies.
-  3. Read dependencies and existing outputs; check consistency in both directions.
-  4. Prepare content in memory and show the decision summary or unified diff before the corresponding Gate. If materialization reveals a new substantive decision, return to the relevant loop and re-approve it.
-  5. After Gate approval, create exactly one ready artifact, or edit one done artifact explicitly targeted by an approved loop-back/consistency repair. Rerun status after every write and process newly unlocked artifacts topologically.
-
-## Phase 3 — Technical Derivation
-- Derive the technical design from the Gate A contract, existing codebase patterns and official API contracts.
-- Mechanical decisions → record directly in the design. Substantive trade-offs → Phase 4.
-
-## Phase 4 — Technical Decision & Verification Loop
-- Cover HOW: interfaces, data flow, implementation error mechanisms, dependencies/algorithms and key parameters. Examples include JWT vs session design and an approved bcrypt cost factor.
-- Apply the same evidence/options/recommendation format to every substantive technical decision; update the Decision Ledger.
-- PBT applicability rule (screen with the six categories: commutativity/associativity, idempotency, round-trip, invariant preservation, monotonicity, bounds):
-  - Behavior with invariants, round-trips, idempotency, ordering, bounds or state transitions → MUST extract a property + falsification strategy.
-  - Behavior unsuited to PBT → use example/E2E/static verification and record why PBT does not apply. Do NOT force every requirement through every category.
-- Give every scenario a stable reference: `<spec-path>#<requirement-heading>/<scenario-heading>` and require those headings to be unique within the spec; maintain Requirement → Scenario → Verification → Task.
-- Every task has exactly one schema checkbox and a verification contract using ordinary indented bullets, NEVER nested `- [ ]`/`- [x]` lines:
-  - Task ID / dependencies
-  - Requirement + stable Scenario reference
-  - Verification type: property | example | E2E | static
-  - Red command + expected failure reason
-  - Green expected behavior
-  - Affected-suite verification command
-  - Target scope/files
-- For a non-behavior-change task, the Red command is a pre-change executable static verification. Manual-only verification is not implementation-ready and MUST NOT pass Gate B or Exit; reshape the task until it has executable property/example/E2E/static verification.
-- Loop until unresolved technical decisions = 0; prepare proposed remaining artifact contents/unified diffs in memory.
-
-## ⛔ Gate B — Approve Implementation Contract
-- Verify Phase 3/4 faithfully expand the Gate A contract; no unapproved new decisions introduced.
-- Present substantive technical decisions, task/verification mapping and artifact materialization preview.
-- The user explicitly approves that implementation contract.
-- Write the remaining ready artifacts one at a time per the Artifact Plan & Write Protocol.
-
-## Loop-Back Rules
-- A user answer widens modules, scenarios or data boundaries → return to Phase 1.
-- Technical analysis overturns the behavior contract → return to Phase 2; re-approve ONLY the affected decisions and synchronize all affected artifacts.
-- Gate B finds the materialization unfaithful → return to Phase 3/4; unaffected Gate A decisions remain approved.
-- Strict validation, verification-contract or traceability failure → return to the earliest phase that introduced the inconsistency.
-- Never hide a late-discovered blocking question.
-
-## Resume Rules
-- Never infer user approval from artifact existence: `status` reporting `done` proves file completion only, not Gate approval.
-- Never resume by fixed file names or file existence alone; the active schema decides.
-- Algorithm:
-  1. Run `openspec status --change <change-name> --json`.
-  2. Use its `schemaName`, `changeRoot`, `artifactPaths` and statuses; read all `existingOutputPaths` and dependencies.
-  3. Check `openspec validate <change-name> --strict --type change`, template completeness, cross-artifact consistency, traceability and verification contracts.
-  4. Rebuild Gate A/B summaries and the Artifact Plan. Re-confirm every Gate approval that cannot be proven in the current conversation.
-  5. Choose the next step:
-     - Explicit Resume change not found (`change_error`) → STOP for spelling/New-mode confirmation; never create silently.
-     - Artifacts incomplete → repair/confirm the nearest safe Gate, then handle the artifacts the schema reports ready.
-     - Artifacts complete but validation/traceability fails → earliest inconsistent phase.
-     - Every artifact id listed in `applyRequires` is `done` → re-confirm any unproven Gate, then run the Exit audit.
-     - Only in-session, un-persisted analysis exists → no mid-loop resume; re-run the read-only analysis.
-- Do NOT create runtime approval-state files; re-confirming the Gate summary IS the resume mechanism.
+## Process
 
-## Exit Criteria
-- [ ] `openspec validate <change-name> --strict --type change` returns zero issues
-- [ ] Every artifact id in `applyRequires` has status `done`
-- [ ] Schema `apply.tracks` resolves to the generated task artifact inside `changeRoot`
-- [ ] Artifacts are consistent and traceable; every task has a valid verification contract
-- [ ] Every task has executable property/example/E2E/static verification; no task is manual-only
-- [ ] BLOCKING_DECISIONS = 0
-- [ ] User has explicitly approved the reconstructed/current Gate A and Gate B summaries in this conversation
-- [ ] Status: READY_TO_IMPLEMENT
+1. Resolve the input as a new requirement or an explicit `--change <change-name>`. Never silently create a mistyped explicit change.
+2. Verify the OpenSpec project and CLI. Use `openspec context --json`, `openspec list --changes --json`, and `openspec schemas --json`; direct missing setup to `/abel-init`.
+3. Resolve the schema from the existing change, explicit choice, project configuration, or the OpenSpec default. Inspect it with `openspec schema which <schema> --json`, `openspec schema validate <schema> --json`, and `openspec templates --schema <schema> --json`.
+4. Confirm the schema exposes a concrete `apply.tracks` path generated by one artifact. For an existing change, read `schemaName`, `changeRoot`, `artifactPaths`, `applyRequires`, and artifact states from `openspec status --change <change-name> --json`.
+5. Explore the affected code and nearby tests. Summarize current behavior, constraints, dependencies, risks, assumptions, and unknowns with file evidence.
+6. Clarify the smallest set of unresolved behavior and technical decisions. Ask only questions whose answers materially affect the design, and include evidence, impact, options, and a recommended default.
+7. Define scope, non-goals, observable scenarios, failure behavior, data/security/privacy effects, interfaces, dependencies, and verification. Keep the Requirement → Scenario → Verification → Task chain explicit.
+8. For a new change, choose a kebab-case name, check for conflicts, show the planned artifact changes as a unified diff, then run `openspec new change <change-name>`; add `--schema <schema>` only for an explicit non-default choice.
+9. Materialize artifacts in schema dependency order. Before each artifact, run `openspec status --change <change-name> --json` and `openspec instructions <artifact-id> --change <change-name> --json`, read its dependencies and existing output, then apply the smallest consistent patch.
+10. Give each implementation task its target files, dependencies, requirement/scenario reference, Red command and expected failure, minimal Green behavior, and affected/final verification commands.
+11. Run `openspec validate <change-name> --strict --type change`. Finish only when validation passes, every `applyRequires` artifact is done, `apply.tracks` resolves inside `changeRoot`, artifacts agree, and no critical unknown remains.
 
-## Reference
-- `openspec context --json` / `openspec schemas --json`
-- `openspec view` / `openspec list --changes --json` / `openspec list --specs` (conflicts with existing specs)
-- `openspec status --change <change-name> --json` / `openspec instructions <artifact-id> --change <change-name> --json`
-- `openspec new change <change-name>` (Gate A only)
-- `openspec show <change-name> --json --deltas-only` when validation fails
-- `rg -n "Constraint:|MUST|MUST NOT|INVARIANT:|PROPERTY:" openspec/` before defining new ones
+Report the change name, decisions made, artifacts changed, validation evidence, and any non-blocking residual risks.
 <!-- ABEL:END -->

package/lib/templates/workflow/commands/abel-diagnose.md

@@ -1,63 +1,37 @@
 ---
 name: abel-diagnose
-description: Parallel diagnosis with batch fix reporting via systematic root cause analysis.
+description: Diagnose bugs from evidence and apply minimal regression-tested fixes.
 category: abel
-tags: [abel, diagnosis, bugfix]
+tags: [abel, diagnosis, bugfix, TDD]
 argument-hint: <problem-description>
 ---
+
 <!-- ABEL:START -->
-**Arguments**
-- Required: `<problem-description>` (one or more bug descriptions; comma-separated supported)
-
-**Guardrails**
-- Root cause first; never fix symptoms only
-- Verify root cause hypothesis with evidence before fix
-- Only fixes with evidence-verified root cause may be applied
-- Every fix must include a regression test
-- Keep changes minimal and scoped
-- If verification fails, rollback and iterate
-
-**Execution Model** 
-- Run detection and root-cause analysis for all issues in parallel
-- Infer scope automatically from problem text, traces, and retrieved code context
-- Build dependency/conflict order before any fix application
-- Same file: force sequential fix order; same symbol: merge when compatible, otherwise sequential
-- Independent scopes: parallel-safe
-- Fix generation for READY issues runs fully in parallel via subagents with forked/minimal context; main agent only aggregates and resolves conflicts
-- Patch application and final verification must run strictly sequential by dependency order
-- Always output one consolidated batch report
-
-**Skill Integration**: See `Stage Skill Matrix` (Diagnose column)
-
-**Steps**
-1. Parse input, infer scope, and split into issue list (single or multiple).
-2. For each issue in parallel: collect logs/traces and locate code via the configured codebase retrieval policy.
-3. For each issue in parallel: perform root cause analysis; for multi-component chains, decompose the failure chain step by step with evidence.
-4. Build dependency/conflict graph across issues and compute safe fix order.
-5. Verify each issue's root cause against collected evidence; only issues with a verified root cause can move to fix generation.
-6. Spawn one subagent per READY issue to generate `unified diff patch` and regression test with minimal scoped context.
-7. Main agent reviews/merges subagent outputs by dependency order and outputs one batch report with all issue statuses and patches.
-8. Apply merged patches strictly sequentially by dependency order.
-9. Run final verification strictly sequentially by the same dependency order and output verification matrix.
-
-**Batch Output**
-```text
-## /abel-diagnose Batch Report
-
-### Batch Summary
-Total: {n} | ReadyToFix: {n_ready} | Blocked: {n_blocked}
-
-### Issue Results
-- [{id}] Classification: {category}/{severity} | Root Cause: {summary} | Verified: {yes|no} | Subagent: {agent_id|none} | Status: {READY|BLOCKED}
-
-### Patch Queue (dependency order)
-1. [{id}] [subagent:{agent_id}] {file_list}
-{unified_diff_patch}
-
-### Verification Matrix
-- [{id}] Regression: {passed|failed} | Affected Suite: {passed|failed}
-
-### Final Status
-{FIXED|PARTIAL|NEEDS_REVIEW|BLOCKED}
-```
+# abel-diagnose
+
+Find the verified root cause of the reported problem, then fix it with a regression test and minimal patch.
+
+## Rules
+
+- Follow the repository instructions and the Diagnose column of its Stage Skill Matrix.
+- State assumptions and unknowns before any write. If a critical unknown prevents reliable reproduction, changes fix scope, or affects safety, stop and ask the user.
+- Retrieve project context with `rg`, `rg --files`, `git grep`, and direct file reads. Use logs, traces, tests, and project evidence before forming conclusions.
+- Do not apply a fix until evidence supports the root cause. Do not broaden scope to speculative cleanup.
+- Use unified diff patches for every change.
+
+## Process
+
+1. Restate the observed failure and expected behavior. Identify the smallest affected boundary and relevant verification command.
+2. Reproduce the problem when safe. Record the command, environment facts, output, and failure identity. If it cannot be reproduced, distinguish missing evidence from disproven hypotheses.
+3. Trace the failing path through callers, state transitions, data boundaries, and nearby tests. Compare working and failing cases.
+4. Form the smallest falsifiable root-cause hypothesis and test it against the evidence. For multiple issues, identify dependencies or file conflicts before editing.
+5. Red: add or update a focused regression test and run it before the fix; require failure for the verified root cause. If no meaningful executable regression is possible, state why and stop for direction.
+6. Green: apply the smallest fix and rerun the regression test. Preserve unrelated behavior and user-owned state.
+7. Refactor only if needed for clarity, keeping the regression and affected tests green.
+
+## Final Verification
+
+- Run the regression test, affected suite, and any proportionate broader suite.
+- Review the complete diff for scope, side effects, security, secrets, and runtime state accidentally added to the repository.
+- Report the verified root cause with evidence, modified files, Red/Green results, final verification commands, and residual risks or unresolved issues.
 <!-- ABEL:END -->