docs(openspec): the process lives in config.yaml (verbara-meta/ADR-0023)

[Harol-Reina]

The measurement that justifies this

openspec/config.yaml ordered, in rules.tasks:

"Use Subagent-Driven Development with FCM batching: Phase A foundation (batch) -> Phase B critical components (focused) -> Phase C integration (batch)."

That line reached the agent verbatim, inside the <rules> block of openspec instructions tasks. It names a skill of a third-party process plugin that is not installed in the active Claude config — an instruction that cannot be carried out. An agent that cannot comply either improvises or silently skips, and both look identical in a green PR. "FCM" was never defined anywhere an agent reads; it is defined twice, incompatibly, in tracked plans (Pro .../2026-03-19-sprint17-pro-analytics.md:13 = Foundation-Critical-Mechanical, Platform docs/plans/completed/2026-04-26-r5.3-execution-plan.md:7 = Foreground-Coordinator + Multiple-background-subagents).

Separately, the ecosystem's § Verification gate (run this repo's own ci.yml fast steps on the integrated branch before committing) travelled only on operations.apply.guidance — the channel /opsx:apply itself labels "optional additive advice… do not follow it". The strongest rule in the ecosystem was on the weakest wire.

Rollout of verbara-meta/ADR-0023 — The process lives in openspec/config.yaml; no third-party process plugin. Same-shaped PR in all five code repos.

Before / after

rules.tasks — one entry replaced by two, naming no external skill:

-    - "Use Subagent-Driven Development with FCM batching: Phase A foundation (batch) -> Phase B critical components (focused) -> Phase C integration (batch)."
+    - "Order execution in three phases — A foundation (batched), B critical components (one focused subagent each), C integration (batched) — with a fresh subagent per task, never inline in the main session."
+    - "For a bug fix, write the failing regression test first, against the unfixed code, and paste its failure verbatim into `tasks.md`. For new capability, tests may batch into Phase C."

The second rule settles an inconsistency that is ours, not the plugin's: of the open changes, four are tests-first and three are tests-last, with no rule saying which is right.

context: — the § Verification gate appended as a hard constraint, because context: is the one channel delivered verbatim to propose and apply and archive:

+  Verification gate (verbara-meta/ADR-0023, non-negotiable):
+  - Before any commit or push, run the fast, deterministic, non-service steps of this repo's own
+    .github/workflows/ci.yml on the integrated branch — build plus the touched tests plus `openspec validate`
+    is a strict subset, because a tree-scanning guard is tripped by a change anywhere.

docs/specs/2026-03-31-v121-operations-design.md:3 — the REQUIRED SUB-SKILL banner reframed as history, not instruction, in the shape Verbara.Sdk.Pro/docs/specs/2026-03-20-pro-agent-assist-design.md:6-8 already uses for its superseded storage mechanism. The dated record is preserved; only the live order is retired. After this, no live tracked file in this repo cites the plugin namespace (sweep below).

.gitignore — docs/superpowers/ added next to the existing .superpowers/ and .worktrees/, completing the uniform six-repo contract.

Historical prose is untouched: docs/plans/, docs/research/, docs/decisions/, CHANGELOG.md and openspec/changes/archive/ keep their period-correct records (Verbara.Sdk.Pro/openspec/specs/docs-path-hygiene/spec.md:48-49 is the live spec that requires this). The one open tasks.md that still carries the old banner (promote-community-smoke-to-gating) dies by archiving, not by rewrite — ADR-0023 "What this does not fix".

Ratchet conditions satisfied (/xr:doctor check 21, no-process-plugin)

Run with the check's own probe:

$ python3 -c '<xr-doctor.sh check 21 probe, verbatim>' openspec/config.yaml
rules.tasks FCM/Subagent-Driven Development present: no
context: carries ci.yml + integrated branch: yes
VERDICT: PASS

$ grep -n "FCM\|Subagent-Driven Development" openspec/config.yaml
(no FCM / Subagent-Driven Development anywhere in config.yaml)

$ git grep -I -l -i -F -e 'superpowers:' -- ':!docs/plans' ':!docs/research' ':!docs/decisions' ':!CHANGELOG.md' ':!*/archive/*'
citation sweep rc=1 (1 = clean)

Part (a) of the check (live tracked citations) also flips to PASS — it was WARNing on one file.

Verification

openspec validate does not read config.yaml: a broken YAML is discarded silently and merges green. So the config is parsed, and the rules are proven to reach the agent.

$ python3 -c "import yaml;d=yaml.safe_load(open('openspec/config.yaml'));print(list(d.keys()))"
['schema', 'context', 'rules', 'operations']        # rules.tasks = 4 entries

$ npx -y @fission-ai/openspec@1.13.1 instructions tasks --change wire-api-rate-limiting
...
Verification gate (verbara-meta/ADR-0023, non-negotiable):
- Before any commit or push, run the fast, deterministic, non-service steps of this repo's own
  .github/workflows/ci.yml on the integrated branch — build plus the touched tests plus `openspec validate`
  is a strict subset, because a tree-scanning guard is tripped by a change anywhere.
</project_context>

<rules>
- When the change spans repos, spell out the cross-repo sequence: ...
- Verification tasks MUST include `dotnet test` green and CI green, ...
- Order execution in three phases — A foundation (batched), B critical components (one focused subagent each), C integration (batched) — with a fresh subagent per task, never inline in the main session.
- For a bug fix, write the failing regression test first, against the unfixed code, and paste its failure verbatim into `tasks.md`. For new capability, tests may batch into Phase C.
</rules>

This repo's own ci.yml fast, deterministic, non-service steps, run on the integrated branch:

$ npx -y @fission-ai/openspec@1.13.1 validate --all --strict --no-interactive   # job: OpenSpec Validate
Totals: 30 passed, 0 failed (30 items)                                          rc=0

$ python3 scripts/check-endpoint-invariants.py                                  # job: Invariant Gates
Gate #6 (no empty catch in Endpoints/**): OK.
  src/Verbara.Platform.Api/Program.cs: 1910 LOC (budget 1932)
Gate #9 (orchestrator LOC budgets): OK.
Gate #7 (no Guid.NewGuid in credential mints): OK.
Gate #10 (no Npgsql legacy-timestamp switch): OK.
Gate #11 (no SpecifyKind relabel in Postgres stores): OK.                       rc=0

$ python3 -m unittest discover scripts/tests                                    # job: Coverage Script Tests
Ran 82 tests in 8.556s
OK                                                                              rc=0

$ ./scripts/ci/classify-docs-only.sh "$(git rev-parse origin/main)" HEAD        # job: Docs-only gate
docs_only=false

Note on the last one: the classifier is fail-closed on top-level non-.md paths, so touching .gitignore makes this diff docs_only=false and the heavy jobs (Build + Unit Tests, Coverage Ratchet, AOT Publish, Live-DB) will run here in full. That is correct behaviour, not a regression — and none of the three changed files enters compilation. Those jobs were not reproduced locally: they need the private Pro NuGet feed plus a live Postgres service container, i.e. exactly the service steps the gate excludes.

🤖 Generated with Claude Code