npm - @kiwidata/grimoire - Versions diffs - 0.1.1 - Mend

@kiwidata/grimoire 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (215) hide show

package/.claude-plugin/plugin.json +8 -0
package/AGENTS.md +217 -0
package/README.md +748 -0
package/bin/grimoire.js +2 -0
package/dist/cli/index.d.ts +2 -0
package/dist/cli/index.d.ts.map +1 -0
package/dist/cli/index.js +42 -0
package/dist/cli/index.js.map +1 -0
package/dist/commands/archive.d.ts +3 -0
package/dist/commands/archive.d.ts.map +1 -0
package/dist/commands/archive.js +22 -0
package/dist/commands/archive.js.map +1 -0
package/dist/commands/branch-check.d.ts +3 -0
package/dist/commands/branch-check.d.ts.map +1 -0
package/dist/commands/branch-check.js +16 -0
package/dist/commands/branch-check.js.map +1 -0
package/dist/commands/check.d.ts +3 -0
package/dist/commands/check.d.ts.map +1 -0
package/dist/commands/check.js +22 -0
package/dist/commands/check.js.map +1 -0
package/dist/commands/ci.d.ts +3 -0
package/dist/commands/ci.d.ts.map +1 -0
package/dist/commands/ci.js +18 -0
package/dist/commands/ci.js.map +1 -0
package/dist/commands/diff.d.ts +3 -0
package/dist/commands/diff.d.ts.map +1 -0
package/dist/commands/diff.js +10 -0
package/dist/commands/diff.js.map +1 -0
package/dist/commands/docs.d.ts +3 -0
package/dist/commands/docs.d.ts.map +1 -0
package/dist/commands/docs.js +11 -0
package/dist/commands/docs.js.map +1 -0
package/dist/commands/health.d.ts +3 -0
package/dist/commands/health.d.ts.map +1 -0
package/dist/commands/health.js +13 -0
package/dist/commands/health.js.map +1 -0
package/dist/commands/init.d.ts +3 -0
package/dist/commands/init.d.ts.map +1 -0
package/dist/commands/init.js +21 -0
package/dist/commands/init.js.map +1 -0
package/dist/commands/list.d.ts +3 -0
package/dist/commands/list.d.ts.map +1 -0
package/dist/commands/list.js +22 -0
package/dist/commands/list.js.map +1 -0
package/dist/commands/log.d.ts +3 -0
package/dist/commands/log.d.ts.map +1 -0
package/dist/commands/log.js +15 -0
package/dist/commands/log.js.map +1 -0
package/dist/commands/map.d.ts +3 -0
package/dist/commands/map.d.ts.map +1 -0
package/dist/commands/map.js +17 -0
package/dist/commands/map.js.map +1 -0
package/dist/commands/pr.d.ts +3 -0
package/dist/commands/pr.d.ts.map +1 -0
package/dist/commands/pr.js +17 -0
package/dist/commands/pr.js.map +1 -0
package/dist/commands/status.d.ts +3 -0
package/dist/commands/status.d.ts.map +1 -0
package/dist/commands/status.js +12 -0
package/dist/commands/status.js.map +1 -0
package/dist/commands/test-quality.d.ts +3 -0
package/dist/commands/test-quality.d.ts.map +1 -0
package/dist/commands/test-quality.js +37 -0
package/dist/commands/test-quality.js.map +1 -0
package/dist/commands/trace.d.ts +3 -0
package/dist/commands/trace.d.ts.map +1 -0
package/dist/commands/trace.js +12 -0
package/dist/commands/trace.js.map +1 -0
package/dist/commands/update.d.ts +3 -0
package/dist/commands/update.d.ts.map +1 -0
package/dist/commands/update.js +22 -0
package/dist/commands/update.js.map +1 -0
package/dist/commands/validate.d.ts +3 -0
package/dist/commands/validate.d.ts.map +1 -0
package/dist/commands/validate.js +17 -0
package/dist/commands/validate.js.map +1 -0
package/dist/core/archive.d.ts +9 -0
package/dist/core/archive.d.ts.map +1 -0
package/dist/core/archive.js +92 -0
package/dist/core/archive.js.map +1 -0
package/dist/core/branch-check.d.ts +27 -0
package/dist/core/branch-check.d.ts.map +1 -0
package/dist/core/branch-check.js +205 -0
package/dist/core/branch-check.js.map +1 -0
package/dist/core/check.d.ts +24 -0
package/dist/core/check.d.ts.map +1 -0
package/dist/core/check.js +372 -0
package/dist/core/check.js.map +1 -0
package/dist/core/ci.d.ts +24 -0
package/dist/core/ci.d.ts.map +1 -0
package/dist/core/ci.js +162 -0
package/dist/core/ci.js.map +1 -0
package/dist/core/detect.d.ts +10 -0
package/dist/core/detect.d.ts.map +1 -0
package/dist/core/detect.js +368 -0
package/dist/core/detect.js.map +1 -0
package/dist/core/diff.d.ts +29 -0
package/dist/core/diff.d.ts.map +1 -0
package/dist/core/diff.js +197 -0
package/dist/core/diff.js.map +1 -0
package/dist/core/doc-style.d.ts +16 -0
package/dist/core/doc-style.d.ts.map +1 -0
package/dist/core/doc-style.js +192 -0
package/dist/core/doc-style.js.map +1 -0
package/dist/core/docs.d.ts +6 -0
package/dist/core/docs.d.ts.map +1 -0
package/dist/core/docs.js +478 -0
package/dist/core/docs.js.map +1 -0
package/dist/core/health.d.ts +7 -0
package/dist/core/health.d.ts.map +1 -0
package/dist/core/health.js +489 -0
package/dist/core/health.js.map +1 -0
package/dist/core/hooks.d.ts +5 -0
package/dist/core/hooks.d.ts.map +1 -0
package/dist/core/hooks.js +168 -0
package/dist/core/hooks.js.map +1 -0
package/dist/core/init.d.ts +9 -0
package/dist/core/init.d.ts.map +1 -0
package/dist/core/init.js +563 -0
package/dist/core/init.js.map +1 -0
package/dist/core/list.d.ts +4 -0
package/dist/core/list.d.ts.map +1 -0
package/dist/core/list.js +170 -0
package/dist/core/list.js.map +1 -0
package/dist/core/log.d.ts +8 -0
package/dist/core/log.d.ts.map +1 -0
package/dist/core/log.js +150 -0
package/dist/core/log.js.map +1 -0
package/dist/core/map.d.ts +9 -0
package/dist/core/map.d.ts.map +1 -0
package/dist/core/map.js +302 -0
package/dist/core/map.js.map +1 -0
package/dist/core/pr.d.ts +9 -0
package/dist/core/pr.d.ts.map +1 -0
package/dist/core/pr.js +273 -0
package/dist/core/pr.js.map +1 -0
package/dist/core/shared-setup.d.ts +52 -0
package/dist/core/shared-setup.d.ts.map +1 -0
package/dist/core/shared-setup.js +221 -0
package/dist/core/shared-setup.js.map +1 -0
package/dist/core/status.d.ts +6 -0
package/dist/core/status.d.ts.map +1 -0
package/dist/core/status.js +114 -0
package/dist/core/status.js.map +1 -0
package/dist/core/test-quality.d.ts +33 -0
package/dist/core/test-quality.d.ts.map +1 -0
package/dist/core/test-quality.js +378 -0
package/dist/core/test-quality.js.map +1 -0
package/dist/core/trace.d.ts +6 -0
package/dist/core/trace.d.ts.map +1 -0
package/dist/core/trace.js +211 -0
package/dist/core/trace.js.map +1 -0
package/dist/core/update.d.ts +10 -0
package/dist/core/update.d.ts.map +1 -0
package/dist/core/update.js +149 -0
package/dist/core/update.js.map +1 -0
package/dist/core/validate.d.ts +20 -0
package/dist/core/validate.d.ts.map +1 -0
package/dist/core/validate.js +275 -0
package/dist/core/validate.js.map +1 -0
package/dist/index.d.ts +19 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +20 -0
package/dist/index.js.map +1 -0
package/dist/utils/config.d.ts +61 -0
package/dist/utils/config.d.ts.map +1 -0
package/dist/utils/config.js +172 -0
package/dist/utils/config.js.map +1 -0
package/dist/utils/fs.d.ts +17 -0
package/dist/utils/fs.d.ts.map +1 -0
package/dist/utils/fs.js +38 -0
package/dist/utils/fs.js.map +1 -0
package/dist/utils/paths.d.ts +10 -0
package/dist/utils/paths.d.ts.map +1 -0
package/dist/utils/paths.js +35 -0
package/dist/utils/paths.js.map +1 -0
package/dist/utils/spawn.d.ts +5 -0
package/dist/utils/spawn.d.ts.map +1 -0
package/dist/utils/spawn.js +34 -0
package/dist/utils/spawn.js.map +1 -0
package/package.json +68 -0
package/skills/grimoire-apply/SKILL.md +274 -0
package/skills/grimoire-audit/SKILL.md +129 -0
package/skills/grimoire-branch-guard/SKILL.md +111 -0
package/skills/grimoire-bug/SKILL.md +160 -0
package/skills/grimoire-bug-explore/SKILL.md +242 -0
package/skills/grimoire-bug-report/SKILL.md +237 -0
package/skills/grimoire-bug-session/SKILL.md +222 -0
package/skills/grimoire-bug-triage/SKILL.md +274 -0
package/skills/grimoire-commit/SKILL.md +150 -0
package/skills/grimoire-discover/SKILL.md +297 -0
package/skills/grimoire-draft/SKILL.md +202 -0
package/skills/grimoire-plan/SKILL.md +329 -0
package/skills/grimoire-pr/SKILL.md +134 -0
package/skills/grimoire-pr-review/SKILL.md +240 -0
package/skills/grimoire-refactor/SKILL.md +251 -0
package/skills/grimoire-remove/SKILL.md +112 -0
package/skills/grimoire-review/SKILL.md +247 -0
package/skills/grimoire-verify/SKILL.md +223 -0
package/skills/references/bug-classification.md +154 -0
package/skills/references/build-vs-buy.md +77 -0
package/skills/references/elicitation-personas.md +118 -0
package/skills/references/refactor-register-format.md +88 -0
package/skills/references/refactor-scan-categories.md +102 -0
package/skills/references/schema-format.md +68 -0
package/skills/references/security-compliance.md +110 -0
package/skills/references/testing-contracts.md +93 -0
package/templates/context.yml +110 -0
package/templates/debt-exceptions.yml +61 -0
package/templates/decision.md +50 -0
package/templates/dupignore +93 -0
package/templates/example.feature +24 -0
package/templates/manifest.md +29 -0
package/templates/mapignore +58 -0
package/templates/mapkeys +65 -0

package/skills/grimoire-pr-review/SKILL.md ADDED Viewed

@@ -0,0 +1,240 @@
+---
+name: grimoire-pr-review
+description: Review a teammate's pull request using the same multi-persona lens as pre-commit review, but against the actual diff. Fetches the PR, loads linked grimoire artifacts via the Change trailer, and produces structured findings suitable for PR comments.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+# grimoire-pr-review
+Review a pull request authored by someone else. Applies the same persona lens as `grimoire-review` (product, engineer, security, QA, data) to the real diff, cross-referenced with the PR's linked grimoire change (if any).
+## Triggers
+- User asks to review a teammate's PR / MR
+- User supplies a PR number, URL, or branch and asks for review
+- Loose match: "review this PR", "look at PR #123", "review <url>", "review teammate's branch", "code review"
+## Routing
+- Reviewing your own pre-merge change you just built → `grimoire-pr` (has optional post-impl review)
+- Reviewing a design before any code exists → `grimoire-review`
+- Verifying scenarios pass after merge → `grimoire-verify`
+- Writing a bug report against merged behavior → `grimoire-bug-report`
+## Prerequisites
+- `gh` (GitHub) or `glab` (GitLab) CLI installed and authenticated, OR the PR's branch fetched locally
+- Working directory is the repo the PR targets
+- Optional: `.grimoire/` directory with baseline features/decisions for linked-change context
+## Inputs
+Accept any of:
+- PR number: `123`
+- PR URL: `https://github.com/org/repo/pull/123`
+- Branch name: `feat/add-2fa-login`
+- Base/head refs: `main...feat/add-2fa-login`
+If nothing supplied, ask the user for one.
+## Workflow
+### 1. Fetch PR Metadata
+Resolve the input to concrete refs.
+- GitHub: `gh pr view <id> --json number,title,body,author,baseRefName,headRefName,files,commits,url`
+- GitLab: `glab mr view <id> --output json`
+- Branch only: derive base from default branch (`git remote show origin | grep 'HEAD branch'`) and head = supplied branch
+Record: PR title, body, author, base branch, head branch, URL, file list, commit count.
+### 2. Fetch the Diff
+- GitHub: `gh pr diff <id>` (or `git fetch origin pull/<id>/head && git diff <base>...FETCH_HEAD`)
+- GitLab: `glab mr diff <id>`
+- Branch: `git fetch origin <head> && git diff origin/<base>...origin/<head>`
+If the diff is very large (>2000 lines changed), ask the user whether to review the full diff, focus on a subset of files, or review commit-by-commit.
+### 3. Find Linked Grimoire Change
+Look for a `Change:` trailer in the PR commits:
+```
+git log <base>..<head> --format="%B" | grep -E "^Change:"
+```
+If present:
+- Change ID = trailer value
+- Load artifacts: first check `.grimoire/changes/<change-id>/` (in-progress), then `.grimoire/archive/*<change-id>*/` (archived). Try the PR's head branch checked out locally if needed.
+- Read `manifest.md`, all `.feature` files in the change, decision records, `tasks.md`, `data.yml`
+- Also grep for `Scenarios:` and `Decisions:` trailers to scope review to the named items
+If no `Change:` trailer exists, that's itself a finding for a grimoire-managed repo: flag as **suggestion** ("commits missing audit trailer — `grimoire trace` won't find this PR") unless the project clearly doesn't use grimoire.
+### 4. Gather Project Context
+- `.grimoire/config.yaml` — language, tools, `commit_style`, `project.compliance`, `dep_audit`
+- `.grimoire/docs/context.yml` — deployment environment, related services
+- `.grimoire/docs/data/schema.yml` — current data baseline
+- Relevant `.grimoire/docs/<area>.md` for the directories touched by the diff
+### 5. Complexity-Gated Depth
+Read `complexity` from the linked manifest frontmatter if available. Fall back to heuristics on the diff:
+| Signal | Depth |
+|---|---|
+| Docs only, ≤50 lines | Senior engineer skim only |
+| Linked manifest complexity 1-2, diff <200 lines, no security tags | Senior engineer + security quick scan |
+| Linked manifest complexity 3, OR diff touches auth/data/API | All relevant personas (skip data if no schema change, skip QA if no user-facing change) |
+| Linked manifest complexity 4, OR diff >500 lines, OR touches multiple domains | All personas mandatory |
+User can override: "full review", "just security", "just engineer", etc.
+### 6. Product Manager Review
+*(Skip if PR is pure internal refactor with no user-facing change.)*
+Evaluate against the linked feature files (if any) or the PR body:
+- **Scenario coverage**: If a feature file exists in the change, does the diff implement every scenario? Any scenario with no matching code change?
+- **Non-goals**: Does the diff touch anything the manifest's Non-goals section excludes?
+- **Acceptance**: From the diff alone, could a PM validate this meets the feature's acceptance criteria?
+- **Clarity**: Does the PR body (or linked manifest) make the user-visible outcome clear?
+Flag as **blocker** or **suggestion**.
+### 7. Senior Engineer Review
+Review the actual code:
+- **Simplicity**: Is this the simplest implementation? Any unnecessary abstraction, indirection, or config that could be inlined?
+- **Conventions**: Does the new code match the file layout, naming, and patterns already in the touched areas? Check `.grimoire/docs/<area>.md` if present.
+- **Reuse**: Are there existing utilities/functions that were re-implemented? `grep` for similar names or check the area doc's reusable-code list.
+- **Dead code**: Functions added but not called, imports unused, commented-out code, stubs with no implementation.
+- **Scope creep**: Files changed outside the scope implied by the change-id or manifest. Formatting-only changes to unrelated files = noise.
+- **Error handling**: Are errors handled at boundaries? Internal code shouldn't be littered with defensive checks; external inputs must be validated.
+- **Tests**: Do new behaviors have tests? Do the tests make real assertions (not just `assert true` / mock everything)? Check `../references/testing-contracts.md` if the framework matches.
+- **Contract compatibility**: If `data.yml` / `schema.yml` exists, does the diff change request/response shape for a documented API? If yes, where's the contract test update?
+- **Dependencies**: Any new packages in `package.json` / `requirements.txt` / `Cargo.toml` etc. not mentioned in tasks? Any version bumps that aren't noted?
+- **Task alignment**: If `tasks.md` exists for the change, does the diff complete the tasks as written? Any task that was "done" but has no corresponding code?
+Flag as **blocker** or **suggestion**.
+### 8. Security Engineer Review
+Apply `../references/security-compliance.md`.
+#### 8a. STRIDE on the diff
+For every new entry point, data flow, or trust boundary introduced by the diff:
+| Threat | Question |
+|---|---|
+| **S**poofing | Auth check at every new route/handler? |
+| **T**ampering | Input/message integrity validated? CSRF on state-changing requests? |
+| **R**epudiation | Security-relevant actions logged? |
+| **I**nfo disclosure | Error responses, logs, stack traces leaking PII/tokens/secrets? |
+| **D**oS | Unbounded loops, unlimited file uploads, expensive queries on user input, no rate limit? |
+| **E**oP | Role/permission checks at the right layer? Any bypass via missing middleware? |
+Skip categories that don't apply.
+#### 8b. Code-level scan
+- **Secrets**: Grep the diff for hardcoded keys, tokens, passwords, cloud credentials, JWT secrets. Flag any hit as **blocker**.
+- **Injection**: Raw SQL with string concatenation, shell-exec with user input, `eval`/`exec`, unsafe deserialization. Tag with OWASP + CWE.
+- **Input validation**: New endpoints without schema validation, file uploads without size/type limits, path params used directly in filesystem calls (path traversal).
+- **Auth**: New routes/handlers missing auth decorators / middleware. Compare against neighbors in the same file.
+- **Dependencies**: New packages in lockfile — check the name is real (typosquat risk), check project's `dep_audit` tool output if committed. Flag packages with zero downloads or suspicious maintainers.
+- **PII**: New logging statements that could emit PII; new storage of personal data without encryption.
+- **Cross-service auth**: If `context.yml` lists related services, are service-to-service calls authenticated?
+#### 8c. Compliance
+If `project.compliance` configured, verify per `../references/security-compliance.md` section "Compliance Framework Verification". Any security-tagged scenario in the linked change with no corresponding verification in the diff = **blocker**.
+#### 8d. Tag findings
+Every security finding gets OWASP 2021 + CWE tags. See the CWE quick-reference in `../references/security-compliance.md`.
+### 9. QA Engineer Review (optional)
+Skip if PR is purely internal.
+- **Test presence**: Every new user-facing behavior has a test? Every scenario from the linked feature file has step definitions?
+- **Test quality**: Are tests asserting outputs, or just that code "ran"? Over-mocked tests are a red flag.
+- **Negative paths**: For each happy path in the diff, is there a failure-path test?
+- **Observability**: New feature — how will it be debugged in prod? Structured logs / metrics / error surfaces?
+- **Regression risk**: Which existing tests cover the touched code? Were any tests removed or weakened in the diff?
+- **Accessibility**: New UI — keyboard nav, aria labels, contrast?
+### 10. Data Engineer Review (optional)
+Skip unless diff touches migrations, models, schema files, or external API clients.
+- **Migrations**: Safe to run on a live DB? Adding a NOT NULL without default on a large table = **blocker**. Renames without a two-step migration = **blocker**.
+- **Indexes**: New foreign keys with no index? New query patterns against unindexed columns?
+- **Naming**: New fields follow existing schema conventions?
+- **Breaking contract**: Compare `data.yml` vs `schema.yml` — removed/renamed/retyped response fields or new required request fields = **blocker** unless a migration path is documented.
+- **Transactions**: Multi-step writes wrapped in a transaction?
+### 11. Present Findings
+Compile into a single report structured for PR comments:
+```markdown
+# PR Review: <PR title> (#<number>)
+**Author:** <author>  **Base:** <base>  **Head:** <head>
+**Linked change:** <change-id or "none — missing Change: trailer">
+**Complexity:** <1-4 or "inferred: moderate">
+**Files changed:** <N>  **Lines:** +<add> / -<del>
+## Product Manager
+- **[blocker]** Scenario "Login with expired TOTP code" is in the feature file but no corresponding code path in `auth/verify.py`
+- **[suggestion]** PR body doesn't mention the rate-limit change — add it
+## Senior Engineer
+- **[blocker]** `utils/hash_helpers.py` duplicates `security/crypto.py::hash_password` — reuse instead
+- **[suggestion]** New abstraction `AuthProviderFactory` has one caller; inline it
+## Security Engineer
+### STRIDE
+- Spoofing: N/A
+- Tampering: new `/api/profile` PATCH has no CSRF token check
+- Info disclosure: `logger.info(f"login attempt for {email}")` emits PII
+### Findings
+- **[blocker]** [A01:2021 / CWE-352] Missing CSRF check on `/api/profile` PATCH (`views/profile.py:42`)
+- **[blocker]** [A09:2021 / CWE-532] Email logged in plaintext (`auth/login.py:88`)
+- **[suggestion]** [A07:2021 / CWE-307] No rate limiting on login handler
+## QA Engineer
+- **[blocker]** New TOTP verification path has no test (`auth/totp.py:15-48`)
+- **[suggestion]** Add negative test for malformed TOTP string
+## Data Engineer
+- **[blocker]** Migration `0042_add_2fa.py` adds NOT NULL `totp_secret` on existing `users` table — will fail on deploy
+(or: "No schema changes — skipped.")
+## Summary
+- **5 blockers** — must be addressed before merge
+- **3 suggestions** — consider addressing
+Recommendation: Request changes.
+```
+### 12. Post to PR (optional)
+Offer three modes:
+- **Print only** (default) — just show the report
+- **Post single review comment**:
+  - GitHub: `gh pr review <id> --comment --body "<report>"` or `--request-changes` if there are blockers
+  - GitLab: `glab mr note <id> --message "<report>"`
+- **Post inline comments** — for each finding with a file:line, post a line comment:
+  - GitHub: `gh api repos/<org>/<repo>/pulls/<id>/comments -f body=... -f path=... -f line=... -f commit_id=...`
+  - This requires the commit SHA — get it from `gh pr view --json commits`
+Ask the user which mode before posting. Never post without confirmation — PR comments are visible to the whole team.
+### 13. Link Back
+If a linked grimoire change was found and the review surfaced blockers that need spec changes (not just code changes), suggest the author run `grimoire-draft` or `grimoire-plan` on that change to update the artifacts before pushing fixes.
+## Important
+- This is a code review against a real diff — reference specific files and line numbers for every finding.
+- Be direct. Don't pad with praise. Blockers are things that should stop the merge; suggestions are things the author should consider.
+- Respect the author. Findings describe the code, not the person. "This query is vulnerable to injection" not "you wrote an injection".
+- A PR without a `Change:` trailer in a grimoire repo is a soft finding, not a hard blocker — the team may have reasons.
+- Don't re-derive tasks or specs. If the linked change's artifacts are wrong, that's a separate `grimoire-draft` / `grimoire-plan` cycle.
+- If the diff is too large or too sprawling to review meaningfully, say so — offer to focus on a subset rather than producing a shallow full-pass review.
+- Never post to the PR without explicit user confirmation.
+## Done
+When the report is presented (and optionally posted), the workflow is complete. If blockers exist, suggest the author address them; if not, suggest approving via `gh pr review <id> --approve`.

package/skills/grimoire-refactor/SKILL.md ADDED Viewed

@@ -0,0 +1,251 @@
+---
+name: grimoire-refactor
+description: Systematically find, prioritize, and plan tech debt reduction. Use when the user wants to identify and address code quality issues, complexity, or duplication.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+# grimoire-refactor
+Systematically find, prioritize, and plan tech debt reduction. Combines automated scanning with LLM analysis to produce a prioritized debt register, then feeds approved items into the standard grimoire pipeline (draft → plan → apply).
+## Triggers
+- User asks about tech debt, code quality, refactoring opportunities, or simplification
+- User wants to reduce complexity, lines of code, or structural bloat
+- User asks "what should we clean up?" or "where's the tech debt?"
+- Loose match: "refactor", "tech debt", "simplify", "clean up", "reduce complexity", "code smells"
+## Routing
+- Behavior change needed (not just code quality) → `grimoire-draft`
+- Removing a feature → `grimoire-remove`
+- Fixing a bug → `grimoire-bug`
+- Documenting existing code → `grimoire-discover`
+## Prerequisites
+- A grimoire-initialized project (`.grimoire/` exists)
+- Git history available (hotspot analysis needs `git log`)
+- Ideally: `grimoire map` + `/grimoire:discover` already run (area docs help contextualize findings)
+## Debt Item Format
+Each debt item in the register follows a structured format influenced by the CodeClimate issue spec (categories, severity, remediation effort, fingerprint) and the SEI/CMU Technical Debt Item classification (consequences, causes, evidence of accumulation).
+**Required fields:**
+- `id` — unique identifier (debt-NNN, monotonically increasing)
+- `category` — one of: `hotspot`, `structural_bloat`, `data_structure`, `circular_dependency`, `dependency_staleness`, `broken_promise`, `duplication`, `dead_code`, `test_debt`
+- `severity` — `high`, `medium`, or `low`
+- `location` — file path (with optional `:line`), or `path ↔ path` for relationships
+- `title` — short human-readable summary
+- `detail` — evidence: what was measured, what threshold was exceeded, what the consequences are
+- `fingerprint` — stable hash of category + location for dedup across scans (so re-scans update existing items rather than creating duplicates)
+- `status` — `open` | `triaged` | `in-progress` | `resolved` | `accepted`
+**Optional fields:**
+- `metrics` — numeric measurements (churn count, complexity score, line count, field count, age in days, etc.)
+- `suggestion` — recommended refactoring approach
+- `effort` — `small` (<1 hour), `medium` (1-4 hours), `large` (>4 hours)
+- `consequences` — what happens if this debt is NOT addressed (SEI/CMU field — forces articulation of impact)
+- `causes` — how this debt was introduced: `evolution` (grew over time), `deadline` (time pressure), `knowledge` (didn't know better), `dependency` (forced by external constraint)
+- `quadrant` — Fowler's classification: `deliberate-prudent`, `deliberate-reckless`, `inadvertent-prudent`, `inadvertent-reckless`
+- `change_id` — grimoire change created to address this item
+- `first_detected` — date the scanner first found this item (set once, never updated)
+- `last_detected` — date of most recent scan that confirmed this item still exists
+## Debt Exceptions
+The scanner respects `.grimoire/debt-exceptions.yml` — a file where the team explicitly accepts known debt. This is modeled on `.snyk`/`.trivyignore` policy files: accept specific items with a reason, an owner, and an optional expiry date.
+**Exception matching (checked before any item is added to the register):**
+1. **By item ID** — matches a specific debt register entry:
+   ```yaml
+   - id: debt-003
+     reason: "Splitting config types would break the plugin API."
+     quadrant: deliberate-prudent
+     owner: fred
+     accepted: 2026-04-06
+     expires: 2026-10-01
+   ```
+2. **By pattern + category** — matches any finding in files matching the glob:
+   ```yaml
+   - pattern: "src/vendor/**"
+     category: "*"              # or a specific category
+     reason: "Vendored code — we don't own it"
+     quadrant: deliberate-prudent
+     owner: fred
+     accepted: 2026-04-06
+   ```
+**Exception rules:**
+- Every exception MUST have `reason`, `quadrant`, `owner`, and `accepted` fields. Exceptions without a reason are rejected — the point is to force articulation of the trade-off.
+- `expires` is optional. If set, the scanner re-flags the item after the expiry date and notes it as "exception expired" in the register.
+- `quadrant` uses Fowler's Technical Debt Quadrant to classify the *intent* behind accepting the debt. This isn't just documentation — it helps the team spot patterns (too many `deliberate-reckless` exceptions = systemic problem).
+- When the scanner finds a matching exception, the item is still recorded in the register but with `status: accepted` and a reference to the exception. This means the debt is visible and tracked, just not flagged for action.
+- Expired exceptions cause the item's status to revert to `open` with a note: `"Exception expired YYYY-MM-DD — re-evaluate"`.
+- When a user marks an item as "accept" during the triage flow (step 4), the skill writes the exception to `debt-exceptions.yml` automatically — the user provides the reason, quadrant, and optional expiry interactively.
+**Scanner behavior:** For each finding, compute fingerprint → check exceptions (by id, then pattern+category) → check if expired → check existing register by fingerprint → add/update item.
+## Workflow
+### 1. Determine Scope
+Ask the user what to scan:
+- **Full scan** — all categories across the whole codebase (default for first run)
+- **Category scan** — specific debt category (e.g., "just hotspots" or "just structural bloat")
+- **Area scan** — specific directory or module (e.g., "just the API layer")
+- **Refresh** — re-scan and update an existing debt register
+Check if `.grimoire/docs/debt-register.yml` already exists — don't redo work unless refreshing.
+### 2. Run Scans
+Run applicable scans in parallel. Each scan produces a list of findings with a category, location, severity, and suggested action.
+Run applicable scans from the categories in `../references/refactor-scan-categories.md`. Each category has specific signals, thresholds, severity levels, and scan commands referencing `config.tools.*` entries.
+**Key categories** (details in reference):
+- **Hotspots** (churn x complexity) — highest ROI, uses `git log` + `config.tools.complexity`
+- **Structural bloat** — oversized files/functions/classes
+- **Data structure complexity** — over-engineered models, deep nesting
+- **Circular dependencies** — tight coupling between modules
+- **Dependency staleness** — uses `config.tools.dep_audit` or package manager outdated commands
+- **Broken promises** — aged TODO/FIXME/HACK comments via `grep` + `git blame`
+- **Duplication** — uses `.snapshot.json` duplicates or `config.tools.duplicates`
+- **Dead code** — uses `config.tools.dead_code` or `codebase-memory-mcp` graph queries
+- **Test debt** — high complexity + low coverage
+### 3. Load Exceptions
+Before generating the register, read `.grimoire/debt-exceptions.yml`. Parse all exceptions and build a lookup:
+- Index by `id` for direct item matches
+- Index by `pattern` + `category` for glob matches
+- Check `expires` dates — any exception past its expiry date is treated as not matching (the item will be flagged as `open` with a note)
+If the exceptions file doesn't exist, proceed with no exceptions (all findings are flagged).
+### 4. Generate Debt Register
+Produce `.grimoire/docs/debt-register.yml`. This is the persistent record of known debt, what's been triaged, and what's been addressed.
+For each finding from the scans:
+1. Compute a fingerprint: `sha256(category + normalized_location)` — this is the stable identifier for dedup across scans
+2. Check against exceptions (by id, then by pattern+category)
+3. Check against existing register (by fingerprint) — preserve status and metadata for known items
+4. Add or update the item in the register
+See `../references/refactor-register-format.md` for the full field specification and example items.
+**Register rules:**
+- Each item has a unique `id` (debt-NNN, monotonically increasing) and a stable `fingerprint` for dedup
+- `status` tracks lifecycle: `open` → `triaged` → `in-progress` → `resolved` (or `accepted` via exception)
+- `first_detected` and `last_detected` track how long debt has been known — debt that persists across many scans is aging and may need escalation
+- Items matched by an exception get `status: accepted` with `quadrant` and `exception_reason` copied from the exception file
+- Items whose exception has expired revert to `status: open` with a note in `detail`: "Exception expired YYYY-MM-DD — re-evaluate"
+- `consequences` should articulate what happens if this debt is NOT addressed — this forces the scanner (and the user) to think about real impact, not just code aesthetics
+- `causes` classifies how the debt was introduced: `evolution` (grew incrementally), `deadline` (time pressure), `knowledge` (didn't know better at the time), `dependency` (forced by external constraint)
+- `change_id` links to the grimoire change created to address it (populated when the user approves a refactoring)
+- `effort` is a rough estimate: `small` (<1 hour), `medium` (1-4 hours), `large` (>4 hours / multiple sessions)
+- On refresh: match by fingerprint, preserve status and first_detected for known items, update last_detected and metrics, add new items, mark items no longer detected as `resolved` automatically
+- Sort by severity (high first), then by hotspot score within severity
+### 5. Prioritize and Present
+Present findings to the user grouped by severity, with recommended action order. Only show items with `status: open` — accepted items are tracked but not flagged.
+**Prioritization heuristic (automated):**
+1. **High-severity hotspots first** — highest ROI, every future change benefits
+2. **High-severity structural bloat** — simplification unlocks everything else
+3. **High-severity data structure complexity** — foundational, affects many layers
+4. **Circular dependencies** — blocks clean architecture
+5. **Everything else by severity**
+**Present in batches** (same pattern as grimoire-audit — don't dump):
+- Show top 5 items first with their category, location, suggestion, and consequences
+- For each item, ask the user to choose one of:
+  - **fix** — create a grimoire change to address it (status → `in-progress`)
+  - **defer** — acknowledge but not now (status → `triaged`, revisit next scan)
+  - **accept** — the cost of fixing exceeds the benefit (status → `accepted`)
+**When the user chooses "accept"**, collect exception details interactively:
+1. Ask for a **reason** (required) — why is this debt acceptable? What's the trade-off?
+2. Ask for the **Fowler quadrant** (required) — present the four options:
+   - `deliberate-prudent`: "We know, and it's the right trade-off for now"
+   - `deliberate-reckless`: "We know, and we're cutting corners"
+   - `inadvertent-prudent`: "We didn't know then, and fixing isn't worth it now"
+   - `inadvertent-reckless`: "We didn't know, and the cost to fix is too high right now"
+3. Ask for an **expiry date** (optional) — when should this be re-evaluated? If set, the scanner re-flags after this date.
+4. Write the exception to `.grimoire/debt-exceptions.yml` automatically
+5. Update the register item: `status: accepted`, `quadrant`, `exception_reason`
+**If the user chooses "accept" with quadrant `deliberate-reckless`**, flag it gently: "Noted. Just a heads-up — too many deliberate-reckless exceptions may indicate systemic time pressure. You might want to discuss capacity with the team." Don't block, just inform.
+After the first batch, ask if the user wants to see more or start working on the approved items.
+**Present a summary of existing exceptions** if any exist:
+- "You have 5 accepted items in debt-exceptions.yml. 1 expires next month."
+- This keeps the team aware of debt they've acknowledged but not resolved.
+**When presenting, frame simplification opportunities concretely:**
+- "This 847-line file could become 3 files of ~250 lines each"
+- "This 34-method class has 5 distinct responsibilities — extracting them would make each class testable independently"
+- "This 28-field config type is used in 3 contexts — splitting it eliminates 22 optional fields and makes each usage self-documenting"
+- "Flattening this 4-level nested structure into 2 normalized types would eliminate the deep property chains throughout the codebase"
+### 6. Create Grimoire Changes
+For each item the user approves to fix:
+1. Create a grimoire change: `refactor-<debt-id>` (e.g., `refactor-debt-001`)
+2. Update the debt register item: set `status: in-progress`, set `change_id`
+3. Draft the change using the standard grimoire format:
+   - **Manifest** with the refactoring rationale (what the debt is, why it matters, what "done" looks like)
+   - **Feature files** if the refactoring changes behavior boundaries (rare for pure refactors, but splitting a module may change its public API)
+   - **Decision record** if the refactoring involves an architectural choice (e.g., "extract event system to decouple orders and inventory")
+4. Hand off to `/grimoire:plan` for task generation, then `/grimoire:apply` for implementation
+**Refactoring-specific guidance for the plan/apply stages:**
+- **All existing tests must keep passing.** A refactoring that breaks tests is not a refactoring.
+- **Prefer incremental moves over big-bang rewrites.** Move one function at a time, run tests after each move.
+- **Add tests before refactoring if test debt is part of the item.** You need a safety net before restructuring.
+- **Update imports incrementally.** When moving code to a new module, re-export from the old location first, then update consumers, then remove the re-export.
+- **Update area docs after refactoring.** File paths and reusable code locations will have changed.
+### 7. Track Progress
+After refactoring is complete (grimoire apply finishes):
+1. Update the debt register item: set `status: resolved`
+2. Update metrics if a re-scan shows improvement
+3. Present a before/after summary:
+   - Lines of code: before → after
+   - Complexity: before → after
+   - Number of files/classes/functions: before → after
+   - Test coverage: before → after (if measurable)
+### 8. Ongoing Maintenance
+The debt register is a living document. Recommend:
+- **Monthly re-scan** to catch new debt and verify resolved items stay resolved
+- **Per-sprint planning** — pick 1-2 high-severity items each sprint alongside feature work
+- **Gate new debt** — the existing grimoire check pipeline (complexity, duplication, best practices) catches debt at commit time. The refactor skill handles accumulated debt.
+## Integration with Other Skills
+- **grimoire-health** — the health score reflects some debt dimensions (coverage, complexity, duplicates). Refactoring should improve health scores.
+- **grimoire-audit** — audit finds undocumented features/decisions. Refactor finds code quality issues. They're complementary — run audit first to understand what the code does, then refactor to improve how it does it.
+- **grimoire-discover** — area docs provide context for refactoring. After refactoring, run discover to update docs.
+- **grimoire-review** — the senior engineer persona already checks for simplicity and reuse. Refactor findings can inform review criteria.
+- **grimoire-check** — the commit-time checks prevent new debt. Refactor addresses existing debt.
+## Important
+- **Don't boil the ocean.** Tech debt reduction is incremental. Pick the highest-impact items and make measurable progress. A codebase with zero debt is not the goal — a codebase where debt doesn't slow you down is.
+- **Respect wont-fix.** Some debt is cheaper to live with than to fix. A 500-line file that changes once a year is not worth splitting. Acknowledge this and move on.
+- **Simplification is the primary goal.** Every refactoring should make the codebase smaller, simpler, or more focused. If a refactoring adds complexity (more files, more abstractions, more indirection) without reducing something else, question whether it's actually an improvement.
+- **Measure before and after.** A refactoring without measurable improvement is just code churn. Track lines, complexity, coverage, and file count.
+- **Existing tests are your safety net.** Never refactor without tests. If tests don't exist, write them first (that's test debt — address it before or alongside the structural refactoring).
+- **Present findings collaboratively** — same interview pattern as grimoire-audit. Batches of 3-5, let the user drive priority. Don't dump a 50-item list.
+## Done
+When debt items are triaged (fixed, deferred, or accepted) and grimoire changes are created for approved fixes, the workflow is complete. Each approved fix flows through the standard pipeline: `grimoire-plan` → `grimoire-apply`.

package/skills/grimoire-remove/SKILL.md ADDED Viewed

@@ -0,0 +1,112 @@
+---
+name: grimoire-remove
+description: Remove a feature or deprecate a decision through a tracked, deliberate change. Use when the user wants to decommission functionality with full impact assessment.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+# grimoire-remove
+Remove a feature or deprecate a decision through a tracked, deliberate change.
+## Triggers
+- User wants to remove, deprecate, or sunset a feature
+- User wants to supersede or retire an architecture decision
+- Loose match: "remove", "delete", "deprecate", "sunset", "retire" with feature/decision reference
+## Routing
+- Feature was never documented → `grimoire-audit` first to establish baseline
+- Want to change behavior (not remove it) → `grimoire-draft`
+- Want to clean up code quality → `grimoire-refactor`
+## Workflow
+### 1. Identify What's Being Removed
+- Ask the user what they want to remove and why
+- Read the existing `.feature` file(s) or ADR(s) being targeted
+- Confirm scope: removing an entire feature? Specific scenarios? A decision?
+### 2. Assess Impact
+Before creating the change:
+- **Search the codebase** for code implementing the feature/decision
+- **Check other features** — does anything depend on the behavior being removed?
+- **Check decisions** — does removing this feature invalidate any ADRs?
+- **Check step definitions** — what test code will need to be removed?
+Present the impact summary to the user:
+> "Removing the document overview tab will affect: `document_review/views.py`, `templates/review/overview.html`, 3 step definitions in `test_document_review.py`, and the 'Document Overview Tab' requirement in `features/documents/review.feature`. The 'Error Detail Modal' feature in the same file is independent and won't be affected."
+### 3. Create Removal Change
+Scaffold `.grimoire/changes/<change-id>/`:
+- Change ID: verb-led with `remove-` prefix (e.g., `remove-legacy-export`)
+**Manifest** must include:
+```markdown
+# Change: Remove <feature/decision>
+## Why
+[Clear rationale for removal]
+## Migration
+[How users/systems should handle this going away]
+[What replaces it, if anything]
+[Timeline if gradual deprecation]
+## Feature Changes
+- **REMOVED** `<capability>/<name>.feature` — [or specific scenarios]
+## Decisions
+- **SUPERSEDED** `NNNN-title.md` — [if applicable]
+```
+**Proposed feature files:**
+- Copy the current baseline `.feature` file
+- Remove the targeted Feature/Scenarios
+- If removing specific scenarios from a feature, the proposed file is the feature WITHOUT those scenarios
+- If removing an entire feature file, note it in manifest (no proposed file needed — absence is the proposal)
+### 4. Generate Tasks
+Create `tasks.md` covering:
+```markdown
+## 1. Remove Production Code
+- [ ] 1.1 Remove <specific code implementing the feature>
+- [ ] 1.2 Remove <related templates/components>
+- [ ] 1.3 Clean up imports and dead references
+## 2. Remove Tests
+- [ ] 2.1 Remove step definitions for removed scenarios
+- [ ] 2.2 Remove any unit/integration tests specific to this feature
+- [ ] 2.3 Update shared steps if affected
+## 3. Update Related Artifacts
+- [ ] 3.1 Update ADR status to superseded (if applicable)
+- [ ] 3.2 Update any features that referenced removed behavior
+## 4. Verification
+- [ ] 4.1 Remaining feature files still pass
+- [ ] 4.2 No dead code / unused imports left behind
+- [ ] 4.3 No broken references in other features
+```
+### 5. Review
+Present the full removal plan to the user:
+- What's being removed (features, scenarios, decisions)
+- What code will be deleted
+- What remains untouched
+- Migration path
+Do NOT proceed without user approval. Removal is destructive.
+## Important
+- Removal is a first-class operation, not a hack. It gets the same rigor as adding a feature.
+- The manifest MUST document WHY something is being removed and what the migration path is.
+- Always check for dependencies before removing. Don't orphan related features or break shared steps.
+- When removing scenarios from a feature (not the whole feature), the proposed `.feature` file represents the desired end state — the feature minus the removed scenarios.
+- After removal, remaining features must still pass. This is verified in the apply stage.
+- Archive preserves the removal rationale forever — future developers can understand why something was removed.
+## Done
+When the removal plan is approved and ready for implementation, the workflow is complete. Proceed to `grimoire-apply` to execute the removal tasks.