feat(packs): compound, ground, and enforce domain knowledge via Compound Packs

.compound-engineering/config.example.yaml

@@ -172,3 +172,22 @@
 # sweep_ack_cap: 25                                 # max acks per source per run before the circuit breaker
 # sweep_lease_ttl_minutes: 60                       # single-writer lease staleness threshold
 # sweep_shared_branch: false                        # true: push-gated lease for shared-docs-branch topology
+
+# --- Compound Packs ---
+
+# Prescriptive domain knowledge folders that planning reads and cites.
+# Declared, never scanned: an entry names a source (repo-relative path,
+# ~/absolute path, or git URL) and what to install from it. Lists from this
+# file and config.local.yaml concatenate -- local adds packs, never replaces
+# the team's. Git sources require ref (tag or sha reproduce exactly; a branch
+# freezes at its cached resolution and can drift across machines). path: and
+# pasted GitHub /tree/<ref>/<sub> URLs scope a source to a subfolder.
+# pack: picks one id or a list; omit it to install everything the source
+# publishes. id: renames a single-pack entry.
+
+# packs:
+#   - source: compound-packs/local-rules                       # repo-relative, read live
+#   - source: ~/compound-packs/kk-style                        # machine-local, read live
+#   - source: https://github.com/org/rails-ce-pack    # git, cached at ref
+#     ref: v1.2.0
+#     pack: [rails, inertia]

CONCEPTS.md

@@ -63,6 +63,9 @@ A documented solution to a past problem — a bug fix, a convention, or a workfl
 ### Pattern doc
 Guidance generalized from several Learnings into a broader rule. Higher-leverage than any single incident-level Learning, and higher-risk when stale, because future work treats it as broadly applicable.
 
+### Compound Pack
+A folder of prescriptive domain knowledge files that planning- and review-stage Skills consume: planning pulls matching rules into a plan as pack-attributed constraints, and review flags work that contradicts them. A repo opts in by declaring each pack in its CE config `packs:` list — a repo-relative path, a home-directory path, or a ref-pinned git URL, installing one, several, or all packs the source publishes. Shaped like Learnings (frontmatter with `applies_when`) but prescriptive rather than retrospective: a pack says what work in its domain must honor, a Learning records what a past problem taught. Not a Skill: a pack is never invoked and its text is quoted as evidence inside other Skills' steps, never executed as instructions. Optional; CE is complete with zero packs.
+
 ### Knowledge track
 One of the two classifications a Learning carries, set by its problem type: the knowledge track holds guidance — conventions, workflow patterns, practices, decisions — while the bug track holds diagnosed defects. The track decides which metadata a Learning must carry and which maintenance checks apply to it; procedure-shaped checks, such as comparing a Learning against the Guidance layer, key on the knowledge track.
 

README.md

@@ -141,6 +141,8 @@ Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainst
 <sub>Replayed from a real pair of sessions 18 days apart, with names and paths anonymized and the six-minute run compressed to about 30 seconds. Nothing shown is behavior the skills don't have — see <a href="assets/demo/README.md">assets/demo</a> for the source and the substitutions.</sub>
 
 > Artifact folders like `docs/solutions/` and `docs/plans/` are the **defaults**. A project whose `docs/` is tracked content can relocate every CE artifact folder under one repo-relative root via the `docs_root` setting -- see [configuration](skills/guides/configuration.md#artifact-root).
+>
+> Want the same knowledge compounding across every repo in your org -- team conventions, security policies, a stack's hard-won rules -- instead of being relearned in each one? Declare it as **Compound Packs**: folders of prescriptive rules (local, or ref-pinned git repos) that planning grounds in and review enforces, every use cited back to the rule file (experimental) -- see [Compound Packs](skills/guides/packs.md).
 
 ## Try it
 
@@ -434,6 +436,7 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, and [`docs/development.md`](
 |---|---|
 | [Skill catalog](skills/guides/README.md) | A page per skill, and how they chain together |
 | [Configuration](skills/guides/configuration.md) | `.compound-engineering/config.yaml` options |
+| [Compound Packs](skills/guides/packs.md) | Declaring, authoring, and publishing prescriptive rule packs |
 | [Installing](#install) · [Upgrading](docs/install/upgrading.md) | Per-host install and refresh |
 | [Contributing](CONTRIBUTING.md) · [Development](docs/development.md) | Working on the plugin itself |
 | [Security](SECURITY.md) · [Privacy](PRIVACY.md) | Reporting and data handling |

docs/dogfood-reports/2026-08-26-feat-ce-packs-v0-dogfood.md

@@ -0,0 +1,86 @@
+# Dogfood Report — feat/ce-packs-v0
+
+> Diff-scoped QA of `feat/ce-packs-v0` vs `origin/main`. Generated by `/ce-dogfood` on 2026-08-26.
+> **Adaptation note:** this branch ships no web surface — its users drive a terminal and an agent. The matrix is executed through the product's real UX (the resolver CLI, the shipped skill prose exercised by fresh agents, `check-health`, and the docs walkthrough in a clean repo) instead of `agent-browser`.
+
+## Diff Summary
+
+- Compound Packs: a `packs:` config list (repo/`~` paths, ref-pinned git URLs, tree-URL sugar, `path:`/`pack:`/`id:` fields) resolved by a new bundled `packs-resolve.py` (6 byte-identical copies, parity-gated)
+- Planning grounds in matching pack rules (`ce-brainstorm` scout, `ce-plan` research) with `(pack: <id>, <path within the pack>)` citations
+- Review enforces them (`ce-code-review` learnings pass, `ce-doc-review` `{pack_constraints}` slot)
+- Capture recognizes them (`ce-compound` `pack_overlap` + writable-pack destination routing)
+- `ce-setup` health check gains a Compound Packs section with a branch-drift note
+- Docs: `skills/guides/packs.md` guide, configuration reference, glossary, plan artifact
+
+## Personas
+
+Source: `STRATEGY.md` § Users.
+
+- **Agent-first multi-harness developer** — wants session knowledge landing in the repo, one workflow traveling across hosts/models; cares that packs work identically everywhere and never demand ceremony
+- **Pack author / org knowledge steward** (inferred specialization) — writes the rules once, needs authoring to be a 2-minute job with loud, specific errors when config is wrong
+
+## Flows Tested
+
+```mermaid
+flowchart TD
+    A[Author writes rule file] --> B[Declares packs: entry]
+    B --> C[packs-resolve.py]
+    C -->|valid| D[roots JSON]
+    C -->|ref on path / bad id| E[Loud per-entry error, others resolve]
+    C -->|no frontmatter .md| F[Skipped pack files warning]
+    C -->|git URL + tag| G[Cached clone -> roots]
+    D --> H[/ce-setup check-health lists packs/]
+```
+
+```mermaid
+flowchart TD
+    I[Developer runs ce-plan] --> J[Research: search-root list]
+    J --> K{applies_when matches work?}
+    K -->|yes| L[Constraint in plan + citation]
+    K -->|no| M[Plan silent about packs]
+    L --> N[Diff violates rule]
+    N --> O[ce-code-review flags with citation]
+    L --> P[Later /ce-compound capture of same insight]
+    P --> Q[pack_overlap: covered -> not re-captured]
+```
+
+## Test Matrix & Results
+
+| # | Flow | Journey / Scenario | Status | Issue | Fix | Commit |
+|---|------|--------------------|--------|-------|-----|--------|
+| 1 | Author | Guide's 2-minute walkthrough verbatim in a clean repo -> resolver returns the pack | Pass | - | - | - |
+| 2 | Author | In-pack `resources/` invisible to discovery, no warnings | Pass | - | - | - |
+| 3 | Author | git-sourced pack (file:// + tag + `pack:` selection) resolves in clean repo | Pass | - | - | - |
+| 4 | Author | Frontmatter-less `.md` in pack -> one skip warning naming the file | Fixed | Resolver emitted no warning; skip-report lived only in researcher prose, so authors validating with check-health never saw it | Resolver warns per skipped file; check-health surfaces it | 1a18a67d |
+| 5 | Author | `ref:` on a path source -> loud error naming entry; sibling entry still resolves | Pass | - | - | - |
+| 6 | Operator | `check-health` in clean repo lists both packs (git one with ref), surfaces skip warning + config error as issue | Pass | - | - | - |
+| 7 | Planning | Fresh researcher matches rule via `applies_when`, emits exact citation | Pass | - | - | - |
+| 8 | Planning | Brainstorm scout: git-cached pack quoted with `pack:security` + file:line, gist line present, non-matching pack silent, resolver warnings surfaced once | Pass | - | - | - |
+| 9 | Review | Violating diff (`/api/orders` for a page's own data) flagged with exact citation | Pass | - | - | - |
+| 10 | Compound | `pack_overlap: covered` verdict + non-interactive `Documentation skipped — covered by pack rule (…)` signal verbatim | Pass | - | - | - |
+| 11 | Docs | Guide's internal links and anchors resolve | Pass | - | - | - |
+| 12 | Suite | Full automated suite green on the branch | Pass | - | 3,690 pass / 0 fail | 26ad850f |
+
+## What Was Fixed
+
+### Frontmatter-less pack files skipped silently at resolve time — `1a18a67d`
+- **Symptom:** `notes.md` without frontmatter inside a pack produced no warning from the resolver or `check-health`; the skip-report existed only in researcher prose, so a pack author validating their setup never learned the file was inert (R8: "reported once per run").
+- **Root cause:** enumeration counted valid files but never reported invalid ones; the reporting duty lived one layer too high.
+- **Fix:** `packs-resolve.py` (all six copies) warns per skipped top-level `.md` in each installed pack (`skipped pack file \`<id>/<name>\` (missing title/applies_when frontmatter)`); `check-health` surfaces it for free.
+- **Regression test:** `tests/skills/ce-packs-resolver.test.ts` — "a frontmatter-less .md inside an installed pack warns at resolve time" (red before, green after).
+
+## Paper Cuts (by persona)
+
+- **Pack author** — resolver silent on frontmatter-less files — sharp — fixed `1a18a67d` (now warns; check-health surfaces it)
+- **Pack author** — "every markdown file" ambiguous about subdirectories/assets; a stray `.md` under `resources/` could read as a rule — sharp — fixed (prose pinned to top-level; assets never listed as skipped)
+- **Agent-first developer** — scout `file:line` pointers unpinned for git-cache packs (opaque paths) — mild — fixed (pack-relative pinned)
+- **Agent-first developer** — `pack_overlap` rule id undefined — mild — fixed (filename stem pinned)
+- **Agent-first developer** — ce-plan researcher's Invocation Contract names only planning invocations; the generic steps carry review-style calls fine, and production review uses ce-code-review's own copy — mild — deferred (note only)
+
+## Console Errors
+
+N/A — no browser surface; resolver stderr/warnings tracked per scenario instead.
+
+## Verdict
+
+**Ready.** 12/12 scenarios closed (11 Pass, 1 Fixed with regression test, `1a18a67d`); all four agent-driven legs passed in a clean repo built verbatim from the guide; 4 of 5 paper cuts fixed in-run. Automated suite on the final tree: 3,691 pass / 0 fail; `release:validate` and `plugin:validate` green; PR #1549 CI green (`test`, `windows-native`, `pr-title`, security review).