canon-ai 3.7.0 → 3.9.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@
 
 ## [Unreleased]
 
+## [3.9.0] — 2026-10-16
+
+### Added
+
+- **`.canon/config.json` sets which docs QA keeps fresh.** Under `docs_freshness`, map source-path globs to the docs QA must check when a task touches matching files (`paths`), list docs QA should report under "Docs drift" in `done.md` instead of editing (`flag_only`), or replace the default protected set (`protected`). The file is yours: `canon init` doesn't create it and `canon upgrade` never changes it. A malformed file stops every `canon run` form before it changes any state, and `canon doctor` reports the file's status. See "Configuring docs freshness" in the canon-ai README.
+
+### Changed
+
+- **QA's doc list and the QA commit allowlist now come from the same set.** QA's prompt names the protected docs plus any mapped docs whose globs match the task's changes. Previously the prompt named five docs while the allowlist admitted six.
+- **`docs/pipeline-orchestrator.md` is no longer a default protected doc.** It is a canon-managed file in your repo, and `canon upgrade` overwrites it, so QA edits there didn't last.
+
+### Fixed
+
+- **`--ship` and the QA and human-review commits no longer split file names that contain ` -> `.** Only renamed or copied entries in git status are read as an `old -> new` pair.
+- **File names with non-ASCII or special characters now match their real paths.** Git quotes such names in its status and diff output (for example `docs/😀.md`), and canon compared the quoted form. The QA-end and human-review commits could reject the file, implement's auto-commit checks could miss it, and `--ship` could overlook it as dirty. Canon now decodes the quoting first.
+
+## [3.8.0] — 2026-10-07
+
+### Changed
+
+- **`/canon-spec-review`'s factual reviewer now runs on Haiku.** The reviewer that checks a spec's paths, symbols, and signatures against the code now runs on `haiku`. Its work is lookups, so the smaller model is enough and costs less. The shape and spec-quality reviewers still use your session's model. Run `canon upgrade`, then start a new Claude Code session to pick it up.
+
 ## [3.7.0] — 2026-10-06
 
 ### Added

package/README.md

@@ -304,6 +304,45 @@ diff .canon/templates/spec.md tasks/_templates/spec.md
 
 See `.canon/README.md` for a quick reference.
 
+### Configuring docs freshness
+
+Create an adopter-owned `.canon/config.json` to tell QA which docs to keep current:
+
+```json
+{
+  "docs_freshness": {
+    "protected": ["docs/architecture.md", "docs/codebase-map.md"],
+    "paths": {
+      "api/**": ["docs/api-contract.md", "docs/environment-variables.md"],
+      "**": ["docs/ROADMAP.md", "AGENTS.md"]
+    },
+    "flag_only": ["AGENTS.md"]
+  }
+}
+```
+
+`protected` **replaces** the defaults: architecture, codebase-map, patterns,
+product-context, and decisions. Omit it to keep those defaults; use `[]` to clear
+them. Add docs through `paths`, using `"**"` to check one on every task.
+Globs support `**`, `*`, `?`, and `{a,b}`; wildcards match dotfiles and hidden
+directories too. Brace alternatives must be one level and stay within a single
+path segment; nested braces and alternatives containing slashes are unsupported.
+Keys match file paths: use a glob such as `api/**` rather than a directory-only
+key ending in a slash. QA scans mapped docs when the task's committed diff matches,
+while every mapped doc stays eligible for QA commits across later review rounds.
+
+`flag_only` removes docs from QA's edit permission. When selected by the protected
+set or a matching mapping, QA reports stale statements in a **Docs drift** section
+of the QA summary instead. An implementer may still edit a flag-only doc explicitly
+listed in the spec's Affected Files.
+
+`canon init` does not create this file and `canon upgrade` leaves it alone.
+Commit the config before starting worktree-isolated tasks: each worktree reads its
+branch's copy, so uncommitted main-checkout changes are not available there.
+Malformed config stops runs, including reroute and ship, and fails the docs-freshness
+check in `canon doctor`; unknown keys warn. Telemetry files and task-artifact paths
+cannot be configured. Without a config, the default protected set applies.
+
 ## Architecture: two layers
 
 Canon is two products: