dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-compound/references/concepts-vocabulary.md

@@ -0,0 +1,98 @@
+# CONCEPTS.md vocabulary rules
+
+`CONCEPTS.md` defines the words that mean something specific in this codebase. It is the shared base that `<root>/solutions/` and AGENTS.md can cite without redefining terms. It lives at the repo root. Terms enter in two ways, accretion and seeding (below), and the file is created the first time either path produces a qualifying entry.
+
+## The supported mutations
+
+A run may **add** an entry, **refine** one, **fold** one into the entry that already carries its meaning, **retire** one to `## Retired`, **delete** one, or **scrub** violations from one it touched. Which subset a given run may perform is stated where that run is defined, and is not re-listed anywhere else.
+
+**Update-only** names what a run withholds, never what it grants: no creation and no seeding. It does not widen the subset that run's own definition permits.
+
+## How terms enter: accretion and seeding
+
+Two paths populate the file, and they cover different gaps:
+
+- **Accretion**: a learning brings up a term whose meaning was not obvious, so it gets defined. This reliably catches *peripheral* terms, because friction is what brings them up.
+- **Seeding**: a run proactively defines the **core domain nouns** of the area it is working in. This catches the *stable-central* terms accretion never reaches: the nouns a system is built around rarely break, so they rarely appear in a learning, yet they are exactly what a reader needs to orient. Without seeding, the file fills with peripheral mechanics and never names what the project is about.
+
+### Seed goal
+
+Define the core domain nouns the area's **declared domain model** exposes that meet the qualifying bar (see "What earns a slot"). The codebase sets the count: seed every term that genuinely qualifies, none added to reach a number and none pulled from beyond the declared model to inflate one. A small domain yields a few; a large one, more. The bound is the **source** (the declared domain model of the area in scope, meaning schema, core types, primary models, and top-level domain docs, not a full-codebase trawl) and the **bar** (the same "a new engineer would need this defined" test), never a fixed quantity.
+
+### Scope of a seed
+
+- A **scoped run** (a learning capture, or a refresh narrowed to an area) seeds only that area's core nouns, and defines only terms it actually investigated against code. It does not reach for repo-wide nouns it never touched.
+- A **repo-wide bootstrap** (an explicit "create CONCEPTS.md" request) seeds the whole project's declared domain model. This is the only path that produces a coherent "what is this project" glossary; a scoped run cannot, and should not pretend to.
+
+## Be opinionated
+
+When the team uses several words for the same concept, pick the best one and drop the rest. Dropping a synonym is not a retirement: the surviving entry still carries that meaning, so the word becomes an aliases line on it (see "Per entry") and never goes to `## Retired`, which is only for a concept the project no longer has. Settled distinctions go to the Flagged ambiguities tail. The glossary is not a record of all words the team has ever used. It is the team's agreed-upon vocabulary.
+
+## The file stands on its own
+
+Each entry teaches its concept to a reader with no access to anything else: no codebase, no PR history, no architecture meetings, no Slack. This rules out:
+
+- Implementation specifics (file paths, class names, function signatures, table names, library calls)
+- Status fields, dates, owners on the entries
+- Examples or current-config values drawn from the code, such as specific thresholds, counts, or enum values that will change. State the behavior, not the number: "each skill sets its own actionable threshold" rather than "surfaces at 50, fixes at 75."
+- Links to PRs, issues, channels, or roadmap milestones
+- Version-specific claims ("currently uses X; migrating to Y")
+
+Cross-references between entries within `CONCEPTS.md` are fine — they resolve internally. General programming vocabulary (caches, queues, jobs, sessions) and everyday domain English need no redefinition either. But if an entry leans on another *project-specific* term to make sense, that term must be defined here too — an undefined project-specific sibling is itself a candidate to add.
+
+## What earns a slot — and what keeps one
+
+A term qualifies on two counts: its meaning here is precise enough that a new engineer would need it defined to follow conversations, tickets, or code, and it is a concept in its own right rather than a property of one already defined. General programming vocabulary does not belong, even when used heavily.
+
+Both counts apply at both moments — admitting a term the work surfaced, and deciding whether an existing entry keeps its heading.
+
+An entry that loses its heading still has to resolve for whoever meets the term next in an old ticket, learning, or commit. Ask which surviving entry can carry it. Usually one can, either the neighbor whose property it always was, or the concept that replaced it. **Fold** it there: the meaning moves into that entry, cross-references repoint, and the old term is named on that entry, worded so a reader can tell whether it meant this entry or was replaced by it. When nothing can carry it, the term **retires** to `## Retired` at the tail if readers will still meet it in the project's own material, and is deleted if they will not. Version history is the archive.
+
+Removing an entry acts only on positive contrary evidence, and uncertainty leaves it standing. Name where the concept went — what replaced it, what absorbed it, what took it out. Being unable to find it is not the same as it being gone: a deleted class, path, or symbol is never that evidence (an entry is meant to outlive the code that implemented it, which is what standing on its own means), and neither is the absence of corroboration.
+
+## The coherence neighborhood
+
+The neighborhood of an entry is its cluster siblings plus the terms it cross-references or that reference it. It bounds a capture-time pass: act only on evidence already in hand, never audit the whole file, and flag for `ce-compound-refresh` anything whose judgment would need investigation this run did not do.
+
+## Per entry
+
+The definition is one sentence: what the term means in this domain, and what makes it distinct from neighbors. A term with non-obvious behavioral rules (lifecycle, cancellation semantics, ownership invariants) earns a second paragraph for those rules, never for elaborating the definition itself.
+
+When dropped synonyms exist, list them as an aliases line directly under the definition: *Avoid: Booking, appointment*. Entities typically need more depth than value types; status concepts may need transition notes.
+
+## Relationships (optional)
+
+When relationships between entries carry meaning a reader needs (ownership, cardinality, lifecycle dependencies that span entries), capture them in a `## Relationships` section near the top of the file or its cluster. Skip it when entries stand on their own without structural context. Relationships are a lift for domains where structure is part of what makes terms meaningful, not a routine section.
+
+## Organization
+
+Cluster concepts by domain relationship (entities with their states, processes with their stages) so a reader sees structure without effort. A flat list works when the file is small. Reshape as the file grows.
+
+## Flagged ambiguities (tail of file)
+
+When two terms were used interchangeably and the team settled on a distinction, record the resolution as a one-line note: *"'account' had been used for both Customer and User — these are distinct."* This section is the audit trail for opinions the team has formed.
+
+## Retired (tail of file, present only when it has entries)
+
+One line per concept the project no longer has and nothing replaced: what the term meant, and what removed it. Write enough that someone meeting it in an old ticket understands what they were reading and why it is not current. Do not carry the original entry over.
+
+## One illustrative entry — the shape, not a template
+
+```
+## Booking
+
+### Reservation
+A future commitment to seat a Party at a specified date and time.
+*Avoid:* Booking, appointment
+
+A Reservation owns its Party but does not own a Table — Tables are acquired only when the Party arrives, through a Seating. Lifecycle: Booked, Seated, Completed, No-Show. Cancellation before a Seating is non-destructive; cancellation after a Seating is recorded as a No-Show.
+
+### Party
+The guests committed to a Reservation. Each Reservation has exactly one Party. Party size is the count promised at booking, not the count who arrive.
+
+### Table
+A physical seating unit with fixed capacity. Tables are shared resources — they do not belong to Reservations and are allocated only on the day-of through Seatings.
+
+### Seating
+The act of placing a Party at a Table once the Party arrives. A Reservation has at most one Seating; a Table accumulates many Seatings across its lifetime.
+```

package/skills/ce-compound/references/enhancement.md

@@ -0,0 +1,42 @@
+# Phase 3: optional enhancement
+
+### Phase 3: Optional Enhancement
+
+**WAIT for Phase 2 to complete before proceeding.**
+
+This phase is interactive-only: a non-interactive caller has no human-in-the-loop to act on reviewer findings, and downstream automations can run specialized reviewers themselves if they want that pass.
+
+<parallel_tasks>
+
+Based on problem type, optionally dispatch generic subagents seeded with local prompt assets from `references/agents/` to review the documentation. Do not dispatch standalone agents by type/name.
+
+- **performance_issue** → `references/agents/performance-oracle.md`
+- **security_issue** → `references/agents/security-sentinel.md`
+- **database_issue** → `references/agents/data-integrity-guardian.md`
+- Any code-heavy issue → preserve code simplification as a **read-only documentation review**. Inspect the solution draft's code examples and explanatory claims inline, or dispatch a generic subagent seeded with a local prompt only to return suggestions. Do **not** invoke `ce-simplify-code` from this phase and do not mutate product code unless the user explicitly asks for a separate code-simplification pass. Do not use the deleted `code-simplicity-reviewer`.
+  Example: review the solution draft's examples for speculative abstractions, redundant wrappers, dead branches, and just-in-case parameters. Apply edits only to the documentation/examples being written by `ce-compound`; leave any branch code changes untouched.
+
+</parallel_tasks>
+
+---
+
+## Applicable Specialized Local Prompts
+
+Based on problem type, these local prompt assets can enhance documentation:
+
+### Code Quality & Review
+- **Read-only code simplification review**: Checks solution examples and documentation claims for unnecessary complexity without mutating product code
+- **references/agents/pattern-recognition-specialist.md**: Identifies anti-patterns or repeating issues
+
+### Specific Domain Experts
+- **references/agents/performance-oracle.md**: Analyzes performance_issue category solutions
+- **references/agents/security-sentinel.md**: Reviews security_issue solutions for vulnerabilities
+- **references/agents/data-integrity-guardian.md**: Reviews database_issue migrations and queries
+
+### Enhancement & Research
+- **references/agents/best-practices-researcher.md**: Enriches solution with industry best practices
+- **references/agents/framework-docs-researcher.md**: Links to framework/library documentation references
+
+### When to Invoke
+- **Auto-triggered** (optional): Generic subagents seeded with local prompts can run post-documentation for enhancement
+- **Manual trigger**: User can run surviving skills such as `ce-simplify-code` after `ce-compound` completes for deeper code review and mutation

package/skills/ce-compound/references/grounding-validation.md

@@ -0,0 +1,89 @@
+# Grounding Validation (Phase 2.45)
+
+Read this when Phase 2.45 runs. The doc just written becomes permanent, trusted knowledge. Future agents will act on its claims without re-verifying them. This phase checks the claims against reality before they compound: a deterministic mechanical pass (bundled script) plus a semantic pass (one read-only validator subagent). Neither pass is a hard stop. You judge every flag, because solution docs legitimately cite deleted paths and pre-fix states.
+
+## Which tree is the ground truth
+
+Two claim categories verify against different trees:
+
+- **Code-behavior claims** (enum values, status semantics, limits, defaults) verify against the **local working tree**. They describe what this session's work produced and verified here.
+- **Merge-state claims** ("fixed in #1608", "landed", "shipped") verify against **remote truth**. The checkout may predate a merge, so `gh pr view` (or the tracker equivalent) is primary and local git reachability is only the fallback. The script's `INFO: worktree is N commits behind …` line tells you how much to distrust the local tree for this category.
+
+Before running the script, optionally run `git fetch --quiet` (best-effort; skip silently on failure or offline, because the network is never a correctness dependency). When remote state cannot be checked at all, keep the claim, add an as-of qualifier ("as of this writing"), and record degraded verification in the run report.
+
+## Step 1: Adjudicate the mechanical flags
+
+The script reports in two tiers and you decide each item. A **FLAG** is a claim it can defend; a **NOTE** is an item it reported without being able to classify, and notes do not affect its exit code. There are three resolutions, **fix**, **annotate**, or **confirm intentional**, and never an automatic rewrite or an automatic pass:
+
+| Flag | Likely meaning | Resolution |
+|------|----------------|------------|
+| path not found anywhere | Typo, or drafted from memory | Fix the citation or remove the claim |
+| path missing here, exists at upstream | Stale checkout | Verify the claim against upstream; annotate if the doc implies the file is present locally |
+| path deliberately gone (doc says removed/renamed) | Historical citation | Confirm the surrounding prose marks it as historical ("removed by this fix", "pre-fix state"); add that marker if absent |
+| SHA does not resolve, cited as a commit | Fabricated or from another repo | Replace with the PR number, or drop |
+| NOTE: unresolved hex, no commit context | The script cannot tell a session id or content hash from a commit; it is reporting, not accusing | Read the line: if it was never a commit citation, nothing to do; if it was, verify it |
+| SHA reachable from HEAD only | Local-only commit; SHA will change on rebase/squash merge | Replace with the PR number |
+| SHA reachable from upstream only | Checkout predates the merge | Keep, with a temporal qualifier; verify the landed claim via `gh` |
+| SHA exists but unreachable | Rebased-away commit | Replace with the PR number |
+| scaffold ("Learning 3", `{{…}}`) | Drafting-context leak | Always fix; rewrite as a real path or link |
+| relative link unresolved | Wrong target | Fix the path |
+
+If the script cannot be resolved on this platform, apply its checks manually at the same scope: scan the body for cited paths that do not exist, hex words presented as commits anywhere in the body (in commands and code blocks as much as in prose), `Learning(s) N` / `{{…}}` scaffold, and broken relative links. Note in the run output that the check was manual. Do not silently skip.
+
+After any body edit from this step or Step 2, re-run the script until it reports clean or every remaining flag is confirmed intentional.
+
+## Step 2: Semantic validator subagent (Full and non-interactive; skipped in lightweight)
+
+Dispatch **one generic read-only subagent** covering the written solution doc plus any `CONCEPTS.md` entries added or edited this run. Phase 2.4's entries are claims too; a glossary entry written from a session-level summary is exactly how wrong semantics enter the vocabulary. Use the same mid-tier model class as other reviewer subagents when the platform exposes one.
+
+If the user's or project's active instructions or the live prompt name a model for this subagent, use that model instead of the default tier above. They can name it by the subagent's tier, by its prompt-asset name, or for the subagents being dispatched. Without such an instruction, a model configured for this subagent's role takes precedence over the default tier.
+
+Build its prompt from this template:
+
+```
+You are a grounding validator for documentation about to enter a permanent
+knowledge store. You are read-only: never edit files. Inspect with Read,
+Grep, Glob, git (non-mutating), and gh when available.
+
+Inputs: the doc content below, the CONCEPTS.md entries below (if any), and
+this staleness context: <INFO line from the mechanical script, or "none">.
+
+Check every factual claim in three categories:
+
+1. CODE-BEHAVIOR CLAIMS — assertions about how code behaves: enum values,
+   status semantics, limits, defaults, ordering, state transitions. For
+   each, locate the defining source in the current tree and quote the
+   defining line(s) with file:line. Verdict: verified (with quote),
+   contradicted (with the quote showing otherwise), or unverifiable
+   (defining source not found).
+
+2. MERGE-STATE CLAIMS — assertions that a change landed ("fixed in",
+   "merged", "shipped in", "resolved by #N"). Primary check: gh pr view
+   <n> --json state,mergedAt,baseRefName (remote truth). Fallback: git
+   reachability from the upstream default branch. Verdict: verified,
+   contradicted (e.g. PR open, not merged), or unverifiable (offline / no
+   gh) — mark unverifiable as "degraded", do not guess.
+
+3. INTERNAL COMPLETENESS — countable assertions ("six PRs", "three root
+   causes", "all N consumers"). Count the substantiating items in the doc
+   itself. Verdict: complete, or short (found M of N).
+
+Ignore session narrative ("we first tried X") — that describes the
+conversation, not the tree. Ignore style.
+
+Return a structured list, one entry per claim checked:
+  claim (verbatim) | category | verdict | evidence (quote + file:line, or
+  command output) | suggested edit (only for non-verified claims)
+```
+
+**Orchestrator handling of verdicts:**
+
+- **contradicted** → fix the doc using the quoted evidence (the quote, not the conversation, is authoritative)
+- **unverifiable** (behavior) → soften or attribute ("per this session's conclusion…"), or drop the claim
+- **unverifiable/degraded** (merge-state) → keep with an as-of qualifier; record degraded verification in the report
+- **short** (completeness) → complete the enumeration or restate the count to match what the doc substantiates
+- **verified** → no change
+
+## Reporting
+
+Summarize the phase in one line of the run output (non-interactive report's `Grounding:` line; interactive success output): flags adjudicated (fixed / annotated / confirmed), claims checked, claims softened or corrected, and `degraded — merge-state claims unverified offline` when applicable.

package/skills/ce-compound/references/lightweight.md

@@ -0,0 +1,56 @@
+# Lightweight mode
+
+### Lightweight Mode
+
+<critical_requirement>
+**Single-pass alternative — same artifact type, reduced research and validation.**
+
+This mode skips parallel subagents entirely. The orchestrator performs all work in a single pass and writes the same solution-doc artifact type, but omits cross-referencing, duplicate detection, session-history research, and semantic grounding validation.
+
+Non-interactive mode enters Lightweight only when explicitly invoked with `depth:lightweight`; otherwise it defaults to Full for backward compatibility.
+</critical_requirement>
+
+The orchestrator (main conversation) performs ALL of the following in one sequential pass:
+
+1. **Extract from conversation**: Identify the problem and solution from conversation history. Also scan the "user's auto-memory" block injected into your system prompt, if present (Claude Code only). Use any relevant notes as supplementary context alongside conversation history. Tag any memory-sourced content incorporated into the final doc with "(auto memory [claude])". Before asserting how code behaves (enum values, status semantics, limits, defaults), Read the defining line at the current tree. Soften or attribute any claim you cannot verify. Cite PR numbers over bare commit SHAs, and phrase unmerged fixes as pending
+2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine track (bug vs knowledge), category, and filename. Sample existing docs under `<root>/solutions/` and choose `component`, `root_cause`, and the directory under the corpus-first rule in `references/yaml-schema.md` (it names what each is matched on and when the suggested defaults apply)
+3. **Write minimal doc**: Before writing, check whether the exact proposed `<root>/solutions/[category]/[filename].md` path exists. If it exists, read it: update it only when it covers the same problem, preserving its path and frontmatter structure and adding `last_updated: YYYY-MM-DD`; otherwise choose a distinct, descriptive filename and re-check that exact path is absent before writing. This is exact-path collision handling only — do not run Full mode's semantic overlap research or dispatch subagents. Create or update the doc using the appropriate track template from `assets/resolution-template.md`, with:
+   - YAML frontmatter with track-appropriate fields, applying the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules)
+   - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
+   - Knowledge track: Context, guidance with key examples, one applicability note
+4. **Vocabulary capture (update-only)**: if `CONCEPTS.md` exists at repo root, read `references/concepts-vocabulary.md`, then scan the new doc and the conversation for qualifying terms and add, refine, fold, or scrub entries silently, within the criteria and coherence-neighborhood bounds that reference states. If `CONCEPTS.md` does not exist, defer creation to a Full run, which is the run that seeds the file. Record the outcome in the output (e.g., "Vocabulary: 1 entry refined, 1 folded" or "scanned, no qualifying terms"). If this run changed `CONCEPTS.md` at all (added, refined, folded, or scrubbed) and the project's active instructions and conventions already in your context do not mention it, add the discoverability tip to the output below. Lightweight only **tips**; it does not edit instruction files. An interactive Full run makes that edit after consent; non-interactive Full also only tips and reports.
+5. **Read-only discoverability check**: Using the project's active instructions and conventions already in your context, assess whether they point agents to `<root>/solutions/` against the three criteria under **Discoverability Check** in `references/refresh-and-discoverability.md`. Do not open, offer to edit, or edit instruction files; Lightweight only reports the result. Record one of:
+   - `no gap` when active project instructions point agents to the knowledge store
+   - `gap noted — instruction-file tip emitted` when active project instructions exist but do not mention it
+   - `not applicable — no active project instructions` when no project instructions are active; emit no discoverability tip
+6. **Mechanical claims check**: run `scripts/validate-doc-claims.py` against the written doc exactly as in `references/assembly.md` Phase 2.45 step 1 (same `SKILL_DIR` anchor, same adjudicate-not-auto-fix rule; read `references/grounding-validation.md` for the adjudication table when it flags anything). Lightweight skips only the semantic validator subagent, not this deterministic check.
+7. **Frontmatter parser-safety check**: validate the written doc exactly as in `references/assembly.md` Phase 2 step 8, using the same bundled-script existence guard and manual fallback checklist. Fix any violation and repeat the check; do not report success until the written frontmatter is parser-safe.
+8. **Skip specialized agent reviews** (`references/enhancement.md`) and the semantic grounding validator (`references/assembly.md` Phase 2.45 step 2) to conserve context
+
+**User-runnable retry rendering.** In the lightweight completion output below, default to `/ce-compound`; use `$ce-compound` only when the active host is Codex or explicitly documents dollar-prefixed skill invocation. Render only the invocation as inline code and output one form only.
+
+**Lightweight completion output:** In non-interactive Lightweight, do not emit this interactive block; use the depth-specific report under `Non-interactive mode` in `references/report.md` instead. In interactive Lightweight, emit:
+```
+✓ Documentation complete (lightweight mode)
+
+File created:
+- <root>/solutions/[category]/[filename].md
+
+[If discoverability check found instruction files don't surface the knowledge store:]
+Tip: Your AGENTS.md/CLAUDE.md doesn't surface <root>/solutions/ to agents —
+a brief mention helps all agents discover these learnings.
+
+[If CONCEPTS.md changed at all this run and isn't surfaced in the instruction files:]
+Tip: Your AGENTS.md/CLAUDE.md doesn't surface CONCEPTS.md —
+a one-line mention helps agents find the shared vocabulary.
+
+Note: This was created in lightweight mode. For richer documentation
+(cross-references, detailed prevention strategies, specialized reviews,
+semantic grounding validation), re-run <rendered invocation> in a fresh session.
+```
+
+**No subagents are launched. No parallel tasks. The solution doc is the one deliverable** (Phase 2.4's update-only vocabulary capture may also change an existing `CONCEPTS.md`).
+
+In lightweight mode, the overlap check is skipped (no Related Docs Finder subagent). This means lightweight mode may create a doc that overlaps with an existing one. That is acceptable; `ce-compound-refresh` will catch it later. Only suggest `ce-compound-refresh` if there is an obvious narrow refresh target. Do not broaden into a large refresh sweep from a lightweight session.
+
+---

package/skills/ce-compound/references/modes.md

@@ -0,0 +1,13 @@
+# Depth and session-history: why neither is a question
+
+Both are decisions the agent is better positioned to make than the user. Depth depends on the context budget the agent can observe and the user cannot. Neither party can know in advance whether session history will pay off, because the payoff is an unrelated earlier session the current agent was never in. So a cheap probe decides it instead of a question to the user.
+
+**Full is the right choice for essentially every documented learning.** Its token cost is small next to the engineering work that produced the learning, and it is dwarfed by the value of a doc that compounds. Lightweight buys back context at the cost of cross-referencing, overlap detection, and semantic grounding validation, so it is for real context pressure only. If Lightweight turns out to be the wrong call for the user's taste, re-running is a rare, cheap correction. It is cheaper than taxing every run with a question.
+
+**The session-history probe is near-free on wall-clock** because it runs alongside the Related Docs Finder and your drafting, and it escalates to the expensive extraction and synthesis only when genuinely relevant candidate sessions turn up (`references/session-history.md`). This support exists only inside the compounding workflow; there is no standalone session-history feature for users.
+
+## Auto-Invoke
+
+Completion phrases such as "that worked", "it's fixed", "working now", and "problem solved" identify the completion checkpoint; they do not establish that a learning is worth documenting. Auto-invoke only when the Preconditions in `SKILL.md` qualify the learning.
+
+An explicit invocation with optional context requests immediate evaluation without waiting for auto-detection. It does not waive the solved, verified, and durable-learning preconditions.

package/skills/ce-compound/references/refresh-and-discoverability.md

@@ -0,0 +1,96 @@
+# Phase 2.5 and the Discoverability Check
+
+### Phase 2.5: Selective Refresh Check
+
+After writing the new learning, decide whether this new solution is evidence that older docs should be refreshed.
+
+`ce-compound-refresh` is **not** a default follow-up. Use it selectively when the new learning suggests an older learning or pattern doc may now be inaccurate.
+
+It makes sense to invoke `ce-compound-refresh` when one or more of these are true:
+
+1. A related learning or pattern doc recommends an approach that the new fix now contradicts
+2. The new fix clearly supersedes an older documented solution
+3. The current work involved a refactor, migration, rename, or dependency upgrade that likely invalidated references in older docs
+4. A pattern doc now looks overly broad, outdated, or no longer supported by the refreshed reality
+5. The Related Docs Finder surfaced high-confidence refresh candidates in the same problem space
+6. The Related Docs Finder reported **moderate overlap** with an existing doc, so there may be consolidation opportunities that benefit from a focused review
+
+It does **not** make sense to invoke `ce-compound-refresh` when:
+
+1. No related docs were found
+2. Related docs still appear consistent with the new learning
+3. The overlap is superficial and does not change prior guidance
+4. Refresh would require a broad historical review with weak evidence
+
+Use these rules:
+
+- If there is **one obvious stale candidate**, invoke `ce-compound-refresh` with a narrow scope hint after the new learning is written
+- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set
+- If context is already tight or you are in lightweight mode, do not expand into a broad refresh automatically; instead recommend `ce-compound-refresh` as the next step with a scope hint
+- **In non-interactive mode**, never invoke `ce-compound-refresh` and never ask the user. Put the recommended scope hint in the terminal report's "Refresh recommendation" line and let the caller decide
+
+**User-runnable refresh rendering.** When recommending rather than directly invoking `ce-compound-refresh`, default to `/ce-compound-refresh <scope>`; use `$ce-compound-refresh <scope>` only when the active host is Codex or explicitly documents dollar-prefixed skill invocation. Render only the invocation as inline code and output one form only. Agent-to-agent invocation remains semantic.
+
+When invoking or recommending `ce-compound-refresh`, be explicit about the argument to pass. Prefer the narrowest useful scope:
+
+- **Specific file** when one learning or pattern doc is the likely stale artifact
+- **Module or component name** when several related docs may need review
+- **Category name** when the drift is concentrated in one solutions area
+- **Pattern filename or pattern topic** when the stale guidance lives in `<root>/solutions/patterns/`
+
+Examples:
+
+- `ce-compound-refresh release-please-version-drift-recovery`
+- `ce-compound-refresh payments`
+- `ce-compound-refresh performance-issues`
+- `ce-compound-refresh critical-patterns`
+
+A single scope hint may still expand to multiple related docs when the change is cross-cutting within one domain, category, or pattern area.
+
+Do not invoke `ce-compound-refresh` without an argument unless the user explicitly wants a broad sweep.
+
+Always capture the new learning first. Refresh is a targeted maintenance follow-up, not a prerequisite for documentation.
+
+### Discoverability Check
+
+After the learning is written and the refresh decision is made, check whether the project's instruction files would lead an agent to discover and search `<root>/solutions/` before starting work in a documented area. This runs every time. The knowledge store only compounds value when agents can find it.
+
+1. Identify which root-level instruction files exist (AGENTS.md, CLAUDE.md, or both). Read the file(s) and determine which holds the substantive content — one file may just be a shim that `@`-includes the other (e.g., `CLAUDE.md` containing only `@AGENTS.md`, or vice versa). The substantive file is the assessment and edit target; ignore shims. If neither file exists, skip this check entirely.
+2. Assess whether an agent reading the instruction files would learn three things:
+   - That a searchable knowledge store of documented solutions exists
+   - Enough about its structure to search effectively (category organization, YAML frontmatter fields like `module`, `tags`, `problem_type`)
+   - When to search it (before implementing features, debugging issues, or making decisions in documented areas — learnings may cover bugs, best practices, workflow patterns, or other institutional knowledge)
+
+   This is a semantic assessment, not a string match. The information could be a line in an architecture section, a bullet in a gotchas section, spread across multiple places, or expressed without ever using the exact path `<root>/solutions/`. Use judgment. If an agent would reasonably discover and use the knowledge store after reading the file, the check passes.
+
+3. If the spirit is already met, no action is needed; move on.
+4. If not:
+   a. Based on the file's existing structure, tone, and density, identify where a mention fits naturally. Before creating a new section, check whether the information could be a single line in the closest related section: an architecture tree, a directory listing, a documentation section, or a conventions block. A line added to an existing section is almost always better than a new headed section. Only add a new section as a last resort when the file has clear sectioned structure and nothing is even remotely related.
+   b. Draft the smallest addition that communicates the three things. Match the file's existing style and density. The addition should describe the knowledge store itself, not the plugin. An agent without the plugin should still find value in it.
+
+      Keep the tone informational, not imperative. Express timing as description, not instruction, for example "relevant when implementing or debugging in documented areas" rather than "check before implementing or debugging." Imperative directives like "always search before implementing" cause redundant reads when a workflow already includes a dedicated search step. The goal is awareness: agents learn the folder exists and what is in it, then use their own judgment about when to consult it.
+
+      **Substitute the concrete root in what you write.** The examples below show `<root>/solutions/`, but the instruction file is read by agents without this plugin (and by people), who cannot resolve `<root>`. When you insert the text, replace `<root>` with the resolved concrete path, never the literal placeholder. That path is the actual artifact directory, which is the default `docs` root's `solutions/` unless a `docs_root` is configured.
+
+      Examples of calibration (not templates; adapt to the file):
+
+      When there is an existing directory listing or architecture section, add a line:
+      ```
+      <root>/solutions/  # documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type)
+      ```
+
+      When nothing in the file is a natural fit, a small headed section is appropriate:
+      ```
+      ## Documented Solutions
+
+      `<root>/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas.
+      ```
+   c. In full interactive mode, explain to the user why this matters. Agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) will not know to check `<root>/solutions/` unless the instruction file mentions it. Show the proposed change and where it would go, then get consent before making the edit through the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability. Do not search for another host's tool name. Fall back to presenting the proposal in the host's user-visible chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes), not because a schema load is required. Never silently skip the question. In lightweight mode (interactive or non-interactive), output a one-liner note and move on. In full non-interactive mode, **do not edit instruction files**. Report the gap in the terminal report as `Instruction-file edit: gap noted, not applied` (non-interactive scope is documentation capture, not project-config edits; a human-invoked interactive run applies the edit with consent)
+
+5. **If `CONCEPTS.md` exists at repo root, run a parallel discoverability check for it.** Assess whether the instruction file would lead an agent to discover the project's shared domain vocabulary. Use the same workflow as the `<root>/solutions/` check above: same target file, same edit-placement judgment, same consent-then-edit interaction shape per mode. A line in an existing section is almost always better than a new headed section. Example calibration when nothing else fits:
+
+   ```
+   CONCEPTS.md  # shared domain vocabulary (entities, named processes, status concepts) — relevant when orienting to the codebase or discussing domain concepts
+   ```
+
+   **Skip this step entirely if `CONCEPTS.md` does not exist.** Never nag for an artifact the project has not adopted. When skipped, this step produces no output and no edit.

package/skills/ce-compound/references/report.md

@@ -0,0 +1,115 @@
+# Completion reports
+
+## Success Output
+
+**User-runnable refresh rendering.** The reports below print a `ce-compound-refresh` invocation for the user to copy. Default to `/ce-compound-refresh <scope>`; use `$ce-compound-refresh <scope>` only when the active host is Codex or explicitly documents dollar-prefixed skill invocation. Render only the invocation as inline code and output one form only.
+
+### Non-interactive mode
+
+Emit a structured terminal report as the last thing this skill writes. No "What's next?" question, no blocking prompt. The report ends this skill, not the turn. When a caller invoked this skill, its next step follows the report in the same session; otherwise end the turn. End with `Documentation complete` as the terminal signal so callers can detect completion.
+
+For `depth:lightweight`, use this lower-overhead report after the Lightweight Mode workflow:
+
+```
+✓ Documentation complete (non-interactive lightweight mode)
+
+File: <root>/solutions/<category>/<filename>.md  (created | updated)
+Track: <bug | knowledge>
+Category: <category>
+Grounding: <mechanical check clean | N flags adjudicated>
+Discoverability: <no gap | gap noted — instruction-file tip emitted | not applicable — no active project instructions>
+CONCEPTS.md: <not present | scanned, no qualifying terms | updated — N added, N refined, N folded, N scrubbed>
+CONCEPTS.md discoverability: <not checked — CONCEPTS.md unchanged | no gap | gap noted — instruction-file tip emitted | not applicable — no active project instructions>
+Refresh recommendation: <none | scope hint for /ce-compound-refresh>
+
+Documentation complete
+```
+
+For `depth:full` or backward-compatible non-interactive calls with no depth token, use the Full report:
+
+```
+✓ Documentation complete (non-interactive mode)
+
+File: <root>/solutions/<category>/<filename>.md  (created | updated)
+Track: <bug | knowledge>
+Category: <category>
+Overlap: <none | low | moderate — see <path> | high — existing doc updated>
+Grounding: <clean | N flags adjudicated (X fixed, Y annotated, Z confirmed) | N claims softened or corrected | degraded — merge-state claims unverified offline>
+Instruction-file edit: <none needed | gap noted, not applied>
+CONCEPTS.md: <scanned, no qualifying terms | created with N entries (M seeded from the learning's area) | updated — N added, N refined, N folded, N scrubbed>
+Refresh recommendation: <none | scope hint for /ce-compound-refresh>
+
+Documentation complete
+```
+
+When no doc was written (e.g., non-interactive invoked on a session where the problem is not yet solved), emit a structured failure instead and end with `Documentation skipped` so callers can distinguish success from no-op:
+
+```
+✗ Documentation skipped (non-interactive mode)
+
+Reason: <one-sentence explanation — e.g., "no solved problem detected in
+conversation history" or "solution not yet verified">
+
+Documentation skipped
+```
+
+### Interactive mode
+
+```
+✓ Documentation complete
+
+Ran Full mode.
+Auto memory: 2 relevant entries used as supplementary evidence
+
+Research Results:
+  ✓ Classified: performance_issue in background_job (component from corpus), category: performance-issues/
+  ✓ Drafted: 3 code fixes, prevention strategies
+  ✓ Related Docs Finder: 2 related issues
+  ✓ Session History: 3 prior sessions in this repo, 2 failed approaches surfaced
+
+Grounding Validation:
+  ✓ Mechanical check: 14 paths, 2 SHAs, 3 links checked — 1 flag annotated as historical
+  ✓ Semantic validator: 9 claims verified, 1 merge-state claim softened to pending
+
+Specialized Agent Reviews (Auto-Triggered):
+  ✓ performance-oracle: Validated query optimization approach
+  ✓ Code simplification review: Code examples are appropriately minimal
+
+Files written:
+- <root>/solutions/performance-issues/n-plus-one-brief-generation.md (created)
+- CONCEPTS.md (created with 3 entries: BriefSystem, EmailQueue, Brief Status)
+
+This documentation will be searchable for future reference when similar
+issues occur in the Email Processing or Brief System modules.
+
+Refresh recommendation: none
+```
+
+`Files written:` lists the destination the assembly step settled on. That is a pack rule's path (`<pack dir>/<file>.md`) when the user routed the capture into a writable pack, and the `<root>/solutions/` path otherwise.
+
+**The summary is the last thing this skill writes. When a caller invoked this skill, its next step follows the summary in the same session; otherwise end the turn. `ce-compound` does not present a "What's next?" menu.** The doc is written and any cross-references the workflow found are already in it. Cross-doc maintenance (fixing references in *other* docs, consolidation) is left to `ce-compound-refresh`, the skill designed for it, through the `Refresh recommendation` line above. It is not applied here, because that would edit tracked docs beyond the one deliverable. If the user wants to view the file or take a follow-up action, they will ask. (Interactive mode only.)
+
+**Alternate interactive output (when updating an existing doc due to high overlap):** in non-interactive mode, this case is communicated via the `Overlap: high — existing doc updated` line of the non-interactive terminal report above, not as a separate output block.
+
+```
+✓ Documentation updated (existing doc refreshed with current context)
+
+Overlap detected: <root>/solutions/performance-issues/n-plus-one-queries.md
+  Matched dimensions: problem statement, root cause, solution, referenced files
+  Action: Updated existing doc with fresher code examples and prevention tips
+
+File updated:
+- <root>/solutions/performance-issues/n-plus-one-queries.md (added last_updated: 2026-03-24)
+```
+
+## Common Mistakes to Avoid
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| Subagents write product files into `docs/` or edit tracked paths | Subagents write only scratch artifacts under `<run-dir>/` and return the path; orchestrator writes the one final doc |
+| Subagent returns a long prose body only as its inline response | Subagent writes full output to its run artifact; orchestrator Reads it back (inline return is fallback only) |
+| Research and assembly run in parallel | Research completes → then assembly runs |
+| Non-interactive Discoverability Check edits AGENTS.md/CLAUDE.md | non-interactive Full reports `Instruction-file edit: gap noted, not applied`; non-interactive Lightweight emits a discoverability tip; only interactive Full applies the edit after consent |
+| Creating a new doc when an existing doc covers the same problem | Check overlap assessment; update the existing doc when overlap is high |
+| Asserting code behavior or merge-state from conversation memory | Read the defining source line before asserting; cite PR numbers over SHAs; soften unverifiable claims (Phase 1 extractor rules, re-checked in Phase 2.45) |
+| Batching several learnings through one run and stitching cross-references between drafts | One learning per run; run the skill sequentially for each additional learning |