@sandgarden/gloria 0.0.0-stage → 0.3.87

package/skills/setting-up-a-project/TDD.rules.md

@@ -0,0 +1,196 @@
+# Rules for Claude
+
+## ABSOLUTE RULES - NO EXCEPTIONS
+
+### 1. Test-Driven Development is MANDATORY
+
+**The Iron Law**: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+
+Every single line of production code MUST follow this cycle:
+
+1. **RED**: Write failing test FIRST
+2. **Verify RED**: Run test, watch it fail for the RIGHT reason
+3. **GREEN**: Write MINIMAL code to pass the test
+4. **Verify GREEN**: Run test, confirm it passes
+5. **REFACTOR**: Clean up with tests staying green
+
+### 2. Violations = Delete and Start Over
+
+If ANY of these occur, you MUST delete the code and start over:
+
+- ❌ Wrote production code before test → DELETE CODE, START OVER
+- ❌ Test passed immediately → TEST IS WRONG, FIX TEST FIRST
+- ❌ Can't explain why test failed → NOT TDD, START OVER
+- ❌ "I'll add tests later" → DELETE CODE NOW
+- ❌ "Just this once without tests" → NO. DELETE CODE.
+- ❌ "It's too simple to test" → NO. TEST FIRST.
+- ❌ "Tests after achieve same goal" → NO. DELETE CODE.
+
+### 3. Test Coverage Requirements
+
+- **Minimum 90%** coverage on ALL metrics:
+  - Lines: 90%+
+  - Functions: 90%+
+  - Branches: 85%+
+  - Statements: 90%+
+- Coverage below threshold = Implementation incomplete
+- Untested code = Code that shouldn't exist
+
+### 4. Implementation Order
+
+Follow the plan tasks listed in @IMPLEMENTATION_PLAN.md in EXACT order.
+
+### 5. Before Writing ANY Code
+
+Ask yourself:
+
+1. Did I write a failing test for this?
+2. Did I run the test and see it fail?
+3. Did it fail for the expected reason?
+
+If ANY answer is "no" → STOP. Write the test first.
+
+### 6. Test File Structure
+
+For every production file, there MUST be a corresponding test file:
+
+- `src/example.ts` → `src/__tests__/example.test.ts`
+- `src/another-example.ts` → `src/__tests__/another-example.test.ts`
+- `src/causes_edge_cases.ts` → `src/__tests__/causes_edge_cases.test.ts`
+
+### 7. Task Completion Requirements
+
+**MANDATORY RULE**: NO TASK IS COMPLETE until:
+
+- ✅ ALL tests pass (100% green)
+- ✅ Build succeeds with ZERO errors
+- ✅ NO linter errors or warnings
+- ✅ Coverage meets minimum thresholds (90%+)
+
+A task with failing tests, build errors, or linter warnings is INCOMPLETE. Period.
+
+### 8. Git Commits - Commit Early, Commit Often
+
+**MANDATORY RULE**: COMMIT EARLY, COMMIT OFTEN
+
+- **Commit after EACH successful TDD cycle**:
+  - ✅ After RED-GREEN-REFACTOR cycle completes
+  - ✅ After each test file is created
+  - ✅ After each module implementation
+  - ✅ After fixing bugs or issues
+  - ✅ After updating documentation
+
+- **Frequency Requirements**:
+  - Minimum: After each completed subtask
+  - Maximum: No more than 30 minutes without a commit
+  - Never have more than one feature in a single commit
+
+- **Each commit MUST**:
+  - Have failing tests written first
+  - Pass all tests
+  - Build successfully
+  - Have no linter errors
+  - Meet coverage requirements (if code was added)
+  - Include clear commit message mentioning TDD
+
+- **Commit Message Format**:
+
+  ```
+  type(scope): brief description
+
+  - RED: What tests were written first
+  - GREEN: What minimal code was added
+  - Status: X tests passing, build successful
+  - Coverage: X% (if applicable)
+  ```
+
+- **Benefits of Frequent Commits**:
+  - Easy rollback if something breaks
+  - Clear history of TDD progression
+  - Smaller, reviewable changes
+  - Proof of TDD discipline
+
+## Development Workflow
+
+For EACH feature/function:
+
+```
+1. Write test file or add test case
+2. Run: <test command>
+3. See RED (test fails)
+4. Understand WHY it fails
+5. Write minimal production code
+6. Run: <test command>
+7. See GREEN (test passes)
+8. Refactor if needed
+9. Run: <test command> (stays green)
+10. Check coverage: <coverage command>
+11. Repeat for next feature
+```
+
+## Commands You'll Use Constantly
+
+```bash
+# Watch mode - keep this running ALWAYS
+<test command>
+
+# Run once
+<test command>
+
+# Check coverage
+<coverage command>
+
+# Build - MUST succeed before task is complete
+<build command>
+
+# Check for Linter errors
+<linter command>
+```
+
+## Red Flags - STOP Immediately
+
+If you catch yourself:
+
+- Opening a code file before a test file
+- Writing function implementation before test
+- Thinking "I know this works"
+- Copying code from examples without tests
+- Skipping test runs
+- Ignoring failing tests
+- Writing multiple features before testing
+
+**STOP. DELETE. START WITH TEST.**
+
+## The Mindset
+
+- Tests are not optional
+- Tests are not added after
+- Tests DRIVE the implementation
+- If it's not tested, it doesn't exist
+- Coverage below 90% = unfinished work
+
+## Accountability Check
+
+Before marking ANY task complete, verify:
+
+1. ✓ Test written first?
+2. ✓ Test failed first?
+3. ✓ Minimal code to pass?
+4. ✓ All tests green?
+5. ✓ Coverage maintained (90%+)?
+6. ✓ Build succeeds (`<build command>`)?
+7. ✓ No linter errors?
+
+Missing ANY ✓ = Task is NOT complete. Fix it first.
+
+## Final Rule
+
+**When in doubt**: Write a test.
+**When not in doubt**: Write a test anyway.
+**When it seems too simple**: Especially write a test.
+
+There are NO exceptions to TDD in this project. None.
+
+---
+
+_This document is your contract. Breaking these rules means breaking the project's core quality commitment. The discipline of TDD is what separates professional, reliable code from hopeful guesswork._

package/skills/setting-up-a-project/git-commit-rules.md

@@ -0,0 +1,16 @@
+## Git Commit Rules
+
+**COMMIT EARLY, COMMIT OFTEN** - This is mandatory.
+
+- Commit after every successful TDD cycle (RED-GREEN-REFACTOR)
+- Commit after completing any discrete unit of work
+- Commit before switching context or taking breaks
+- Never have more than 30 minutes of uncommitted work
+- Each commit should be atomic: one logical change per commit
+
+Why this matters:
+
+- Small commits are easier to review and revert
+- Frequent commits prevent loss of work
+- Atomic commits make git history useful for debugging
+- Regular commits force you to think in small, testable increments

package/skills/setting-up-gloria/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: setting-up-gloria
+description: For a project that's already set up (has, or intentionally has no, its own CLAUDE.md/AGENTS.md) and just needs Gloria wired in — not for a brand-new project with no CLAUDE.md yet (use `setting-up-a-project` for that, which chains into this skill automatically at the end). Use when installing Gloria into a repo ("set up gloria", "install gloria in this project"), when a repo is missing .gloria/USING-GLORIA.md or the gloria section in CLAUDE.md/AGENTS.md, or after a gloria plugin update to refresh a stale doc — copies the canonical USING-GLORIA.md agent doc into the repo, wires an evergreen Gloria section into the agent instruction files (with the user's permission), and offers to register the project with gloria.dev. Idempotent; safe to re-run.
+---
+
+# Setting Up Gloria
+
+## Overview
+
+Wire Gloria into the current repo so every coding agent that works here knows
+what Gloria is and when to use it. Two files carry that:
+
+1. **`.gloria/USING-GLORIA.md`** — the agent playbook, copied verbatim from
+   the `USING-GLORIA.md` that sits next to this SKILL.md (the skill's base
+   directory). Committed to the repo.
+2. **A marked section in the repo's agent instruction files** (`CLAUDE.md`
+   and/or `AGENTS.md`) that points unconditionally at the doc. The section is
+   evergreen — it names no features, so it never changes across Gloria
+   releases; only the doc does.
+
+Never modify the user's files without showing them exactly what will change
+and getting a yes first.
+
+This skill assumes the repo is already set up (or deliberately has no
+CLAUDE.md of its own) — it only ever inserts/updates the marked Gloria
+section inside existing instruction files, or creates a bare `AGENTS.md`
+holding just that section. For a brand-new, empty repo that needs a full
+CLAUDE.md authored from scratch, use `setting-up-a-project` instead — it
+runs the full interview and, as its last step, offers to run this skill
+automatically.
+
+## The instruction-file section
+
+Insert this text exactly, markers included. The markers are how re-runs find
+and replace the section instead of duplicating it.
+
+```markdown
+<!-- gloria:start -->
+
+## Gloria
+
+This project uses [Gloria](https://gloria.dev) to keep agent-written code
+aligned with intent — dependency monitoring, shared skills, and more. Gloria's
+tools and skills apply to everyday coding tasks, not just Gloria-specific
+requests.
+
+Before starting work in this repo, read `.gloria/USING-GLORIA.md`. It explains
+which Gloria tools and skills to use, and when. When it names a trigger that
+matches your current task, using the corresponding tool/skill is required, not
+optional.
+
+<!-- gloria:end -->
+```
+
+## Workflow
+
+### 1. Detect state
+
+- Find the repo root (`git rev-parse --show-toplevel`; fall back to the
+  working directory if not a git repo).
+- Locate the shipped doc: the `USING-GLORIA.md` in this skill's base
+  directory. If it is missing, stop and tell the user the plugin install
+  looks broken — do not synthesize the doc from memory.
+- Check what already exists at the repo root:
+  - `.gloria/USING-GLORIA.md` — present? Compare its `gloria-doc-version`
+    stamp (first line) with the shipped copy's.
+  - `CLAUDE.md`, `AGENTS.md` — which exist, and does each already contain a
+    `<!-- gloria:start -->` ... `<!-- gloria:end -->` block?
+
+### 2. Propose and ask permission — once
+
+Tell the user precisely what will happen, in one message, and ask a single
+yes/no. Cover only the actions actually needed, e.g.:
+
+- create (or replace, if the stamp differs) `.gloria/USING-GLORIA.md`;
+- insert the Gloria section into `CLAUDE.md` and `AGENTS.md` (or "replace the
+  existing Gloria section in ...");
+- create `AGENTS.md` containing the section, when neither instruction file
+  exists.
+
+If everything is already current, say so and skip to step 5. If the user
+declines the file edits, stop — do not partially apply.
+
+### 3. Write the doc
+
+Copy the shipped `USING-GLORIA.md` to `.gloria/USING-GLORIA.md` **verbatim**
+(create the `.gloria/` directory if needed). Do not edit, reformat, or
+"improve" the content — refreshes must stay a pure file copy.
+
+### 4. Wire the instruction files
+
+For each of `CLAUDE.md` and `AGENTS.md` that exists at the repo root:
+
+- If it contains a marker block, replace everything from
+  `<!-- gloria:start -->` through `<!-- gloria:end -->` (inclusive) with the
+  section above.
+- Otherwise append the section at the end of the file, preceded by one blank
+  line.
+
+If neither file exists, create `AGENTS.md` containing only the section
+(AGENTS.md is the cross-agent standard; Claude Code reads it too).
+
+### 5. Offer project registration
+
+- Call the `gloria` MCP tool `get_info`.
+  - If the call fails (not authenticated / server unreachable), tell the user
+    the files are wired but registration needs an MCP login, mention the
+    login step for their agent, and finish. Setup is still a success.
+- Call `list_projects` and look for a project matching this repo (by name or
+  repo URL). If none matches, offer to run `register_project`. Registration
+  is optional — a "no" still completes setup.
+
+### 6. Report
+
+Summarize what changed (files created/updated, section inserted where,
+registration outcome) and suggest committing the changes, e.g.
+`chore: wire gloria agent doc into instruction files`.
+
+Token-usage tracking (declaring work items, minting the collector's ingest
+credential) moved to the Miranda plugin's own `setting-up-usage-tracking`
+skill — offer that separately if the user has Miranda installed and hasn't
+set it up yet.
+
+## Idempotency rules
+
+- Re-running with identical content is a no-op; say "already current".
+- A stale `.gloria/USING-GLORIA.md` (older stamp) is overwritten wholesale.
+- Marker blocks are always replaced in place, never duplicated. If a file
+  somehow contains multiple marker blocks, replace the first and remove the
+  rest, and mention it.
+- Never touch anything outside the marker block in an instruction file, and
+  never edit any other file.
+
+## When to suggest this skill proactively
+
+- A Gloria MCP tool's `get_info` response carries a `latestAgentDocVersion`
+  newer than the repo's `.gloria/USING-GLORIA.md` stamp → offer a refresh.
+- The user just installed or updated the Gloria plugin in a repo with no
+  `.gloria/USING-GLORIA.md` → offer initial setup.

package/skills/setting-up-gloria/USING-GLORIA.md

@@ -0,0 +1,144 @@
+<!-- gloria-doc-version: 0.3.87 -->
+
+# Using Gloria
+
+[Gloria](https://gloria.dev) keeps agent-written code aligned with intent. It
+watches the places where implementation drifts from what the team wants —
+dependencies, shared skills, project documents — and gives you, the coding
+agent, tools to keep them in sync. This project has adopted Gloria: the
+triggers below are commitments the team has made, not suggestions. When a
+trigger matches the task you are doing, take the corresponding action.
+
+Gloria is available two ways, and both apply to you:
+
+- **MCP tools** on the `gloria` server (dependencies, skills library,
+  documents, Doc Holiday).
+- **Agent skills** installed with the Gloria plugin (invoke them by name; do
+  not improvise their workflows by hand).
+
+**Vocabulary — "register" and "sync" mean call a Gloria tool.** When the user
+says **"register"** or **"sync"** a resource **with Gloria** — a dependency, a
+project, a coding standard, a rule, a snippet, a document — they mean: call the
+matching Gloria MCP tool (`put_dependency`, `register_project`,
+`register_standard`, `put_rule`, `put_snippet`, `put_document`), **not** perform
+the underlying action informally or just edit a file. "Register this dependency"
+→ `put_dependency`; "sync my project with Gloria" → `register_project` (via the
+`documenting-service-dependencies` skill); "register our standards" → the
+`extracting-coding-standards` skill's `register_standard` / `put_rule` /
+`put_snippet` flow. If a request names one of these resources with "register" or
+"sync", route it to the corresponding tool or skill below.
+
+## Start of every session
+
+One cheap check, done as early as possible — before other Gloria work, and
+regardless of what the task turns out to be:
+
+**Check this file isn't stale.** Call `get_info` (cheap) and compare its
+`latestAgentDocVersion` field to the `gloria-doc-version` stamped at the top
+of this file. If newer, tell the user and offer to re-run `setting-up-gloria`
+— see "Keeping this file current" below.
+
+If this org also uses Miranda (token-cost tracking), its plugin's own
+`.miranda/USING-MIRANDA.md` — installed by the `setting-up-usage-tracking`
+skill — has its own "start of every session" obligation (declaring the work
+item via `tag_session_work_item`). That lives there, not here.
+
+## Keeping this file current
+
+This file is written by the `setting-up-gloria` skill and stamped with the
+plugin version that shipped it (see the first line). Check it for staleness
+at the start of every session (see above), not just the first time some
+other task happens to call a Gloria tool. Never edit this file by hand — it
+is replaced verbatim on refresh.
+
+## When to use Gloria
+
+| The moment in your work                                                                                       | Required action                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| You added, removed, or swapped an external service, SaaS API, SDK, or API client                              | Update the dependency inventory: run the `documenting-service-dependencies` skill, or for a single obvious change sync directly with `put_dependency` / `delete_dependency` |
+| You changed how an internal system is reached (new database, queue, internal API, or a changed endpoint/auth) | Same as above — internal dependencies are monitored too                                                                                                                     |
+| The user asks what this project depends on, or whether a vendor/service is healthy                            | `list_dependencies` / `get_dependency` — answer from Gloria's inventory, not just from reading code                                                                         |
+| You are about to author a new agent skill, or the user asks "do we have a skill for X?"                       | `search_skills` FIRST. Only author when nothing fits; follow the `using-the-skills-library` skill                                                                           |
+| You built a skill or workflow worth reusing across the org                                                    | Publish it: `publish_skill` (see `using-the-skills-library`)                                                                                                                |
+| The user wants a skill from an external marketplace the org subscribes to                                     | `list_marketplaces`, then `install_skill`                                                                                                                                   |
+| You produced a durable project document (dependency inventory, architecture map, docs site map)               | Store it with `put_document` so teammates and other agents see it                                                                                                           |
+| A Gloria tool reports the project is not registered                                                           | `get_info`, then offer `register_project`                                                                                                                                   |
+| The user updated the Gloria plugin, or this file looks wrong or stale                                         | Offer to re-run `setting-up-gloria`                                                                                                                                         |
+| The user asks for documentation to be written or updated via Doc Holiday                                      | Use the `doc_holiday_*` tools (see below)                                                                                                                                   |
+
+## MCP tools reference
+
+All tools run as the authenticated user against their active organization.
+Reads need `inventory:read` (any member); writes need `inventory:write`;
+`publish_skill` needs admin (`settings:manage`).
+
+**Org & projects**
+
+- `get_info` — org id/name/slug plus `latestAgentDocVersion`. Cheap; call it
+  first when you need org context or a staleness check.
+- `register_project` — register this repo as a gloria.dev project.
+- `list_projects` — the org's registered projects.
+
+**Dependencies (Canary)**
+
+- `put_dependency` — create/update a dependency and its health-check
+  definition. May return a Configure-secrets link when a check needs a
+  credential; pass that link to the user, never ask for the secret in chat.
+- `get_dependency`, `list_dependencies` — inventory and current status.
+- `delete_dependency` — remove a dependency that no longer exists in code.
+
+**Skills library**
+
+- `search_skills` — search the org's library; always precedes authoring.
+- `get_skill` — fetch a skill bundle (latest or a specific version).
+- `publish_skill` — publish an immutable new version org-wide.
+- `list_skill_versions` — a skill's version history.
+- `list_marketplaces`, `install_skill` — external marketplaces the org
+  subscribes to, and installing from them via the host agent's native
+  mechanism.
+
+**Documents**
+
+- `put_document` — store a Markdown document against the project.
+
+**Doc Holiday** (documentation automation; requires the org's Doc Holiday API
+key, configured in gloria.dev Settings)
+
+- Browse: `doc_holiday_list_publications`, `doc_holiday_get_publication`,
+  `doc_holiday_list_conversations`, `doc_holiday_list_conversation_turns`,
+  `doc_holiday_get_conversation_turn`,
+  `doc_holiday_list_conversation_comments`,
+  `doc_holiday_get_conversation_diffs`.
+- Act: `doc_holiday_request_documentation` (new docs from a prompt),
+  `doc_holiday_request_work` (follow-up work on a conversation).
+
+## Skills reference
+
+Invoke these by name when their trigger matches; each skill contains its own
+full workflow.
+
+- `documenting-service-dependencies` — map and document every external and
+  internal service dependency, with health checks, and sync them to Gloria.
+  Trigger: dependency changes; "document our integrations"; "what does this
+  connect to?"
+- `using-the-skills-library` — search/publish/install org skills. Trigger:
+  about to author a skill; "do we already have a skill for this?"; sharing a
+  reusable skill.
+- `identifying-skills-for-a-project` — inventory the skills a project uses
+  and recommend gaps. Trigger: "what skills would help this project?"
+- `defining-the-documentation-site-map` — plan a Diátaxis-organized docs site
+  from the source. Trigger: "what should our docs contain?"
+- `setting-up-gloria` — wire Gloria into a repo (this file + instruction-file
+  section) and offer registration. Trigger: "set up gloria"; plugin updated;
+  this file missing or stale.
+
+## First-time and recovery
+
+- **Project not registered** — `register_project` needs `inventory:write`.
+  Offer it once; if the user declines, continue without syncing.
+- **MCP auth fails** — the user must log in to the `gloria` server: Claude
+  Code `/mcp` → gloria → authenticate; Codex `codex mcp login gloria`;
+  OpenCode follows its MCP auth flow. Until then, skills still work — queue
+  the sync and mention it.
+- **This file is missing, stale, or contradicts the tools you see** — trust
+  the live MCP server, and offer to re-run `setting-up-gloria`.

package/skills/using-coding-standards/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: using-coding-standards
+description: Use while writing code in a project with a registered gloria Coding Standards library — before implementing anything pattern-shaped (a DAO, an API route, a migration, a test harness, a channel adapter), and whenever CLAUDE.md carries a "## Coding Standards" section with a gloria:standards stamp. Also fires for "follow/use our standards while writing this", "write this the way we do", and "register/contribute this back as a snippet". Drives the write-time discipline: find_snippets before writing, adopt or adapt the canonical exemplar, leave a gloria:snippet provenance marker, contribute reusable shapes back via put_snippet, and justify deliberate divergence.
+---
+
+# Using Coding Standards While Writing
+
+## "Register" / "contribute a snippet" means call put_snippet
+
+Consulting the library is a gloria MCP call, not memory: **`find_snippets`**
+before writing pattern-shaped code. And when the user says **"register"**,
+**"contribute"**, or **"add" this back as a snippet** — or you produce a reusable
+shape worth sharing — that means **calling the gloria MCP tool `put_snippet`**
+(with the user's approval), not just leaving the code in place. The write-time
+loop is: `find_snippets` → adopt/adapt → leave the `gloria:snippet` marker →
+`put_snippet` for genuinely reusable new shapes.
+
+## Overview
+
+A project with a gloria standards library has already decided what its patterns look like.
+This skill is the write-time half of the loop: **consult the library before writing
+pattern-shaped code, copy the canonical exemplar instead of improvising, and leave a marker
+so reuse is verifiable.**
+
+**Core principle: the snippet is the decision, the marker is the receipt.** Adopting the
+canonical snippet keeps the codebase converged; the provenance marker makes that reuse
+greppable, so the checker verifies claimed reuse deterministically instead of guessing.
+
+## When to Use
+
+- About to write something pattern-shaped: a new DAO, statement builder, API route,
+  migration, worker handler, test file, UI list component — any "another one of those"
+- The repo's `CLAUDE.md`/`AGENTS.md` has a `## Coding Standards` section (the
+  `<!-- gloria:standards vN -->` stamp is the tell)
+
+**Don't use for:** genuinely one-off logic with no repeating shape; repos with no registered
+standards (nothing to consult); extracting or checking standards (their own skills).
+
+## Process
+
+### Step 1 — Search before writing
+
+Before writing the first line of a pattern-shaped change:
+
+```
+find_snippets { projectSlug, language, query }
+```
+
+Query with the pattern's name as the repo speaks it ("D1 DAO", "api route zod", "d1
+migration"). The search ladders exact → contains → fuzzy, so a short natural phrase works.
+
+### Step 2 — Decide on the ladder
+
+| Match                                                          | Action                                                                                                                        |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Strong match** — the snippet is the shape you need           | Adopt it. Fill every `TODO:` placeholder. Marker: `(verbatim)`                                                                |
+| **Partial match** — right pattern, needs structural adaptation | Adapt it. Keep the structural skeleton, change what must change, fill every placeholder. Marker: `(adapted)`                  |
+| **No match, but the shape will recur**                         | Write it well, then contribute it back: `put_snippet` with placeholders and linked `ruleIds` (ask the user before publishing) |
+| **No match, genuinely one-off**                                | Write normally. No marker, no contribution                                                                                    |
+
+Never leave a `TODO:` placeholder unfilled in committed code — placeholders are the snippet's
+customization points, and an unfilled one means the adaptation is incomplete.
+
+### Step 3 — Leave the provenance marker
+
+On the adopted/adapted unit (top of the function, class, or file section it produced), in the
+language's comment syntax:
+
+```
+// gloria:snippet <project>/<snippet-id> (verbatim|adapted)
+```
+
+Exact grammar: the literal `gloria:snippet`, one space, the project slug, `/`, the snippet id,
+one space, then `(verbatim)` or `(adapted)`. Examples:
+
+```typescript
+// gloria:snippet gloria-dev/d1-dao (adapted)
+```
+
+```sql
+-- gloria:snippet gloria-dev/d1-migration (verbatim)
+```
+
+`verbatim` means structure copied with only placeholders filled; `adapted` means you changed
+structure beyond the placeholders. When in doubt, `adapted`.
+
+### Step 4 — Justify divergence
+
+If a strong match exists but you deliberately deviate from it, say why in an adjacent comment:
+
+```typescript
+// gloria:snippet gloria-dev/d1-dao (adapted) — diverges: streaming read, so no
+// row-array mapping; see #412
+```
+
+Documented divergence is legitimate for `observed`-authority rules and snippet patterns; the
+checker treats it as intent, not drift. **`enforced` rules have no such escape hatch** — never
+"diverge" from a rule a tool blocks.
+
+## Common Mistakes
+
+| Mistake                                        | Fix                                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------------------- |
+| Writing the pattern from memory, then checking | `find_snippets` first — the snippet may encode decisions you'd re-litigate |
+| Adopting without filling placeholders          | Every `TODO:` filled before the code is done                               |
+| Marker on the wrong granularity                | Mark the unit the snippet produced, not the whole file it lives in         |
+| Claiming `(verbatim)` after structural edits   | Structural change = `(adapted)`; the checker compares faithfulness         |
+| Silent divergence from a strong match          | One comment line saying why; silence reads as unattributed duplication     |
+| Contributing one-off code as a snippet         | Contribute only shapes that will recur; ask the user before `put_snippet`  |
+
+## Quality Checklist
+
+- [ ] `find_snippets` called before writing anything pattern-shaped
+- [ ] Every adopted/adapted snippet carries a correctly-formed `gloria:snippet` marker
+- [ ] Every `TODO:` placeholder filled
+- [ ] Deliberate divergence justified in an adjacent comment
+- [ ] Recurring new shapes offered back via `put_snippet` (with user approval)