feat(packs): load shared writing rules through Compound Packs

[kieranklaassen]

Summary

A writing home can now declare Compound Packs: folders of prescriptive writing rules that a publication, a team, or one writer with several homes shares, and that every step loads at the moment it matters. cw-draft grounds in the rules that match, cw-dev-edit/cw-line-edit revise against them, cw-voice-check/cw-final-pass/cw-panel flag a draft that contradicts one, and cw-save recognizes a lesson a pack already prescribes instead of writing a duplicate into VOICE.md or STYLE.md. Every influence is cited (pack: <id>, <file>). Before this, standards shared beyond one home could only be copied by hand or baked into a skill.

The design mirrors compound-engineering-plugin's packs (#1549, hardened in #1661): the same rule shape (title + situational applies_when), the same layout rule (top-level .md files are rules, README.md is the description, subfolders are storage), the same entry fields, the same guards, and the same evidence-not-instructions posture. One pack repository can therefore serve both plugins; a cross-compatibility run confirmed identical ids, dirs, warnings, and citations from a shared repo under both resolvers. With no packs: key, every skill behaves exactly as before.

Plan: docs/plans/2026-09-10-001-feat-compound-packs-plan.md. Guide: references/packs.md.

Design decisions

Decision	Why
Config in <home>/.compound-writing/config.yaml + config.local.yaml, anchored to the writing home rather than a git root	A writing home is portable and often not a repository. Sharing .compound-engineering/ was rejected: engineering rules firing during a line edit are noise, and a repo holding both plugins would have to accept both.
Nobody hand-writes the config	cw-packs creates config.yaml from its template when it declares or scaffolds a pack; cw-setup-project --with-packs creates it with a new home (opt-in, so the default four-surface scaffold is unchanged); .compound-writing/config.example.yaml at the plugin root is the same template, byte-identical by test, as CE ships .compound-engineering/config.example.yaml. The guide carries a complete copy-pasteable example. CE ships no example packs (its dogfood packs live in a private repo), so none are added here.
The nearest .compound-writing/ governs; a checkout is only the fallback	Walk up from --home (a draft or folder) or the working directory to the nearest config; when none exists, the innermost checkout (first .git) is the home, so a plain repo reads its root config. A manuscript repository nested inside a home inherits the home's packs and can override them with its own config. The walk never crosses a filesystem boundary or a GIT_CEILING_DIRECTORIES entry, does not consult git configuration, and skips directories the user does not own. CE reads only a repo root; this is the writing-home analogue.
One resolver copy at skills/cw-packs/scripts/packs-resolve.py	This repo's skills already reference siblings (../../references/, <plugin-root>/skills/cw-setup-project/scripts/...), so CE's byte-identical copies would add a parity rule without a packaging need.
Packs enter through the context contract as layer 5, below the home's own VOICE.md/STYLE.md and above examples/	The contract is the seam every voice-sensitive skill already reads; each step adds one paragraph on what it does with a match rather than restating the mechanism. The home's own guides win on a direct conflict and the conflict is named, never merged.
cw-save is the capture hook	It resolves packs first, reports a covered lesson with its citation, and offers a writable (path-sourced) pack for a standing rule bigger than one home, scaffolding one through cw-packs when none exists. Every pack write is shown in full (path, frontmatter, body) and waits for approval, even on an explicit request; with two writable packs it asks; a non-interactive run never writes into a pack. Git-sourced packs are read-only caches.
cw-compound command alias; cr:compound not created	The request proposed cr:compound as a CE-compatible entry point. ARCHITECTURE.md requires cw-<name> for every user-invokable skill and command, and a colon is not a valid skill or command name. commands/cw-compound.md routes to cw-save and adds no behavior. It is a Claude Code command: the Codex manifest packages skills/ only, so Codex users invoke cw-save; the repo has no Cursor manifest. tests/test_packaging.py rejects the colon form.
The public allowlist is now a file	README and ARCHITECTURE have said since 2.2.0 that public releases come from "an explicit generic-skill allowlist", but no such file existed in this repo or the private source snapshot. release/allowlist.json now names every skill and command allowed in the public package (cw-packs and cw-compound included) and tests/test_packaging.py holds skills/ and commands/ to it in both directions.
Writing-home scaffold unchanged	create_project.py and defaults/project-template/ still create exactly VOICE.md, STYLE.md, examples/, drafts/; the packs config is opt-in.

cw-packs is the one new skill: declare a source, scaffold <home>/compound-packs/<id>/ from a template after a preview that names the resolved home and config path, and render the resolver's JSON as a health report.

Tester round

Four independent test matrices (resolution, CE cross-compatibility, save/alias, writing flow; 276 cases) found no blockers. Fixed here, each with a regression test:

• Two-hop symlink escape (security, medium): a directory link into a sibling folder inside the source hid a second link beneath it that left the source. Escape checks now follow in-boundary directory links, each real directory once.
• A FIFO named *.md blocked the resolver forever; only regular files are opened now.
• An unreadable config.yaml aborted the run; it is now that layer's error and config.local.yaml still loads.
• id: was unvalidated (empty, ../../etc, -rf all published); ids must be one plain path segment.
• A deleted working directory produced a resolver-failure error instead of CE's no-home warning.
• A README folder whose only rules sat one level down published under the subfolder's name with no signal; it still publishes (CE-identical) and now says so.
• An entry indented under another top-level key was dropped silently; it is a loud error, and cw-packs verifies by the presence of the pack <id> line.
• Nested-checkout semantics decided and documented (see the design table).
• cw-save: explicit requests skipped the pack preview; two writable packs had no selection rule; "non-interactive" was undefined.
• Cheap nits: packs: [] append kept valid, YAML-unsafe titles quoted, short rule file names, voice-check double error report, handoffs no longer list unmatched rules, the guide's example fires while drafting, full-sha wording, and the runtime claim above.

The ~20 CE resolver cases the suite lacked are ported into tests/test_packs_resolve.py; all pass unchanged. Deferrals with one-line reasons are in docs/residual-review-findings/cursor-compound-packs-7c77.md.

Validation

• CI (.github/workflows/ci.yml, new): on pull requests and pushes to main, runs python3 -m unittest discover -s tests -v and claude plugin validate --strict against the marketplace catalog and the plugin manifest, validator pinned to 2.1.220 (CE's pin) and cached. First run on this PR: green, 97 tests, both validations passed.
• python3 -m unittest discover -s tests: 97 pass (70 resolver, 11 packaging incl. allowlist and config-example pins, 4 create_project.py, 12 prose-contract). Resolver tests drive the script through a subprocess against temp homes and local tagged git repos: home discovery (config, .git dir, worktree .git file, nested config, nested checkout, ceiling directory, --home on a draft), path and git sources, every documented error shape, symlink containment including the two-hop case, cache behavior, --declared-only, and the ported CE cases. Packaging tests check every skill and command for cw- names with only name/description frontmatter, the allowlist, the config example, and the four-surface template. Prose-contract tests pin the cw-save/cw-packs/contract sentences the testers found missing.
• Resolver from this repo root prints {"roots": [], "warnings": [], "errors": [], "entries": 0, "home": "<repo>"}, so a checkout with no live config is silent.

Security disclosure

Adds a script that clones git repositories named in a writing home's config and walks user-authored pack directories, feeding their frontmatter to an agent. Mitigations carried over from CE and pinned by tests: --end-of-options plus a leading-dash guard on git arguments, owner-and-symlink-checked private cache under /tmp/compound-writing-<uid>/cw-packs, realpath containment for home-relative sources and path: subfolders, refusal to publish a pack whose tree links outside its source (now including links reached through an in-boundary directory link), non-interactive bounded git, JSON-always output. New in this port and reviewed: home discovery skips unowned directories, stops at filesystem and ceiling boundaries, and validates id:. Pack text is treated as evidence at every consumer; cw-panel hands rules to reviewers in a quoted block labeled as evidence, not instructions.

New concepts

Compound Pack. A pack is knowledge the agent must honor while working, as opposed to a skill, which is something the agent can do. It is a folder of Markdown rules; each rule's applies_when names the situations in which it fires ("judging whether a piece is ready to publish"), and the consuming step matches those conditions semantically against its own work, reading a rule's body only on a match. Why here rather than a skill: knowledge that must be invoked is knowledge that gets skipped, and skill text is obeyed while pack text is quoted and cited, which is the injection boundary this design depends on. In this PR, a house rule earn-the-ending.md makes cw-final-pass refuse Ready on a recap ending and cite the file, and makes cw-save decline to write "never end on a recap" into STYLE.md because the pack already says it. Do not use a pack for a workflow a writer runs on purpose (a cutting pass, a panel); those stay skills.

---