ultra-builder-pro-cli 0.7.0 → 0.8.1

package/hooks/workflow_resume.py

@@ -2,12 +2,82 @@
 """Restore only the current Ultra workflow boundary after compaction."""
 
 import json
+import os
 import sys
+import tempfile
+from datetime import datetime, timezone
 from pathlib import Path
 
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
+def valid_workflow(state: object) -> bool:
+    return (
+        isinstance(state, dict)
+        and isinstance(state.get("command"), str)
+        and bool(state["command"].strip())
+        and state.get("step") is not None
+        and isinstance(state.get("status"), str)
+        and bool(state["status"].strip())
+    )
+
+
+def read_json(file: Path, label: str):
+    if not file.is_file():
+        return None
+    try:
+        return json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"[workflow_resume] cannot read {label} {file}: {exc}", file=sys.stderr)
+        return None
+
+
+def parse_time(value: object):
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def newest_time(file: Path, *values: object) -> datetime:
+    candidates = [parsed for value in values if (parsed := parse_time(value)) is not None]
+    try:
+        candidates.append(datetime.fromtimestamp(file.stat().st_mtime, tz=timezone.utc))
+    except OSError:
+        pass
+    return max(candidates, default=datetime.min.replace(tzinfo=timezone.utc))
+
+
+def load_checkpoint(file: Path):
+    checkpoint = read_json(file, "checkpoint")
+    if checkpoint is None:
+        return None
+    if not isinstance(checkpoint, dict):
+        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
+        return None
+    captured_at = checkpoint.get("captured_at")
+    workflow = checkpoint.get("workflow")
+    if checkpoint.get("schema") != 1 or parse_time(captured_at) is None or not valid_workflow(workflow):
+        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
+        return None
+    return checkpoint
+
+
+def restore_state(file: Path, state: dict) -> None:
+    file.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(prefix="workflow-state.", suffix=".json", dir=file.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(state, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp_name, file)
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -18,21 +88,40 @@ def main() -> None:
     start = Path(data.get("cwd") or Path.cwd()).resolve()
     for root in (start, *start.parents):
         state_file = root / ".ultra" / "workflow-state.json"
-        if not state_file.is_file():
+        checkpoint_file = root / ".ultra" / "runtime" / "checkpoint.json"
+        if not state_file.is_file() and not checkpoint_file.is_file():
             continue
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[workflow_resume] cannot read {state_file}: {exc}", file=sys.stderr)
+        live = read_json(state_file, "workflow state")
+        if live is not None and not valid_workflow(live):
+            print(f"[workflow_resume] invalid workflow state in {state_file}", file=sys.stderr)
+            live = None
+        if live is not None and live.get("status") in TERMINAL:
             break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+        checkpoint = load_checkpoint(checkpoint_file)
+        checkpoint_state = checkpoint["workflow"] if checkpoint is not None else None
+        if checkpoint_state is not None and checkpoint_state.get("status") in TERMINAL:
+            checkpoint_state = None
+
+        source = ".ultra/workflow-state.json"
+        state = live
+        if checkpoint_state is not None:
+            checkpoint_time = newest_time(
+                checkpoint_file, checkpoint_state.get("ts"), checkpoint.get("captured_at")
+            )
+            live_time = newest_time(state_file, live.get("ts")) if live is not None else None
+            if live_time is None or checkpoint_time >= live_time:
+                state = checkpoint_state
+                source = ".ultra/runtime/checkpoint.json"
+                restore_state(state_file, state)
+        if state is None:
             break
         text = (
             "[Ultra workflow resumed] "
             f"command={state.get('command', 'unknown')}; "
             f"task={state.get('task_id', state.get('task', 'unknown'))}; "
             f"step={state.get('step', 'unknown')}; status={state.get('status', 'active')}. "
-            "Continue from .ultra/workflow-state.json and verify state through .ultra/state.db."
+            f"source={source}. Continue from the recovered workflow boundary and verify "
+            "task/session/change state through .ultra/state.db."
         )
         event = data.get("hook_event_name", "SessionStart")
         if event == "SessionStart":

package/mcp-server/lib/change-workflow.cjs

@@ -26,6 +26,13 @@ const REQUIRED_EVIDENCE = Object.freeze({
   major: ['diff', 'tests', 'spec', 'docs', 'review'],
   incident: ['diagnosis', 'diff', 'tests'],
 });
+const INCIDENT_DIAGNOSIS_SECTIONS = Object.freeze([
+  { heading: 'Reproduction', key: 'reproduction' },
+  { heading: 'Hypotheses', key: 'hypotheses' },
+  { heading: 'Root cause', key: 'root-cause' },
+  { heading: 'Regression test', key: 'regression-test' },
+  { heading: 'Recovery', key: 'recovery' },
+]);
 
 class ChangeWorkflowError extends Error {
   constructor(code, message, details) {
@@ -149,6 +156,53 @@ function writeIntent(file, change) {
   fs.writeFileSync(file, `${lines.join('\n')}\n`);
 }
 
+function writeIncidentDiagnosis(file, change) {
+  const lines = [
+    `# Incident diagnosis: ${change.title}`,
+    '',
+    ...INCIDENT_DIAGNOSIS_SECTIONS.flatMap(({ heading }) => [`## ${heading}`, '', '']),
+  ];
+  fs.writeFileSync(file, `${lines.join('\n')}\n`);
+}
+
+function readMarkdownSections(text) {
+  const sections = new Map();
+  let current = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      current = heading[1].trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+      if (!sections.has(current)) sections.set(current, []);
+      continue;
+    }
+    if (current) sections.get(current).push(line);
+  }
+  return new Map([...sections].map(([key, lines]) => [key, lines.join('\n').trim()]));
+}
+
+function inspectIncidentDiagnosis(change, artifactDir, rootDir) {
+  if (change.kind !== 'incident') return { blockers: [], artifact: null };
+  const diagnosisPath = path.join(artifactDir, 'diagnosis.md');
+  if (!fs.existsSync(diagnosisPath)) {
+    return { blockers: ['DIAGNOSIS_ARTIFACT_MISSING'], artifact: null };
+  }
+  const content = fs.readFileSync(diagnosisPath);
+  const sections = readMarkdownSections(content.toString('utf8'));
+  const blockers = INCIDENT_DIAGNOSIS_SECTIONS
+    .filter(({ key }) => !sections.get(key) || sections.get(key).length < 3)
+    .map(({ key }) => `DIAGNOSIS_SECTION_MISSING:${key}`);
+  return {
+    blockers,
+    artifact: {
+      change_id: change.id,
+      kind: 'diagnosis',
+      artifactPath: path.relative(rootDir, diagnosisPath),
+      contentHash: crypto.createHash('sha256').update(content).digest('hex'),
+      metadata: { required_sections: INCIDENT_DIAGNOSIS_SECTIONS.map(({ key }) => key) },
+    },
+  };
+}
+
 function upsertArtifact(db, { change_id, task_id = null, kind, artifactPath, contentHash, metadata }) {
   const id = `art-${crypto.randomUUID().slice(0, 12)}`;
   db.prepare(
@@ -275,6 +329,17 @@ function createChange(db, input, { rootDir = process.cwd() } = {}) {
         change_id: row.id, kind: 'intent', artifactPath: path.relative(rootDir, intentPath),
         contentHash: crypto.createHash('sha256').update(fs.readFileSync(intentPath)).digest('hex'),
       });
+      if (row.kind === 'incident') {
+        const diagnosisPath = path.join(artifactDir, 'diagnosis.md');
+        writeIncidentDiagnosis(diagnosisPath, row);
+        upsertArtifact(db, {
+          change_id: row.id,
+          kind: 'diagnosis',
+          artifactPath: path.relative(rootDir, diagnosisPath),
+          contentHash: crypto.createHash('sha256').update(fs.readFileSync(diagnosisPath)).digest('hex'),
+          metadata: { required_sections: INCIDENT_DIAGNOSIS_SECTIONS.map(({ key }) => key) },
+        });
+      }
       ops.appendEventInTx(db, {
         type: 'change_created', change_id: row.id,
         payload: { kind: row.kind, artifact_root: row.artifact_root },
@@ -410,6 +475,8 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   }
 
   const artifactDir = path.resolve(rootDir, change.artifact_root);
+  const diagnosis = inspectIncidentDiagnosis(change, artifactDir, rootDir);
+  for (const blocker of diagnosis.blockers) blockers.add(blocker);
   if (['standard', 'major'].includes(change.kind)) {
     if (filesUnder(path.join(artifactDir, 'delta')).length === 0) blockers.add('SPEC_DELTA_MISSING');
     if (!fs.existsSync(path.join(artifactDir, 'plan.md'))) blockers.add('CHANGE_PLAN_MISSING');
@@ -434,6 +501,7 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
     ops.tx(db, () => {
       db.prepare("UPDATE changes SET status = 'blocked', updated_at = ? WHERE id = ?")
         .run(nowIso(), change.id);
+      if (diagnosis.artifact) upsertArtifact(db, diagnosis.artifact);
       ops.appendEventInTx(db, {
         type: 'change_blocked', change_id: change.id, payload: { blockers: blockerList },
       });
@@ -452,6 +520,7 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   ops.tx(db, () => {
     db.prepare("UPDATE changes SET status = 'ready', updated_at = ? WHERE id = ?")
       .run(nowIso(), change.id);
+    if (diagnosis.artifact) upsertArtifact(db, diagnosis.artifact);
     upsertArtifact(db, {
       change_id: change.id, kind: 'verification', artifactPath: path.relative(rootDir, verificationPath),
       contentHash: crypto.createHash('sha256').update(fs.readFileSync(verificationPath)).digest('hex'),

package/mcp-server/lib/change-workflow.test.cjs

@@ -38,6 +38,14 @@ function standardEvidence() {
   ];
 }
 
+function incidentEvidence() {
+  return [
+    { category: 'diagnosis', status: 'pass', evidence: 'Structured diagnosis artifact reviewed.' },
+    { category: 'diff', status: 'pass', evidence: 'Root-cause fix diff reviewed.' },
+    { category: 'tests', status: 'pass', evidence: 'Regression test reproduces then verifies the fix.' },
+  ];
+}
+
 test('createChange persists a change and an inspectable external-provider context manifest', () => {
   const fx = fixture();
   try {
@@ -257,3 +265,82 @@ test('updateChange rejects whitespace-only title or intent outside the MCP bound
     cleanup(fx);
   }
 });
+
+test('incident changes create a durable structured diagnosis artifact', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-incident-diagnosis', title: 'Diagnose runtime failure', kind: 'incident',
+      intent: 'Reproduce and fix the runtime failure at its root cause.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal runtime repair.' },
+    }, { rootDir: fx.rootDir });
+
+    const diagnosisPath = path.join(path.dirname(created.intent_path), 'diagnosis.md');
+    assert.ok(fs.existsSync(diagnosisPath));
+    const text = fs.readFileSync(diagnosisPath, 'utf8');
+    for (const heading of ['Reproduction', 'Hypotheses', 'Root cause', 'Regression test', 'Recovery']) {
+      assert.match(text, new RegExp(`^## ${heading}$`, 'm'));
+    }
+    const artifact = fx.db.prepare(
+      "SELECT kind, path, content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-diagnosis');
+    assert.equal(artifact.kind, 'diagnosis');
+    assert.match(artifact.content_hash, /^[0-9a-f]{64}$/);
+    assert.equal(path.join(fx.rootDir, artifact.path), diagnosisPath);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('incident convergence requires every structured diagnosis section and refreshes its artifact hash', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-incident-converge', title: 'Converge runtime diagnosis', kind: 'incident',
+      intent: 'Require inspectable debugging evidence before incident closure.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal runtime repair.' },
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'incident-task', title: 'Fix diagnosed failure', type: 'bugfix', priority: 'P0',
+      change_id: 'chg-incident-converge',
+    });
+    ops.updateTaskStatus(fx.db, 'incident-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'incident-task', 'completed');
+    changes.compileContext(fx.db, { id: 'chg-incident-converge' }, { rootDir: fx.rootDir });
+
+    const blocked = changes.convergeChange(fx.db, {
+      id: 'chg-incident-converge', evidence: incidentEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(blocked.ready, false);
+    assert.ok(blocked.blockers.includes('DIAGNOSIS_SECTION_MISSING:reproduction'));
+    assert.ok(blocked.blockers.includes('DIAGNOSIS_SECTION_MISSING:root-cause'));
+
+    const diagnosisPath = path.join(path.dirname(created.intent_path), 'diagnosis.md');
+    const beforeHash = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-converge').content_hash;
+    fs.writeFileSync(diagnosisPath, [
+      '# Incident diagnosis: Converge runtime diagnosis', '',
+      '## Reproduction', '', 'The projection worker fails after an interrupted claim.', '',
+      '## Hypotheses', '', 'A stale running job is never returned to the pending queue.', '',
+      '## Root cause', '', 'Boot recovery did not consume interrupted projection state.', '',
+      '## Regression test', '', 'The test seeds a stale running job and verifies requeue.', '',
+      '## Recovery', '', 'Requeue the job after the stale cutoff and replay projection.', '',
+    ].join('\n'));
+
+    const ready = changes.convergeChange(fx.db, {
+      id: 'chg-incident-converge', evidence: incidentEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(ready.ready, true);
+    const afterHash = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-converge').content_hash;
+    assert.notEqual(afterHash, beforeHash);
+    assert.equal(
+      afterHash,
+      require('node:crypto').createHash('sha256').update(fs.readFileSync(diagnosisPath)).digest('hex'),
+    );
+  } finally {
+    cleanup(fx);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, and Codex CLI.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -58,7 +58,7 @@ Choose the smallest honest kind:
 | `quick` | localized fix or tiny behavior change | diff, tests, spec |
 | `standard` | normal feature or cross-file change | diff, tests, spec, docs, review |
 | `major` | architecture, public contract, migration, or broad redesign | diff, tests, spec, docs, review |
-| `incident` | production/runtime failure requiring diagnosis | diagnosis, diff, tests |
+| `incident` | canonical debug lane for a production/runtime failure | diagnosis, diff, tests |
 
 When uncertain between two kinds, choose the higher-risk kind. Classification
 changes the proof required; it must not be used to bypass evidence.
@@ -91,14 +91,18 @@ The change directory is the bounded execution packet:
   context-manifest.json
   delta/                  # required for standard and major
   plan.md                 # required for standard and major
+  diagnosis.md            # created and structurally required for incident
   verification.md         # generated by convergence
 ```
 
 For `standard` and `major`, write delta documents under `delta/` describing
 what changes relative to the current baseline. Do not copy the whole baseline.
 Write `plan.md` with live entry points, files/contracts, tests, documentation,
-and rollback. For `quick` and `incident`, add only artifacts needed to make the
-decision and evidence inspectable.
+and rollback. For `quick`, add only artifacts needed to make the decision and
+evidence inspectable. For `incident`, complete the generated `diagnosis.md` with
+non-empty `Reproduction`, `Hypotheses`, `Root cause`, `Regression test`, and
+`Recovery` sections. Free-form convergence evidence never substitutes for this
+durable diagnosis artifact.
 
 Create at least one task through `task.create` with `change_id` set. Split only
 when ownership, dependencies, or independent verification justify it. All task
@@ -116,6 +120,11 @@ context, not permission to silently refresh or mutate the external provider.
 
 ## 6. Route execution
 
+- For `incident`, diagnosis is the first execution slice. Route it to the bundled
+  `debugger` agent when the Host exposes native subagents; otherwise the primary
+  Host follows the same four-phase method. Supply only the compiled change/task
+  context. The primary Host owns the fix, updates `diagnosis.md`, and reruns the
+  discriminating regression test.
 - Implement one linked task with `/ultra-dev <task-id>`.
 - Run `/ultra-test` for project-level evidence.
 - Run `/ultra-review` when the change kind requires review.

package/skills/ultra-deliver/SKILL.md

@@ -141,7 +141,9 @@ evidence required by kind:
 
 - `quick`: diff, tests, spec;
 - `standard` / `major`: diff, tests, spec, docs, review;
-- `incident`: diagnosis, diff, tests.
+- `incident`: diagnosis, diff, tests. The diagnosis evidence must point to the
+  completed `diagnosis.md`; convergence separately validates all five required
+  debugging sections and cannot be satisfied by the evidence string alone.
 
 Evidence must name concrete commands, artifacts, or file paths. If blockers are
 returned, stop before tag/push and route to the owning workflow. Do not weaken

package/skills/ultra-doctor/SKILL.md

@@ -66,9 +66,16 @@ remaining incident unresolved.
 For an installed hook that points to a missing cached file:
 
 1. capture the exact hook config path and missing target;
-2. verify the currently installed plugin/cache version;
-3. reinstall or regenerate the host-native plugin through the adapter;
-4. rerun read-only doctor and a host hook smoke test.
+2. run the separate read-only installer boundary check:
+   `npx ultra-builder-pro-cli --<runtime> --local --doctor --json` (or use
+   `--global` when that is the actual install scope);
+3. preserve its provenance, asset-hash, and host-contract findings;
+4. reinstall or regenerate the host-native plugin through the adapter;
+5. rerun both installer doctor and `system.doctor`, then a host hook smoke test.
+
+`system.doctor` diagnoses project `.ultra/state.db` and workflow recovery.
+Installer `ubp --doctor` diagnoses the installed plugin files and host wiring.
+Neither report substitutes for the other.
 
 Do not bypass a broken hook by changing application implementation, and do not
 treat a hook failure as project-code evidence.

package/spec/mcp-tools.yaml

@@ -630,7 +630,7 @@ tools:
   # ────────────────────────── change family ──────────────────────────────
   - name: change.create
     family: change
-    description: Create a continuous feature, fix, redesign, or incident change unit and its initial context manifest.
+    description: Create a continuous feature, fix, redesign, or incident change unit and its initial context manifest; incidents also register a five-section diagnosis artifact.
     phase: '9'
     writer_role: mcp
     input_schema:
@@ -860,7 +860,7 @@ tools:
 
   - name: change.converge
     family: change
-    description: Deterministically verify task, spec, test, documentation, review, and context evidence before closure.
+    description: Deterministically verify task, spec, test, documentation, review, context, and incident diagnosis structure before closure.
     phase: '9'
     writer_role: mcp
     input_schema: