Compass 6.0.0

Compass 6.0.0 is a major release. It makes a project's configuration a file a person edits and a tool can check, renames the vocabulary and the commands, and adds an opt-in GitHub label sync. It removes no command. It does change the manifest schema to 3.0 and one output shape, so update every checkout and plugin together (see "What breaks").

New

Configuration in compass.yml

compass.yml at the project root is the one file a person edits. It holds the project's settings and, optionally, its edits to the shipped default. It extends compass:default@6, and a project that sets nothing runs on the default. A 6.x release of the default never changes a value that 6.0.0 defines.

• Presets. The shipped default is a preset directory, governance/presets/default/. governance/routing-policy.yml and governance/guardrails.yml are views generated from it and stay through 6.x. compass preset init scaffolds a team preset repository and compass preset test runs a preset's fixtures and checks its locks.
• Layers. A layer can add, set, replace or remove an entry. compass policy lint checks a layered project, compass policy show prints every resolved field with the layer that set it, and compass policy diff compares two configurations by classification and by replaying assessments.
• Waivers and locks. A change that loosens its parent needs a waiver with an approver. A framework lock cannot be removed by a lower layer, and a project that unlocks a framework entry is reported non-conformant.
• Generations. compass approach evaluate --write stores the configuration an issue runs against as a numbered generation. A later change to compass.yml cannot change an issue that is already running. compass issue configure changes an issue's own configuration, and compass issue migrate --config pins an issue to the installed versions.
• Git parents. A project can name git parents, singly or in a chain. Each is pinned by sha and judged against the default like any other layer. compass policy update moves a project to a new major of the shipped default and asks again for approval of each affected waiver.
• Judged checks. A check can pass on a recorded review. compass evidence review records the verdict, its reason and the reviewer.
• Approvers. approvers name who may approve a waiver, a human check or an exit. compass evidence approve records a person's approval or rejection with its approver.
• Stage entry and exit lists. Each stage's entry and exit lists are evaluated, so a stage can name what must hold before it starts and before it ends.
• Approach table. compass approach render writes the delivery approaches as one HTML table, one column per stage.
• Artifact freshness. An opt-in capability that records a document's digest and reports the document as stale when an artifact it depends on has changed.
• Receipt provenance. compass issue receipt shows where each rule, waiver, lock and check came from.
• Templates. compass issue template show prints a document template with its checklists rendered from the issue's stage lists.
• Migration. compass policy migrate turns copied governance and a .compass/config.yml into a compass.yml. /compass:init writes a minimal compass.yml for a new project and copies no governance.

Vocabulary and commands

6.0.0 renames the depth words (full becomes thorough, light becomes lightweight, full-plus-backfill becomes thorough-with-follow-up), the size standard (now medium), the run stage build (now implement), the friction key phase (now stage) and the stored issue statuses. An issue's state is now backlog, ready, in-progress, in-review or done, and it is read from the issue's records. compass issue blocked set and compass issue blocked remove flag an issue that is in progress or in review. compass spec sync merges the base branch and re-derives the living spec.

Eight released command spellings are renamed. The old spellings keep working through an alias until 7.0.0. Each prints the new spelling on standard error, and standard output and the exit code are the new command's.

Old	New
approach summary	approach show
issue set-status	issue status set, or issue status remove for active
policy review-rules	review-rule list
issue dashboard	issue dashboard render
issue artifact	issue artifact set
migrate	issue migrate
issue subtask update	issue subtask set
run --stage build	run --stage implement

The old words in manifests, copied governance and .compass/config.yml are also read until 7.0.0. issue status remove reopens a closed issue, so a script that ran issue set-status active on a landed issue keeps working.

GitHub label sync (opt in)

Compass can write an issue's domain labels and workflow state to the GitHub issue it is linked to. It is off by default. The github_labels key in compass.yml has two switches, domain and status. With both off, no command calls GitHub.

• compass issue link set links a Compass issue to a GitHub issue. The manifest schema gains an optional github field (repo, number).
• compass issue labels sync writes the labels now.
• Compass writes one way. It never reads a label back into the manifest, and compass issue lint reports the issue as out of sync when a label differs on GitHub.

See docs/github-labels.md.

What breaks

6.0.0 removes no command. These are the changes that can break a caller.

• Manifest schema 3.0. A 6.0.0 command reads schemas 1, 2 and 3 and writes 3.0. The first save of a manifest that holds old words copies the original to manifest.yml.v5.bak. A v5.6.0 check, issue lint, ci, gate pass, approach evaluate and approach summary refuse a 3.0 file and exit 2. A v5.6.0 next, flow, analyze, retro and issue dashboard read it and exit 0, and tdd-green writes to it, so they can read it wrongly.
• Update everything together. Update every checkout and every installed plugin at the same time. Do not run a v5.6.0 ship-commit on a 6.0.0 tree: it does not read the new words and drops the issue from the living spec.
• No supported rollback. A problem is fixed forward in a 6.0.x release. Restoring manifest.yml.v5.bak discards everything recorded after the first rewrite.
• compass flow --json keys. The keys held, next_up, landed_this_week and abandoned are removed. The board now has backlog, ready, in_progress, in_review, done_this_week and closed. A closed entry carries its close_reason.
• Output names. A project with a compass.yml sees approach evaluate name the intent document intent, the launch document launch-readiness and the last stage ship. A project without one keeps the 5.6.0 document names.
• Stricter refusals. A compass.yml that fails compass policy lint makes compass approach evaluate --write refuse to commit. A project with a compass.yml and a .compass/config.yml that still holds settings is refused (settings-conflict). When a .compass/config.yml also exists, a compass.yml with no schema: key is not taken for Compass's file: the old file is read and a warning says so.
• Old CLI on new data. A v5.6.0 CLI reading a manifest that has a generation: key fails compass issue lint.
• A tool to rewrite configuration files (compass.yml, copied governance and .compass/config.yml) into the new words is owed before 7.0.0. Until then they are read in their old words.

How to upgrade

Read docs/upgrade-6-0-0.md. It has the full tables of renamed words and commands, the notice a first save prints, and why there is no supported rollback. To move settings into compass.yml, run compass policy migrate (a dry run) and then compass policy migrate --apply. To rewrite every issue in one run, use compass issue migrate --apply. It refuses unless .compass/work is tracked by git or you pass --i-have-a-copy to confirm you have a copy.

docs/configuration.md explains compass.yml. The documentation and the plugin's agent instructions now describe the 6.0.0 model: the shipped guardrails and strategies come from the plugin, compass policy show prints the configuration in force, and a project changes the rules in compass.yml. A 5.x project that has not run compass policy migrate keeps running on its own copied governance/. The glossary and compass terminology now give only what each term means.

Fixed

• compass issue dashboard render shows each issue's state, close reason and blocked reason, where it printed Status: ? for an issue in progress.
• compass policy show no longer says the generation store has not landed, and the compass issue migrate help names schema 3.0.
• The release, security and upgrade pages list every command that can fetch a git parent, and say which v5.6.0 commands refuse a 3.0 manifest.

Checked

• A project with no configuration behaves as 5.6.0, apart from the renamed words, for routing output, what each delivery approach owes, compass check verdicts on archived issues, CLI exit codes on a recorded command corpus, pre-tool hook decisions on a recorded corpus, and the readability of old manifests, evidence and receipts. Each is compared with a baseline captured once from 5.6.0.

Queued against this release

None that this release changes. Four queued issues carry a recommendation and wait for a maintainer decision:

• Governance merge versus replace: 6.0.0 adds layers in compass.yml as a way to extend the default, but the issue's report about a copied governance/ directory has not been re-checked against 6.0.0.
• Whether this repository declares project guardrails: its compass.yml stays settings-only.
• Approvals bound to what was approved: 6.0.0 records the approver with an evidence approval, not the revision approved.
• An architecture decision record whose status disagrees with the index: unrelated to this release.

Verify the download

compass-6.0.0.tar.gz, SHA-256 4c3886479a4965bae86df1e14f29ccb7ca91dfcddf3aac701f267ceb20b918ce.