docs(specs): harden OpenSpec authority lifecycle

2026-08-23 17:49:52 +03:00
parent b8a3f96316
commit 51344d4988
18 changed files with 608 additions and 13 deletions
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+verifier="$script_dir/verify-openspec-authority.sh"
+
+if [[ ! -f "$verifier" ]]; then
+  echo "expected verifier at $verifier" >&2
+  exit 1
+fi
+
+fixture=$(mktemp -d)
+trap 'rm -rf "$fixture"' EXIT
+
+write_file() {
+  local relative_path=$1
+  local content=$2
+  mkdir -p "$fixture/$(dirname "$relative_path")"
+  printf '%s\n' "$content" > "$fixture/$relative_path"
+}
+
+write_file "specs/.openspec-store/store.yaml" $'version: 1\nid: wealth-ledger-specs'
+mkdir -p "$fixture/specs/openspec"
+
+for path in AGENTS.md frontend/AGENTS.md backend/AGENTS.md specs/AGENTS.md docs/AGENTS.md; do
+  write_file "$path" $'OpenSpec store: wealth-ledger-specs\nUse --store wealth-ledger-specs\nSDD artifacts only in specs/openspec\nreferences/** is read-only.'
+done
+
+entrypoints=(
+  .opencode/commands/opsx-apply.md
+  .opencode/commands/opsx-archive.md
+  .opencode/commands/opsx-continue.md
+  .opencode/commands/opsx-explore.md
+  .opencode/commands/opsx-new.md
+  .opencode/commands/opsx-propose.md
+  .opencode/commands/opsx-sync.md
+  .opencode/commands/opsx-verify.md
+  .opencode/skills/openspec-apply-change/SKILL.md
+  .opencode/skills/openspec-archive-change/SKILL.md
+  .opencode/skills/openspec-continue-change/SKILL.md
+  .opencode/skills/openspec-explore/SKILL.md
+  .opencode/skills/openspec-new-change/SKILL.md
+  .opencode/skills/openspec-propose/SKILL.md
+  .opencode/skills/openspec-sync-specs/SKILL.md
+  .opencode/skills/openspec-verify-change/SKILL.md
+)
+
+for path in "${entrypoints[@]}"; do
+  write_file "$path" 'openspec status --store wealth-ledger-specs'
+done
+
+archive_gate='openspec status --store wealth-ledger-specs
+Do not ask for or accept a confirmation override.'
+write_file ".opencode/commands/opsx-archive.md" "$archive_gate"
+write_file ".opencode/skills/openspec-archive-change/SKILL.md" "$archive_gate"
+
+run_verifier() {
+  WEALTH_LEDGER_WORKSPACE="$fixture" bash "$verifier"
+}
+
+run_verifier
+
+mkdir -p "$fixture/frontend/openspec"
+if run_verifier; then
+  echo "expected additional OpenSpec root to fail" >&2
+  exit 1
+fi
+rmdir "$fixture/frontend/openspec"
+
+write_file ".opencode/commands/opsx-apply.md" 'Without a store, commands act on the nearest local openspec root.'
+if run_verifier; then
+  echo "expected implicit store selection to fail" >&2
+  exit 1
+fi
+write_file ".opencode/commands/opsx-apply.md" 'openspec status --store wealth-ledger-specs'
+
+write_file ".opencode/commands/opsx-apply.md" $'openspec status --store wealth-ledger-specs\nFor another store, append --store "<id>" when applicable.'
+if run_verifier; then
+  echo "expected conditional store selection to fail" >&2
+  exit 1
+fi
+write_file ".opencode/commands/opsx-apply.md" 'openspec status --store wealth-ledger-specs'
+
+write_file ".opencode/commands/opsx-apply.md" $'openspec status --store wealth-ledger-specs\nRun `openspec status --change "example" --json` before continuing.'
+if run_verifier; then
+  echo "expected unscoped OpenSpec invocation to fail" >&2
+  exit 1
+fi
+write_file ".opencode/commands/opsx-apply.md" 'openspec status --store wealth-ledger-specs'
+
+write_file ".opencode/commands/opsx-apply.md" $'openspec status --store wealth-ledger-specs\nUse artifact graph (openspec status --change "example" --json) before continuing.'
+if run_verifier; then
+  echo "expected parenthesized unscoped OpenSpec invocation to fail" >&2
+  exit 1
+fi
+write_file ".opencode/commands/opsx-apply.md" 'openspec status --store wealth-ledger-specs'
+
+write_file ".opencode/commands/opsx-archive.md" $'openspec status --store wealth-ledger-specs\nDon\x27t block archive on warnings - just inform and confirm.'
+if run_verifier; then
+  echo "expected archive override guidance to fail" >&2
+  exit 1
+fi
+write_file ".opencode/commands/opsx-archive.md" "$archive_gate"
+
+mkdir -p "$fixture/docs/superpowers/plans"
+if run_verifier; then
+  echo "expected prohibited planning location to fail" >&2
+  exit 1
+fi
+rmdir "$fixture/docs/superpowers/plans"
+rmdir "$fixture/docs/superpowers"
+
+mkdir -p "$fixture/references/example/superpowers/plans"
+run_verifier
+
+echo "verify-openspec-authority tests passed"