Compass 8.0.4

Compass 8.0.4 is a patch release. The plugin manifest now names Compass's privacy policy, terms of service and support pages, which the Claude plugin directory shows on the listing. No check, refusal or exit code changes.

Upgrade

Run claude plugin update compass. No archive migration is needed.

Changes

• The directory listing links privacy, terms and support. plugin.json names https://ayeo.io/privacy/, https://ayeo.io/terms/ and https://ayeo.io/support/ (#718).
• compass policy migrate recognizes 8.0.3. Governance copied from the 8.0.3 release is matched to that release (#716).
• The test suite passes on GitHub's current Ubuntu runner image. Five test helpers that build a PATH without jq or python3 failed when /usr/bin and /bin held the same broken link (#716).

Queued against this release

• Show git's error when a test's clone of the repository fails (ayeo-io/compass-delivery#309).
• Plugin copy tests fail in a clone that has a local plugin branch (ayeo-io/compass-delivery#310).
• A settings test sometimes gets no-red-on-record instead of a read error (ayeo-io/compass-delivery#311).
• Scope the write grants of six commands. The directory reports it as information only.
• Let the approval guard cover the approval program file.
• Move the remaining inline Python out of shipped scripts.
• Refuse a Codex tool call when python3 is missing.

Compass 8.0.3

Compass 8.0.3 is a patch release. It rewrites seven lines in the pre-tool and post-tool hooks so the Claude plugin directory can read every command they run. No check, refusal or exit code changes, and nothing is removed.

Upgrade

Run claude plugin update compass. No archive migration is needed.

Fixes

• The plugin directory can read the hooks. The directory blocked the 8.0.1 and 8.0.2 copies with "Unpinned npx launcher" on hooks/pre-tool.sh and hooks/post-tool.sh, although neither runs a package launcher. Its validator cannot read a quote nested inside a double-quoted string, such as "${ABS_TARGET#"$REAL_ROOT"/}" or "${found//\\\"/\"}". Those lines now keep every quote outside double-quoted strings. A new test fails if either hook nests a quote again (#714).
• Without jq, the pre-tool hook decodes \/ on macOS. The reader the hook uses when jq is missing left \/ undecoded under bash 3.2, the macOS /bin/bash, so a path written that way did not match jq's reading. It now decodes every string as jq does under bash 3.2, 4.4, 5.1 and 5.2 (#714).
• compass policy migrate recognizes 8.0.2. Governance copied from the 8.0.2 release is matched to that release (#711).

Queued against this release

• Scope the write grants of six commands. /compass:define, /compass:go, /compass:implement, /compass:quick-fix, /compass:resume and /compass:ship pre-approve Write (and all but /compass:resume also Edit) with no path. It waits: five of them write code and tests anywhere in a project, so their scope needs a decision of its own. The directory reports it as information only.
• Let the approval guard cover the approval program file. It waits: the guard change needs its own review.
• Move the remaining inline Python out of shipped scripts. It waits: the scripts it names, bin/compass-statusline and scripts/multiagent.sh, are not hooks.
• Refuse a Codex tool call when python3 is missing. It waits: the fix needs a hook command that does not start with python3.

Compass 8.0.2

Compass 8.0.2 is a patch release. It rewrites how the pre-tool and post-tool hooks write their commands, so the Claude plugin directory can read every command they run. No check, refusal or exit code changes, and nothing is removed.

Upgrade

Run claude plugin update compass. No archive migration is needed.

Fixes

• The plugin directory can read the hooks. The pre-tool and post-tool hooks ran 33 commands inside double-quoted strings, such as TOOL="$(... | jq ...)". The directory validator cannot read a command written that way, so it refused the 8.0.1 copy. Each of those commands now assigns its output first, and nested commands are split into steps. A new test fails if either hook runs a command inside a double-quoted string again (#709).
• compass policy migrate recognizes 8.0.1. Governance copied from the 8.0.1 release is matched to that release (#707).

Checked in this release

• An 8.0.0 install updates to 8.0.1 from the plugin branch, and the updated install holds the 434-file copy, not the whole repository.

Queued against this release

• Scope the write grants of six commands. /compass:define, /compass:go, /compass:implement, /compass:quick-fix, /compass:resume and /compass:ship pre-approve Write (and all but /compass:resume also Edit) with no path. It waits: five of them write code and tests anywhere in a project, so their scope needs a decision of its own. The directory reports it as information only.
• Let the approval guard cover the approval program file. It waits: the guard change needs its own review.
• Move the remaining inline Python out of shipped scripts. It waits: the scripts it names, bin/compass-statusline and scripts/multiagent.sh, are not hooks.
• Refuse a Codex tool call when python3 is missing. It waits: the fix needs a hook command that does not start with python3.

Compass 8.0.1

Compass 8.0.1 is a patch release. It changes how Compass is packaged and narrows what its commands pre-approve, so the Claude plugin directory can read and review it. Nothing is removed, and no reader changes: every old form 8.0.0 reads is still read until 9.0.0.

Upgrade

Run claude plugin update compass. No archive migration is needed.

What's new

• A smaller install. An install is now a copy of the 434 files the plugin reads, published to the plugin branch, not the whole repository with its tests and developer documents. The marketplace entry fetches that branch, so 8.0.0 users get 8.0.1 through the usual update (#698).
• compass policy migrate recognises 8.0.0. Governance copied from the 8.0.0 release is matched to that release (#696).

Changed behavior

• Commands pre-approve only compass. Each command's allowed-tools now names Bash(compass *) in place of every shell command. Test runs go through compass tdd-red and compass tdd-green, so they stay pre-approved. Three steps now ask for permission once: the status-line setup in /compass:init, scripts/integrate.sh in /compass:ship and scripts/multiagent.sh in /compass:breakdown (#699).
• Commands that write only issue state write only there. Twelve commands (assess, breakdown, consult, design, flow, init, intent, plan, position, refine, status and verify) pre-approve writes to .compass/ and docs/ only, and init also to compass.yml. A write elsewhere asks first (#699).
• gh and the Codex hooks get only the variables they need. The GitHub label and page sync passes gh its own settings, the GitHub token, locale, certificates and proxies, and no other variable. The Codex adapter's shared hooks get the same kind of list (#699).
• A broken install refuses. The pre-tool hook now loads its checks from parts in hooks/lib/. If a part is missing from the install or cannot be read, the hook refuses every call with reader-failed and names the part, in any project, rather than run with a check left out (#699, #701).

Fixes

• The hooks, including the approval prompt hook, run each Python check from its own file in hooks/py/, not from text inside the script. A file in your project can no longer shadow a module a check imports, because the project folder is no longer on the check's import path (#699, #700).

Queued against this release

• A check that an 8.0.0 install updates to 8.0.1 from the plugin branch (FU-B3). It needs the published 8.0.1 copy, so it runs after this release.
• Let the approval guard cover the approval program file. It waits: the approval program moved to hooks/py/ in this release, and the guard change needs its own review.
• Move the remaining inline Python out of shipped scripts. It waits: the scripts it names, bin/compass-statusline and scripts/multiagent.sh, are not hooks, and this release moves only the hooks' inline programs.
• Refuse a Codex tool call when python3 is missing. It waits: without python3 the Codex hook fails as it did in 8.0.0, and the fix needs a hook command that does not start with python3.

Compass 8.0.0

Compass 8.0.0 is a major release because of one change: delegation. A delegation now works across git worktrees and takes optional flags, and four forms that 7.0.0 accepted are refused. 8.0.0 removes no reader: old words, old approach names, copied 5.x governance, the generated governance views, .compass/config.yml and migrated LEGACY waivers are read until 9.0.0. docs/upgrade-8-0-0.md covers the change.

Upgrade

1. Update every checkout and every installed plugin together.
2. Type /compass:delegate again for each delegation you rely on, in the flag form below. A delegation file that 7.0.0 wrote in a linked worktree's own folder no longer gives approval.
3. If an agent prompt or script records delegated approvals, add --issue <slug>, and run the command as a plain compass ... in the agent's Bash tool.

No archive migration is needed.

What breaks

• The positional form of /compass:delegate is refused, and so is --labels. The message shows the flag form: /compass:delegate --agent compass:architect --until 08:00 --on my-issue (#691).
• A delegated approval needs --issue <slug>. The pre-tool hook writes a call ticket naming the calling session and agent, and the CLI takes the session from it. A command inside a script, an echo or a variable gets no ticket and is refused (#691).
• One delegation store. Compass reads .compass/delegations/ in the main checkout; a file in a linked worktree's own folder is refused, and the refusal names it (#691).

What's new

• Delegation without ceremony. /compass:delegate [--agent] [--until] [--on] [--for] [--max], each optional. With none, a delegation covers this session's agents on every issue until /compass:revoke, with no time limit and no cap. --for g5 still needs the code you type back. Each delegation with no end time is listed at session start (#691).
• Approve and reject across worktrees. /compass:approve <n> and /compass:reject <n> <reason> find a request in any worktree's current issue; --issue <slug> reaches any issue (#691, #679).
• Review only what you were shown. /compass:approve with nothing pending marks reviewed only the approvals your last summary showed (#691).
• compass in your own terminal. A plugin install now has a launcher in the plugin's data folder. The commands the CLI prints for you to run in your terminal name it, with the folder to add to your PATH (#693).
• Execution profiles. compass profile lint, add and show (#677).

Fixes

• The pre-tool hook treats perl -pi, ruby -pi and interpreter scripts that write a path held in a variable as writes to production code (#692).
• The approval guard joins a protected folder name split over two lines with a backslash, and decides long or unusual commands within the hook's time limit (#690).
• compass record restore refuses a redacted generation file instead of leaving the issue broken (#684).
• compass issue migrate keeps a one-unit distribution map (#683).
• The README, the docs home page and the quickstart state what each guarantee covers and where it stops, and the text an adopter reads is plain English (#694).
• compass quick-fix start writes its start record before the pointer, so a failed start can run again (#686).
• Assess reuses the issue the pointer names; the docs show the shell install; two templates are corrected (#681).
• The architect reads the intent when acceptance criteria are missing (#682).
• Six commands list Bash among their tools, and the manifest schema defines intent_source (#680).
• Three code scanning alerts in the template readers are fixed (#678).

Known limits

• A resumed session (claude --resume) gets no list of delegations with no end time (ayeo-io/compass-delivery#299).
• Some texts still name plain compass for a terminal command, such as the issue page, and a few install layouts fall back to it: ayeo-io/compass-delivery#302.

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...

Compass 6.1.0

Compass 6.1.0 is an interim release on the way to 7.0.0. It makes the Stop hook fast on projects with many issues, and it carries the 7.0.0 changes that have landed so far. Some of those change behaviour, so read docs/upgrade-7-0-0.md before you upgrade a project.

Fixed

• The Stop hook skips closed issues and checks the rest in one Python process. On this repository's 515 issues one run took 513 seconds before and takes under a second now, with 40 warnings instead of 264. One issue folder it cannot read no longer hides the warnings for the others.
• Two Compass commands that save the same issue at once no longer lose either change, and a reader never sees a half-written manifest.
• Two sessions approving at once can no longer hang on each other's review locks.
• A generation commit no longer deletes files it did not write.
• compass migrate no longer stops with a NameError when it checks which files it can restore.
• Records copied to the delivery record now match their source: redaction removes secret values only.
• The compass next latency check no longer fails on runner noise, and still fails a real slowdown.

Changed behaviour

• Stage commands write the status of each registered document, and compass ship-commit refuses a document that is not accepted (the blocking check artifacts-approved). compass issue migrate settles the status of done issues. See docs/upgrade-7-0-0.md.
• Guardrail 5 asks for a human sign-off only on work labelled auth, payments, personal-data or migrations, not on every risk: critical issue.
• Role is no longer part of the assessment.
• Compass picks each stage's model and effort from the issue's assessment.
• Regular issues owe a short intent with four sections, and every issue that ships records a release line, given with --release-note.
• A document kind can carry a word limit per depth, and the full approach keeps one low-level design per work unit.
• An owner-approved waiver can lower a stage that a label floor raised, without touching its gates or guardrails.
• The pre-tool hook refuses more Bash writes to production code that substitutions, line continuations, quotes or .. paths used to hide, and no longer refuses a write to a scratch file named through a variable the same command sets.
• The approval guard refuses more ways an agent could forge or replay a guardrail 5 approval.
• Lint accepts LEGACY waivers, with a warning, until 8.0.0.
• The CLI and the docs use only the current vocabulary.

How to upgrade

1. Copy .compass/work and docs/compass to a folder outside the project.
2. Run compass issue migrate for a dry run, then compass issue migrate --apply --i-have-a-copy.
3. Do not run a 6.0.x CLI on the migrated tree.

Verify the download

compass-6.1.0.tar.gz, SHA-256 cf6869269091e5278d68968fe19fd91b9755b888b822dacfbfca3e6f21e17a1d.

Compass 6.0.1

Compass 6.0.1 is a patch release. It fixes compass issue migrate, which left some paths in a migrated manifest pointing at files that had moved, and it makes compass flow faster on a large archive. It removes and renames nothing.

Fixed

• compass issue migrate now repoints every path in a manifest when it moves an issue's documents to the 6.0 layout. In 6.0.0 it missed some fields, including the evidence path on a stopped subtask. A project with multi-agent issues then saw compass check fail multiagent-run-recorded on issues whose work was fine. On this repository's archive, 34 of 490 issues failed this way.
• compass flow reads issue manifests through a cache, so a second run on a large archive is quicker. On this repository's archive, it takes 0.18 s instead of 2.29 s once the cache is filled.

Changed behaviour

• compass flow keeps parsed manifests under .compass/cache/parsed_yaml/. The folder carries its own .gitignore, so git ignores it. Deleting the folder is safe: the next run parses the manifests again. An entry is used only when it matches the file on disk exactly, and no command that changes a manifest reads the cache.

How to upgrade

If you ran compass issue migrate --apply on 6.0.0, run it again on 6.0.1. Run compass issue migrate first to see what it would change. The second run repairs the paths 6.0.0 missed and leaves every other field alone.

Queued against this release

None that this release changes. The four backlog issues that carry a recommendation are the same as at 6.0.0, and none touches compass issue migrate or compass flow.

Verify the download

compass-6.0.1.tar.gz, SHA-256 3723e25f564ed2a6a982a06f94d98e41a616046ee6671bd1050e28458e19e16f.

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 approve...

Compass 5.6.0

Compass 5.6.0 is a minor release. It adds two commands, tightens several checks, fixes the defects below and pins CI's dependencies. Nothing is removed.

New

• compass ship-commit -F <file> reads the commit message from a file, so a long message never needs a shell fallback around ship-commit's HEAD check (#120).
• make test-clean runs the suite in a fresh clone of HEAD, as CI sees it, so a test that reads gitignored local state fails before the push (#122).

Changed behaviour

• compass changed-file add and compass evidence add refuse a scenario id the issue does not define, or several ids in one value. Define a scenario with compass scenario add before tracing to it (#119).
• compass check --verbose labels a check with nothing to inspect NOTHING TO CHECK, not PASS, and a failing verdict counts those checks apart: FAIL - 1 of 13 check(s) failed, 9 had nothing to check. The exit code and the JSON are unchanged (#110).
• Printed output says "delivery approach" and "stages" where it said "route", "candidate shape" and "phases". retro prints Delivery approaches:. Machine keys are unchanged (#108).
• compass approach evaluate --write and compass check refuse an assessment key the manifest schema does not allow (#399).
• scripts/multiagent.sh refuses a distribution map whose subtask table and stated final count disagree (#101).

Fixed

• compass tdd-red recorded no import red when FORCE_COLOR was set, and the eval harness and judge read no results (#403).
• A friction note's phase accepts the current stage names (#156).
• compass issue lint no longer demands an assessment from an issue abandoned before it was assessed.
• Fired policy rules print through one formatter on every screen (#109).
• The pytest-bdd adapter tests pass where pytest-bdd is installed, and CI runs them (#407, #114).
• Test reliability: seed test runs no longer write caches into the checkout (#261), the full-archive citation check passes before generated files are built (#153), and the entry-point guard measures logic rather than line count (#102).
• Docs site: inline code in tables stays on one line.

Supply chain

Every action in .github/workflows/ and in the copyable ci/ workflows is pinned by commit SHA. CI installs its test tools from .github/requirements/ at exact versions, and the cucumber-js adapter installs with npm ci (#99, in part).

Queued against this release

None that this release changes. Three queued issues carry a recommendation and wait for a maintainer decision: governance merge versus replace (#105), project guardrails in this repository (#100) and approvals bound to what was approved (#118).

Verify the download

compass-5.6.0.tar.gz, SHA-256 56059226a4a1bbceb3b7ca78e1eec1272ad491508d35408887fd160f9628284c.