governance-check

Files (1)

• SKILL.md

SKILL.md (first lines)

# Governance Check

Two kinds of rule govern Compass, and the governance check is the
moment they are applied to a plan, spec, or change. It is not one pass/fail
against one document - it is three distinct walks against three
distinct sources, and each has its own standard of proof. The prose is in
`${CLAUDE_PLUGIN_ROOT}/governance/`; the rules in force are what
`compass policy show` prints. An unmigrated 5.x project runs on its own copied
`governance/` until `compass policy migrate`.

- `guardrails.md` - **hard, checkable, blocking.** A guardrail is cleared with
  evidence; a failed guardrail stops the work. A guardrail beats a strategy.
- `strategies.md` - **soft, assessed, accretive.** A strategy is judged, not
  cleared; following it is the default, departing from it is allowed *and
  recorded*. A strategy never stops the work on its own.
- `routing-policy.md` - the same split applied to the router: **routing
  guardrails** bound the delivery approach, **routing strategies** bias it.

Read the governance fresh before you start: a cached memory of an earlier
read is not the current file.

**Record which governance you read.** Write the layers that
`compass policy show` names (for example `default@6.0.0, project`) and the
issue's `generation:` from `manifest.yml` into the check, the way section 3a
(policy provenance) of `${CLAUDE_PLUGIN_ROOT}/templates/delivery-approach.md`
does. An unmigrated 5.x project has no layers line: record the `version:` of its
copied `guardrails.yml` and `routing-policy.yml` instead. A check that names
nothing cannot be told apart from one run against wording that has since
changed, and the prose files carry no version of their own to compare.

## Before you start

Run `compass policy show` to see the rules in force, then read the reasons in
`${CLAUDE_PLUGIN_ROOT}/governance/guardrails.md`, `strategies.md` and
`routing-policy.md`. A new project has no `governance/` directory (an
unmigrated 5.x project keeps its copied one): the shipped default preset is in force, and `compass.yml` holds only what the
project changed. The shipped defaults alone are a complete governance state: "the shipped default
guardrails, the shipped default strategies, and zero project additions" is a
fully legitimate thing to check against. Do not treat an un-extended project
as a reason to stop.

If the project has `governance/decisions/`, read it too. Each entry records a
product decision a named person made, and never changes. A design that
reverses one is reported as "settled by <path>", for the person to reopen
with a new entry, not passed or failed on your judgment.

## Walk 1 - the guardrails (hard, evidence)

Walk the plan, spec, or change against every applicable guardrail - the five
shipped defaults and any project guardrails.

The five default guardrails:

- **Tested before it lands.** Is the work shaped so that nothing reaches
  `main` without a passing automated test it traces to? At Plan, this means the
  plan introduces work test-first (the TDD strategy is how) and the test
  surface is planned. At the verify stage, it is cleared with the recorded run.
- **Acceptance defined before it is built.** Does every piece of planned
  code trace to a stated, checkable acceptance criterion that exists *before*
  the code? The BDD strategy (Given/When/Then scenarios) is the default way to
  satisfy this; the guardrail itself is the outcome - acceptance is stated and checkable.
- **Traceability holds.** Are both chains planned for and intact -
  code → acceptance criterion → intent, and public claim → backing criterion?
- **Evidence, not assertion.** This one is *about* the others: a guardrail
  is cleared with artifacts and command output, never a claim. When you record
  a guardrail result, the proof is the artifact.
- **A human signs off on the irreversible.** Does anything that can lose
  data, move money, or breach auth or privacy have an explicit human checkpoint
  before it lands? Check the plan routes such work to where the checkpoint <!-- vocabulary-scan: allow - route is a verb here -->
  happens.

Then any project guardrails - concrete, measurable floors a project has added
(a coverage floor, a no-secrets-committed rule, a tested-rollback rule). Floors
only ratchet up: a plan can exceed a floor, never fall short of one.

**The standard of proof is evidence.** At Plan you are checking the plan is
*shaped* to clear each guardrail; at the verify stage the guardrail is *cleared* with the
verifier's artifacts. Either way: "looks fine" is not a result. For each
guardrail, record **clears** (with the evidence, or the plan element that will
produce it) or **fails** (with the specific guardrail and how it is crossed). A
plan that crosses a guardrail does not proceed - it is revised, or the issue
is re-assessed. There is nothing to waive a guardrail *for*; a guardrail beats every
strategy and every convenience.

## Walk 2 - the strategies (soft, assessed)

Walk the same plan, spec, or change against the applicable strategies - the
shipped default method strategies (including **BDD** and **TDD**) and any
project strategies (product, engineering, voice & positioning).

The standard here is different and you must keep it different. A strategy is
**assessed**, not cleared:

- Did the work follow the strategy? This is honest judgment - is this the
  simplest thing that works, does it follow the team's engineering
  strategies, does the copy fit the voice strategies.
- Where it departed from a strategy, **is the departure recorded?** A recorded
  departure is the system working, not a failure. An *unrecorded* departure is
  the thing to flag - not because the departure is wrong, but because it was
  silent.
- Record the result **as judgment**, clearly labeled as judgment - never
  dressed up as evidence. A strategy not followed is a note and a conversation,
  not an automatic stop.

### The no-placeholders check

Before committing `technical-design.md`, run:

```
compass plan lint
```

It reports phrases that mean the plan is not actually finished - `TBD`, `TODO`,
"implement later", "add appropriate error handling" - and work units that
promise tests without naming any: a decision quietly deferred to whoever
builds it, who then makes it alone and unrecorded.

**A reported hit is a note, rather than a stop.** The command always exits 0.
Assess each hit as judgment: fill the gap in, or record why the placeholder

From ayeo-io/compass, Apache-2.0.

More from ayeo-io/compass