Compass 7.0.0

Compass 7.0.0 is a major release. It finishes the document set and moves the framework's own text to US English. It removes 8 command spellings that 6.0.0 renamed, and a ninth, issue labels sync. The readers for old words, old approach names, copied 5.x governance and .compass/config.yml stay until 8.0.0.

6.1.0 already carried most of the document set. This list covers what changed since 6.1.0. If you upgrade from 6.0.x, read the 6.1.0 release notes too. docs/upgrade-7-0-0.md covers both steps, one section for each change.

Upgrade

There is no supported rollback. Copy your issue folders before you start.

1. Update every checkout and every installed plugin together. Do not run a 6.x CLI on a 7.0.0 tree.
2. Copy the two issue folders, .compass/work and docs/compass, to a folder outside the project.
3. Run compass issue migrate for a dry run and read the list. Then run compass issue migrate --apply --i-have-a-copy. Its totals must equal the dry run's.
4. Run compass issue render --all --dry-run, then compass issue render --all.
5. If the project has a compass.yml, run compass policy migrate --words to see the old words in it, then compass policy migrate --words --apply. Run compass policy update to move the project to default@7, then compass policy lint.
6. Replace each removed spelling in your scripts, notes and CI with the new one from the table below. A script that reopened a closed issue with issue set-status must run issue status remove.
7. If a script matches the refusal code not-initialised, match not-initialized. The session-start hook prints only the new code (#661).
8. To go back, restore both folders from the copy, together. Restoring the copy discards everything recorded after you took it. To undo a compass policy migrate --apply, run compass policy migrate --undo (#660).

Known issue: compass issue migrate renames a distribution map that declares units: 1 to distribution-map.md.v6.bak. The check multiagent-run-recorded then fails for that issue. Rename the .v6.bak file back to distribution-map.md, then restore the entry with compass issue artifact set distribution-map --status approved --path <the map's path> --reason "<why>" --issue <slug>. Only a project that used the one-unit breakdown before 7.0.0 is affected. The fix is tracked as ayeo-io/compass-delivery#259 [Leave a one-unit distribution map in place when the migration renames stubs] for 7.1.0.

What breaks

These 8 command spellings are removed. Each exits 2 (#658). run --stage build is refused by compass run, which names the stages it permits. The other 7 get the parser's usual error.

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 render
issue artifact	issue artifact set
migrate	issue migrate
issue subtask update	issue subtask set
run --stage build	run --stage implement

issue labels sync is removed too. Use issue github sync. The error for issue labels sync and for issue dashboard adds one line that names the new spelling. The error for the others names no new spelling, so use the table (#658).

Other changes that can stop a script or a session:

• A command refuses an issue whose stored generation is from another major. This applies when another resolver or schema major built the generation. Each command that reads or changes the issue exits 2 and names compass issue migrate --config. The repair commands still run. A closed issue is read, not refused. compass ci, compass flow and compass issue render --all report the issue and continue with the others (#650, #657).

• The pre-tool hook refuses a Bash command it cannot check in time. In a Compass project it refuses a command over 98,304 bytes (bash-command-too-long). It refuses a command in these cases (bash-command-too-complex):

  • more than 400 write targets, 700 $( openers or 20 variable names;
  • a write target over 2,048 bytes;
  • a command over its work budget or its 8-second limit.

  Outside a Compass project the hook skips only the write scan. Claude Code 2.1.295 or later also stops the hook after 15 seconds and blocks the call (#655).

• The pre-tool hook refuses when its working directory is gone. This applies when the folder was removed and CLAUDE_PROJECT_DIR is not set. The hook then refuses an Edit or Write of a file inside a Compass project, with exit 2 (working-directory-gone). Before, the hook ended with exit 1 and the edit ran unchecked (#656).

• The quick-fix skill is removed. Its rules are now in the /compass:quick-fix command. The command and the skill had the same name, and the Skill tool loaded the command in 83 of 86 calls and the skill in none. An agent file or a project instruction that loads the skill by name must run the command (#667).

• The compass ship-commit error has new first lines. When git does not commit, the error opens with the lines git printed. "HEAD did not advance" and "the land did NOT happen" stay (#665).

• A layer that sets both spellings of one check is refused. A compass.yml layer that gives dor-behaviour-is-gwt and dor-behavior-is-gwt different values fails the merge with M-ONE-CHECK (#661).

• The hook text says "initialized by". hooks/pre-tool.sh now prints "This project was initialized by ...". A tool that matches the old printed text initialised by must match the new text (#669).

What is new

• The shipped default is default@7. default@6 stays as a frozen copy of the 6.1.0 preset, so compass policy update can tell which waived fields moved. A project on 6.0.1 has its waivers checked again against the 6.1.0 values (#641, #643).

• A project-scoped design decision needs a record. Each design decision in the technical design has a Scope: line, issue or project. A landing refuses an open issue whose design holds a Scope: project decision that no record in architecture/decisions/ names (project-decision-unrecorded). The refusal names the path compass adr new writes next (#641).

• A regular issue needs a requirements review, and a hotfix needs a bug report. A new regular issue cannot land until its requirements-review.md is approved. A new hotfix cannot land until its bug-report.md is approved (#641).

• The language setting. language in compass.yml is a BCP 47 tag such as en-US or de. When it is set, the session-start hook adds one line that tells the agent to write prose in that language. When it is not set, nothing changes. compass policy lint refuses a malformed value. /compass:init asks the question, and a new project now extends compass:default@7 (#661).

• US English. Compass prints its messages and its --help text in US English (#664). It writes its typed names in US English (#661). Its documents, skills, commands and templates use US English (#669). A guard fails the build when a British spelling returns.

• Typed names in US English, with the old forms read until 8.0.0. Each old name is still read and prints one notice. The new name is the one written (#661).

  Kind	Old name	New name
  kind	judgement	judgment
  check	dor-behaviour-is-gwt	dor-behavior-is-gwt
  skill	behaviour-mapping	behavior-mapping
  refusal code	not-initialised	not-initialized
  state key	initialised	initialized
  readiness key	catalogue_digest	catalog_digest
  JSON key	behaviour, behaviours	behavior, behaviors
  heading	Current Behaviour, Archived Behaviour	Current Behavior, Archived Behavior
  term	catalogue	catalog

  For one release the writer emits both spellings of two saved keys: the readiness record holds catalogue_digest beside catalog_digest, and compass retro --compliance emits behaviour and behaviours beside behavior and behaviors. docs/artifact-catalogue.md is now docs/artifact-catalog.md, and the old page links to it (#661).

• compass policy migrate --undo. It restores a migrated project to its state before compass policy migrate --apply. It is a dry run until you add --apply. It restores the old settings file and any deleted governance file from .compass/legacy/, byte for byte. It refuses, and writes nothing, in these cases:

  • a file the migration wrote has changed;
  • a legacy copy is missing or differs;
  • a signed record exists from after the migration.

  A marker from an earlier migration lacks the digests the undo needs. The undo refuses it and prints the steps to go back by hand (#660).

• The approval guard reads a simple command as words. The guard judged the whole text of a Bash command. A commit message that only mentioned a protected folder was therefore refused. Now the guard does not judge the message text of a simple git or gh command. A command alone can name a protected path in these cases: ls, wc and stat can name a request folder, and cat can name the prompt hook script. Read, Grep, Edit and Write can open the auto-memory folder. The guard judges every other command by its whole text, as before. A refusal names the word it judged (#663).

• /compass:approve names the real cause when no approver can be named. Each of the seven causes has its own message with the next step (#663).

• A comment-only edit of Python or YAML needs no failing test. The hook applies the Edit in memory. It compares the syntax tree (Python) or the parser events (YAML). A pragma, a hidden character, an encoding cookie, a file over 1 MiB or a parse error keeps the old verdict. The rule does not cover shell. evals/*/seed/ is no longer production code (#662).

• The hook judges an edit in another worktree by that worktree's issue. It reads the pointer of the tree that the Edit or Write names. It refuses a tree that it cannot tie to the session's repository (#644).

• A project can add trigger entries without a waiver. Adding an entry to trigger_paths or trigger_contents makes the policy tighter. Removing or replacing one makes it looser, and then a waiver is needed where the check is placed. The check that compares a layer with its parent (the classifier) is now version 11 (#637).

• The define command starts the architect. /compass:define runs the architect before the spec author when the labels match the architect's trigger: public-api, a service in architecture/relations.md, or a lens_trigger_tag in architecture/invariants.yml. The spec author could not start another agent, so this check ran only when a person remembered it (#668).

• The documents describe three scored dimensions. Risk, familiarity and size are scored. Goal and urgency are optional switches. Domain labels are read beside them. 45 places in 20 files that said "four dimensions" now say this (#666).

Changed behavior

• The readers for old words, old approach names, copied 5.x governance, the generated views governance/routing-policy.yml and governance/guardrails.yml, and .compass/config.yml (when compass.yml is absent) stay until 8.0.0, not 7.0.0. The notice says "the old word is read until 8.0.0" (#658).
• compass ci reports a closed issue that records another resolver or schema major as a failure of that issue, and checks the rest. Before, it exited 2 with no summary (#657).
• compass ci in advisory mode prints FAIL, not PASS, after a failed check. The exit code stays 0 (#631).
• A reassess that leaves the approach unchanged and is given --reason records an entry of kind unchanged. compass retro and the flow digest do not count it as a re-assessment (#636).
• checked_at names the current stages refine, implement and ship. governance/guardrails.yml is version 1.33.1 (#633).
• In the Compass repository itself, compass policy lint reports invalid policy YAML as a structure error with exit 1, not exit 2 (#651).

Kept until 8.0.0

• Old words in a manifest, a policy or a flag, such as the stage mode full and the size standard.
• Old approach names.
• Copied 5.x governance and the generated views governance/routing-policy.yml and governance/guardrails.yml.
• .compass/config.yml, when compass.yml is absent.
• A project waiver with approved_by: LEGACY, which lint reads with a warning.
• The old typed names in the table above.

Run compass policy migrate --words and compass policy migrate before 8.0.0, so that no project depends on a reader that 8.0.0 removes.

Fixed

• Compass refuses a manifest that is not valid UTF-8, or that holds a list, and the message names the file (#648, #628).
• compass policy show names the copied governance it read (#647).
• A one-unit breakdown is recorded from the units line (#638).
• compass retro restores standard output when a report section fails. compass retro --impact reads each manifest once (#625, #652).
• compass board render and compass flow --html refuse a page that they cannot write. They print one line and no traceback (#627).
• compass ship-commit no longer leaves out an issue's own edit of docs/system-spec.md when it judges a whole commit (#632).
• compass evidence approve --delegated refuses an --as word that it cannot read. The hook refuses a glob that reaches the delegation files (#642).
• The help of compass approach evaluate states which configuration the command applies (#626).
• The upgrade guide tells a project that replaced a shipping approach that the entry needs release_line. On regular and full it also needs an intent (#639).
• The docs site publishes the GitHub labels pages and the 7.0.0 upgrade page. It adds a page on waiver and lock syntax (#649).

Repository and CI only:

• The shipped-releases table lists v6.1.0 (#624). A follow-up pull request adds v7.0.0.
• CI shard times were rebuilt (#653).
• Timing tests are stable (#629, #635, #654).
• The eval harness drops plugin folders under any configuration folder (#630).
• The review workflow sets up Python (#634).

Queued against this release

compass flow --digest on 20 October 2026 lists 35 backlog issues. Four are older than 14 days and carry a recommendation. These backlog issues touch what 7.0.0 changes:

Backlog issue	What 7.0.0 changes	Decision
An approval does not bind to what was approved (#118)	An approval request now holds the document's digest and a single-use nonce. A rewritten approved document moves back to draft	Waits for the maintainer's decision on its recommendation. Not yet checked against 7.0.0
compass retro can leave stdout pointing at a dead buffer (#117)	#625 put the redirect in a with block	Fixed by #625. Close it
Every spine-writing verb leaves the review page stale (#121)	Compass renders the documents after each command that changes a record	Probably met. Not yet checked against 7.0.0
A feature, hotfix or initiative record blocks every code edit (no GitHub issue)	The delivery-approach record is in the documents folder on every approach, and the hooks find it	Probably met. Not yet checked against 7.0.0
The glossary prints a scan marker mid-sentence (no GitHub issue)	docs/glossary.md on main holds no marker text	Fixed. Close it
Manifest fields keep the retired word (no GitHub issue)	7.0.0 adds an old-names table, but not for next_task, target_task or tracking_task	Waits. A key rename needs an old-name reader and a major release
Three keys in .compass/config.yml configure nothing (no GitHub issue)	7.0.0 keeps reading .compass/config.yml until 8.0.0	Waits for 8.0.0, which removes the reader
Governance merge versus replace (#105) and project guardrails in this repository (#100)	Copied 5.x governance is read until 8.0.0	Wait for the maintainer's decision, as at 5.6.0
scripts/multiagent.sh reads two fixed paths for an issue's documents (no GitHub issue)	The delivery-approach record moved into the documents folder	Waits. The script now names docs/compass. Not yet checked whether that closes it

The other backlog issues do not touch what 7.0.0 changes. This check used their titles and first lines only.

Two issues of the delivery record moved to the 7.1.0 milestone on purpose. Both touch the approval paths that 7.0.0 changed:

• ayeo-io/compass-delivery#206 [Fail compass check when an issue waiver's approval is withdrawn]
• ayeo-io/compass-delivery#207 [Record waiver approvals through a typed command]

ayeo-io/compass-delivery#247 also waits: a broader word reader for the approval guard. #663 did not ship it, because two reviews found inputs that get past it. ci/README.md stays in British English until 7.1.0 (#669).

Check the download

compass-7.0.0.tar.gz, SHA-256 5d1feebf35357d1514447a722d2280dea3b8484d56d6aca6ea530a5453fe8442. Built from the commit ffb2013674ea8ab9590db677454e5312e231ddc1, which v7.0.0 points to.