From 390b3a2e0eb4805f3104a660a937b953e75a195c Mon Sep 17 00:00:00 2001
From: Kent <iamcxa@gmail.com>
Date: Wed, 6 May 2026 14:58:04 +0800
Subject: [PATCH] fix(debrief): make status and schema contracts portable

---
 skills/debrief/SKILL.md              | 14 +++++++----
 tests/test_debrief_skill_contract.py | 36 ++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_debrief_skill_contract.py

diff --git a/skills/debrief/SKILL.md b/skills/debrief/SKILL.md
index 57b7b0a78..fdec9477d 100644
--- a/skills/debrief/SKILL.md
+++ b/skills/debrief/SKILL.md
@@ -148,14 +148,19 @@ Categorize each issue into two buckets:
 
 ### 2e. What's next
 
-Extract the dispatchable list and overall workflow view via the plugin-shipped status helper:
+Extract the dispatchable list and overall workflow view via a local-first status resolver. Do not require a workflow-local status helper: if `{dir}/status` exists and is executable, use it; otherwise fall back to the plugin-shipped commission status helper with `--workflow-dir {dir}`.
 
 ```bash
-{spacedock_plugin_dir}/skills/commission/bin/status --workflow-dir {dir} --next
-{spacedock_plugin_dir}/skills/commission/bin/status --workflow-dir {dir}
+if [ -x "{dir}/status" ]; then
+  {dir}/status --next
+  {dir}/status
+else
+  {spacedock_plugin_dir}/skills/commission/bin/status --workflow-dir {dir} --next
+  {spacedock_plugin_dir}/skills/commission/bin/status --workflow-dir {dir}
+fi
 ```
 
-`{spacedock_plugin_dir}` is the plugin directory containing this skill file (the `skills/` parent). If the plugin-shipped status helper is unreachable, raise the error to the captain rather than working around it — the first officer already invoked `status --boot` to start the session, so an unreachable helper here indicates a real environmental problem worth surfacing.
+`{spacedock_plugin_dir}` is the plugin directory containing this skill file (the `skills/` parent). If `{dir}/status` is absent and the plugin-shipped status helper is unreachable, raise the error to the captain rather than working around it — the first officer already invoked `status --boot` to start the session, so an unreachable helper here indicates a real environmental problem worth surfacing.
 
 Use the helper output to populate:
 - Entities blocked at gates (waiting for captain)
@@ -291,6 +296,7 @@ Write the debrief to `{dir}/_debriefs/{date}-{sequence:02d}.md`:
 
 ```markdown
 ---
+schema_version: 1
 session-date: {YYYY-MM-DD}
 sequence: {N}
 first-commit: {hash}
diff --git a/tests/test_debrief_skill_contract.py b/tests/test_debrief_skill_contract.py
new file mode 100644
index 000000000..eb1b946cc
--- /dev/null
+++ b/tests/test_debrief_skill_contract.py
@@ -0,0 +1,36 @@
+#!/usr/bin/env -S uv run --with pytest python
+# ///
+# requires-python = ">=3.10"
+# ///
+# ABOUTME: Static checks for the spacedock:debrief skill's workflow status and schema contracts.
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEBRIEF_SKILL = REPO_ROOT / "skills" / "debrief" / "SKILL.md"
+
+
+def read_debrief_skill() -> str:
+    return DEBRIEF_SKILL.read_text()
+
+
+def test_debrief_uses_packaged_status_fallback_when_workflow_status_missing():
+    text = read_debrief_skill()
+
+    assert "{dir}/status" in text
+    assert "skills/commission/bin/status" in text
+    assert "--workflow-dir {dir}" in text
+    assert "if `{dir}/status` exists and is executable" in text
+    assert "Do not require a workflow-local status helper" in text
+
+
+def test_debrief_template_emits_schema_version_one():
+    text = read_debrief_skill()
+    template_start = text.index("Write the debrief to `{dir}/_debriefs/{date}-{sequence:02d}.md`")
+    template = text[template_start:]
+
+    assert "schema_version: 1" in template
+    assert template.index("schema_version: 1") < template.index("session-date: {YYYY-MM-DD}")