@grimoire-cc/cli 0.7.0 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grimoire-cc/cli",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "CLI tool for installing Grimoire agent and skill packs",
   "type": "module",
   "license": "MIT",

package/packs/dev-pack/agents/gr.tdd-specialist.md

@@ -2,7 +2,7 @@
 name: grimoire:tdd-specialist
 description: "Language-agnostic TDD and unit testing specialist. Use when writing unit tests, adding test coverage, or doing test-driven development in ANY language. Auto-detects project language and test framework (pytest, jest, vitest, mocha, junit, go test, cargo test, xunit, etc.). Examples: 'write tests for this function', 'add test coverage for the auth module', 'help me TDD this feature'."
 tools: Read, Edit, Write, Grep, Glob, Skill, Bash
-model: sonnet
+model: inherit
 ---
 
 # TDD Specialist Agent

package/packs/docs-pack/skills/gr.business-logic-docs/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: grimoire:business-logic-docs
-description: "Create and maintain structured business logic documentation for AI assistants and developers. Use when documenting business rules, domain knowledge, invariants, workflows, state machines, entity relationships, decision logs, or building a business logic knowledge base."
+description: "Create, update, and audit structured business logic documentation for AI assistants and developers. Use when documenting business rules, domain knowledge, invariants, workflows, state machines, entity relationships, decision logs, building a business logic knowledge base, or reviewing docs for staleness."
 ---
 
 # Business Logic Documentation
 
-Guide Claude through creating and maintaining a structured knowledge base of a project's business logic. The knowledge base serves two audiences: AI coding assistants (so they understand domain context and make better decisions) and human developers (so they can recall and reason about business rules).
+Guide Claude through creating, updating, and auditing a structured knowledge base of a project's business logic. The knowledge base serves two audiences: AI coding assistants (so they understand domain context and make better decisions) and human developers (so they can recall and reason about business rules).
 
 All generated documentation lives in `docs/business-logic/` by default. Ask the developer if they prefer a different path before generating.
 
+**Core principle: business rules drive code, not vice versa.** Business logic documentation captures decisions that drive code changes — not descriptions of what code does. The flow is always: business decision → documentation → code implementation.
+
 ## Workflow 1 — Create the Initial Knowledge Base
 
 Use this when a project has no business logic docs yet.
@@ -31,8 +33,9 @@ Surface business rules that aren't obvious from code alone. Ask focused question
 1. **Domain terminology** — "What terms does your team use that have precise meanings? Any terms that are commonly confused?"
 2. **User roles and permissions** — "What roles exist, and what can each role do or not do?"
 3. **Critical invariants** — "What must always be true? What must never happen?"
-4. **Non-obvious edge cases** — "What scenarios have caused bugs or confusion before?"
-5. **Regulatory or legal rules** — "Are any business rules driven by compliance requirements?"
+4. **Hard constraints** — "What things MUST NEVER happen in the system? What would cause the most damage if violated?"
+5. **Non-obvious edge cases** — "What scenarios have caused bugs or confusion before?"
+6. **Regulatory or legal rules** — "Are any business rules driven by compliance requirements?"
 
 After each batch of answers, ask follow-up questions if something needs clarification. Move to the next domain area once coverage feels sufficient.
 
@@ -41,7 +44,7 @@ After each batch of answers, ask follow-up questions if something needs clarific
 Create the three-tier structure described below. For each domain area identified:
 
 1. Create the Tier 2 file using the template from [references/tier2-template.md](references/tier2-template.md)
-2. Fill in what you learned from code analysis and the interview
+2. Fill in what you learned from the interview. For rules surfaced from code analysis (not confirmed by the developer), mark with `[SOURCE: code-audit — unconfirmed]` — these MUST be confirmed before being treated as business rules.
 3. Mark sections where information is incomplete with `<!-- TODO: clarify with team -->`
 
 Then create the `_overview.md` (Tier 1) and `_decision-log.md` (Tier 3) files.
@@ -52,17 +55,104 @@ Add a reference to the knowledge base in the project's `CLAUDE.md` (create one i
 
 ## Workflow 2 — Update the Existing Knowledge Base
 
-Use this when business logic changes.
+Use this when business logic changes. Updates are driven by text input — user stories, change requests, discussion transcripts/summaries — not by code analysis.
+
+### Step 1: Understand the Change
+
+Read the provided input (user story, change request, discussion transcript/summary). Extract:
+
+- What business rules are being added, modified, or removed
+- Which domain area(s) and Tier 2 file(s) are affected
+
+Do NOT look at code to infer business rules — the provided input is the single source of truth. If the input is ambiguous or incomplete, ask the user for clarification before proceeding.
+
+### Step 2: Review Existing Documentation
+
+Read the affected Tier 2 file(s). For each change from Step 1, check:
+
+- Does it contradict any existing rule?
+- Does it modify an existing rule or add a new one?
+- Does it affect workflows, entities, or integration points?
+- Does it invalidate any existing constraints, examples, or counterexamples?
+
+Flag any conflicts or ambiguities to the user before making changes.
+
+### Step 3: Clarify Uncertainties
+
+If anything from the input is unclear, contradicts existing docs, or leaves gaps, ask the user targeted questions. Examples:
+
+- "The user story says X, but the current docs say Y — which is correct?"
+- "This change implies Z — is that intended?"
+- "Are there edge cases for this new rule?"
+- "Does this replace the existing rule or add a new exception?"
+
+NEVER proceed with uncertain information. NEVER fill gaps by guessing from code.
+
+### Step 4: Apply the Updates
+
+Only add information you are certain about from the provided input.
+
+- **Modified rules**: Replace the old rule with the new one. Don't annotate what changed — git tracks history.
+- **New rules**: Use the template format from [references/tier2-template.md](references/tier2-template.md). Include Source marker.
+- **Removed rules**: Delete them. Only keep a note about the removal if it carries business context that other rules depend on (e.g., "we no longer support gift cards" is useful if other rules reference gift cards).
+- **New domain areas**: Create a new Tier 2 file and add it to the table of contents in `_overview.md`.
+- **"Enforced in" fields**: Leave empty or mark with `<!-- TODO: add code location after implementation -->` — code locations are filled in after implementation, not before.
+- **Diagrams and glossary**: Update as needed to reflect changes.
+
+### Step 5: Validate and Present
+
+Verify:
+
+- No contradictions introduced across files
+- Diagrams reflect the changes
+- Table of contents is accurate
+- Terminology is consistent with the glossary
+- Decision log entry added if the change involves a non-obvious decision
+
+Present a summary to the user showing exactly what was changed and why, so they can confirm accuracy.
+
+## Workflow 3 — Audit Knowledge Base
+
+Use only when the user explicitly requests an audit or review of existing documentation.
+
+This is the one workflow where code comparison is appropriate — but only to flag potential gaps, never to infer new business rules.
+
+### Step 1: Review Documentation Completeness
 
-1. **Identify the affected domain area.** Determine which Tier 2 file(s) need updating.
-2. **Update in place.** Edit the corresponding file directly. Do not keep old versions in the doc — git handles history.
-3. **Log non-obvious decisions.** If the change involves a non-obvious decision (why this approach over alternatives), append an entry to `_decision-log.md`.
-4. **New domain areas.** If logic doesn't fit any existing file, create a new Tier 2 file using [references/tier2-template.md](references/tier2-template.md) and add it to the table of contents in `_overview.md`.
-5. **Deprecated logic.** Mark deprecated rules clearly with a reason and expected removal timeline. Do not delete until the code is cleaned up:
-   ```markdown
-   - **Rule**: ~~Users can pay with gift cards.~~
-     **DEPRECATED (2025-03-01):** Gift card support removed in v3.0. Code cleanup tracked in PROJ-1234. Remove this entry after cleanup.
-   ```
+Check for structural issues using [references/audit-checklist.md](references/audit-checklist.md):
+
+- Unresolved `<!-- TODO -->` markers
+- Empty or placeholder sections
+- Rules missing "Why" explanations
+- Critical rules without counterexamples
+- Constraints section empty or missing
+
+### Step 2: Check Code Alignment
+
+**Only when the user explicitly asks to compare docs against code.** Check:
+
+- "Enforced in" references still point to existing code
+- State diagram transitions match actual code behavior
+- Entity attributes match current schema
+
+Flag undocumented code behavior as questions, not assertions: "This code seems to enforce X, but it's not documented — is this a business rule that should be captured?" Mark any rules surfaced this way with `[SOURCE: code-audit — unconfirmed]`.
+
+### Step 3: Check Terminology Consistency
+
+- Extract all glossary terms from `_overview.md`
+- Search Tier 2 files for inconsistent usage (synonyms, abbreviations, variant spellings)
+- Report inconsistencies in the format described in [references/audit-checklist.md](references/audit-checklist.md)
+
+### Step 4: Produce Audit Report
+
+Structured output with sections:
+
+1. **Incomplete Items** — Missing Why, missing examples, empty sections, unresolved TODOs
+2. **Terminology Issues** — Inconsistent term usage across files
+3. **Structural Issues** — ToC mismatches, missing template sections, duplicated rules
+4. **Potential Documentation Gaps** *(only if Step 2 was performed)* — Code behavior not reflected in docs
+
+Ask the developer to review and confirm before making any changes.
 
 ## Three-Tier Documentation Structure
 
@@ -82,8 +172,10 @@ E.g., `orders.md`, `payments.md`, `inventory.md`. Each follows the template in [
 
 - **Purpose** — What this area does and why it exists.
 - **Key Entities** — Core entities, attributes, relationships. Use mermaid for non-trivial relationships.
-- **Business Rules & Invariants** — The most critical section. Each rule states: what the rule is, why it exists (the business reason), where it's enforced in code, and a concrete example including an edge case.
+- **Constraints** — The highest-value content. MUST and MUST NOT rules with business reasons.
+- **Business Rules & Invariants** — Each rule states: what the rule is, why it exists (the business reason), where it's enforced in code, a concrete example including an edge case, and for critical rules a counterexample.
 - **Workflows & State Transitions** — Key processes with mermaid state diagrams for anything with 3+ states. Specify triggers and validations.
+- **Decision Trees** — Sequential if-then format for multi-branch conditional logic.
 - **Integration Points** — External systems, APIs, other domain areas. Note contracts and assumptions.
 - **Edge Cases & Known Gotchas** — Non-obvious behaviors that have caused bugs or confusion.
 
@@ -96,7 +188,7 @@ Each entry follows:
 ```markdown
 ## YYYY-MM-DD — [Short title]
 **Context:** What situation prompted this decision.
-**Decision:** What was decided.
+**Decision:** [Chosen option] because [justification], to achieve [desired outcome], accepting [tradeoff].
 **Alternatives considered:** What else was evaluated and why it was rejected.
 **Affected areas:** Which Tier 2 files are impacted.
 ```
@@ -107,7 +199,7 @@ Follow these when writing or updating business logic docs:
 
 1. **Write for reasoning, not just reading.** Always include the "why" behind a rule. Instead of "Users can't delete invoices," write "Users can't delete invoices because downstream accounting reconciliation depends on invoice immutability. Soft-delete via `deleted_at` is used instead." The causal chain enables correct inferences.
 
-2. **Be explicit about invariants.** Things that must always or never be true are the highest-value content. Call them out prominently in every domain area file.
+2. **Be explicit about invariants.** Things that must always or never be true are the highest-value content. Call them out prominently in the Constraints section of every domain area file.
 
 3. **Link business concepts to code landmarks.** Don't describe implementation details, but do say "Order state transitions are enforced in `OrderStateMachine` — never manipulate `order.status` directly." This bridges conceptual and concrete.
 
@@ -119,6 +211,49 @@ Follow these when writing or updating business logic docs:
 
 7. **Group by domain area, not by technical layer.** Everything about orders (validation, state machine, permissions, integrations) goes in `orders.md`, not split across "validations.md" and "permissions.md".
 
+8. **Constraints before capabilities.** Document what MUST NOT happen before documenting what should happen. Use explicit RFC-2119 language (MUST, MUST NOT, SHOULD, SHOULD NOT) for rules that carry enforcement weight.
+
+9. **Include counterexamples for critical rules.** For every invariant and constraint, show the wrong behavior and why it fails. Format: what the correct behavior is, what the incorrect behavior looks like, and why it matters.
+
+10. **Use decision trees for complex conditional logic.** Any logic with 3+ branches MUST use sequential if-then format. Mark mutually exclusive paths explicitly. No prose-only descriptions for multi-branch logic.
+
+11. **Mark information sources.** Tag rules with their origin: `[SOURCE: user-story]`, `[SOURCE: discussion]`, `[SOURCE: change-request]`. During audits (Workflow 3 only), rules surfaced from code analysis get `[SOURCE: code-audit — unconfirmed]` and MUST be confirmed with the user before being treated as business rules. Incorrect docs are worse than missing docs.
+
+12. **State machines over prose for workflows.** Any process with 3+ states MUST use a mermaid stateDiagram plus a transition table. No prose-only workflow descriptions for stateful processes.
+
+## Documentation Clarity
+
+Docs describe the current state, not history:
+
+- When a rule changes, **replace it** — don't annotate what it used to be. Git tracks history.
+- No "previously was", "changed from X to Y", "before it was" language.
+- Remove rules that no longer apply. Only keep a note about the removal if it carries business context other rules depend on (e.g., "we no longer support gift cards" is useful if other rules reference gift cards).
+- Use `<!-- TODO -->` markers only for genuinely incomplete information that needs user input.
+- Every statement in the docs should describe what IS true right now.
+
+## ALWAYS / NEVER
+
+### ALWAYS
+
+- ALWAYS confirm the output path before generating files
+- ALWAYS include "Why" for every rule and constraint
+- ALWAYS ask for clarification when input is ambiguous or incomplete
+- ALWAYS verify new information doesn't contradict existing rules
+- ALWAYS present a summary of all changes for user confirmation
+- ALWAYS update the Table of Contents when files are added or removed
+- ALWAYS add a decision log entry for non-obvious changes
+- ALWAYS leave "Enforced in" empty when the code location is unknown
+
+### NEVER
+
+- NEVER guess or infer business rules from code — business rules drive code, not vice versa
+- NEVER add information you are not certain about
+- NEVER proceed when the input contradicts existing documentation — ask first
+- NEVER reverse-engineer business rules from code changes unless the user explicitly requests it
+- NEVER use "previously was" / "changed from X to Y" / history annotations — docs describe current state, git tracks history
+- NEVER leave diagrams contradicting documented transitions
+- NEVER duplicate rules across files — reference the canonical location instead
+
 ## CLAUDE.md Integration
 
 Add (or update) the following section in the project's `CLAUDE.md`:
@@ -129,6 +264,7 @@ Before modifying business logic, read the relevant file in `docs/business-logic/
 When your changes affect business rules, update the corresponding doc in the same commit.
 If no file exists for the domain area, create one following the structure of existing files.
 Start with `docs/business-logic/_overview.md` for domain orientation.
+Rules marked `[SOURCE: code-audit — unconfirmed]` need human confirmation before relying on them.
 ```
 
 If the developer chose a custom docs path, adjust the paths accordingly.
@@ -137,5 +273,6 @@ If the developer chose a custom docs path, adjust the paths accordingly.
 
 - This skill provides guidance for creating documentation, not executable code.
 - The knowledge base captures business rules at a point in time — it requires human input for rules that aren't visible in code.
+- Rules inferred from code (`[SOURCE: code-audit — unconfirmed]`) require human verification before they should be treated as authoritative business rules.
 - Mermaid diagrams may not render in all environments (they work in GitHub, VS Code, and most modern markdown viewers).
 - The decision log is only as valuable as the team's discipline in maintaining it.

package/packs/docs-pack/skills/gr.business-logic-docs/references/audit-checklist.md

@@ -0,0 +1,48 @@
+# Audit Checklist
+
+Use this checklist with [Workflow 3 — Audit Knowledge Base](../SKILL.md#workflow-3--audit-knowledge-base).
+
+## Code Alignment Checks
+
+Only perform when the user explicitly requests code comparison.
+
+- [ ] Every "Enforced in" reference points to a file/class/function that still exists
+- [ ] Mermaid state diagrams match actual state transitions in code
+- [ ] Entity attributes listed in docs match the current schema/model definitions
+- [ ] Integration contracts (endpoints, payloads) match actual API implementations
+- [ ] Decision trees match actual conditional logic in code
+
+Present findings as questions, not assertions. Example: "This code seems to enforce X, but it's not documented — is this a business rule that should be captured?"
+
+## Content Quality Checks
+
+- [ ] Every business rule has a "Why" explanation
+- [ ] Critical rules (invariants, constraints) have counterexamples
+- [ ] No unconfirmed `[SOURCE: code-audit — unconfirmed]` markers older than 30 days
+- [ ] Decision trees exist for multi-branch logic (3+ paths)
+- [ ] Constraints section populated with MUST / MUST NOT items
+- [ ] Examples use concrete values, not abstract descriptions
+
+## Structural Checks
+
+- [ ] Table of Contents in `_overview.md` lists all Tier 2 files
+- [ ] Each Tier 2 file has all template sections (even if marked TODO)
+- [ ] Glossary terms in `_overview.md` are consistent across all files
+- [ ] No business rules duplicated across multiple Tier 2 files
+- [ ] All `<!-- TODO -->` markers reviewed — resolve or confirm still pending
+- [ ] Decision log entries reference correct Tier 2 files in "Affected areas"
+
+## Terminology Consistency Check
+
+For each term in the glossary:
+
+1. Search all Tier 2 files for the term
+2. Search for common synonyms or abbreviations
+3. Flag any file that uses a synonym instead of the glossary term
+4. Check that the term's definition still matches how it's used in context
+
+Report format:
+
+| Term | Expected | Found | File | Line |
+|---|---|---|---|---|
+| `[glossary term]` | `[glossary term]` | `[synonym found]` | `[file]` | `[line]` |

package/packs/docs-pack/skills/gr.business-logic-docs/references/tier2-template.md

@@ -1,5 +1,16 @@
 # [Domain Area Name]
 
+## Table of Contents
+
+- [Purpose](#purpose)
+- [Key Entities](#key-entities)
+- [Constraints](#constraints)
+- [Business Rules & Invariants](#business-rules--invariants)
+- [Workflows & State Transitions](#workflows--state-transitions)
+- [Decision Trees](#decision-trees)
+- [Integration Points](#integration-points)
+- [Edge Cases & Known Gotchas](#edge-cases--known-gotchas)
+
 ## Purpose
 
 One-paragraph summary of what this area does and why it exists.
@@ -23,14 +34,32 @@ erDiagram
     }
 ```
 
+## Constraints
+
+The highest-value content — what MUST and MUST NOT happen in this domain area.
+
+### MUST
+
+- **Constraint**: State what must always be true.
+  - **Why**: Business reason this constraint exists.
+  - **Enforced in**: File, class, or function name.
+
+### MUST NOT
+
+- **Constraint**: State what must never happen.
+  - **Why**: Business reason — what goes wrong if violated.
+  - **Enforced in**: File, class, or function name.
+
 ## Business Rules & Invariants
 
 Each rule follows this pattern:
 
 - **Rule**: State the rule clearly.
 - **Why**: Explain the business reason (this enables AI to reason correctly in adjacent code).
-- **Enforced in**: Point to where in the codebase this is enforced (file, class, or function name).
+- **Enforced in**: Point to where in the codebase this is enforced (file, class, or function name). Leave empty or use `<!-- TODO: add code location after implementation -->` if not yet implemented.
 - **Example**: A concrete scenario illustrating the rule, including at least one edge case.
+- **Counterexample** *(critical rules)*: Show the wrong behavior and why it fails.
+- **Source**: `[SOURCE: user-story]`, `[SOURCE: discussion]`, `[SOURCE: change-request]`, or `[SOURCE: code-audit — unconfirmed]`.
 
 ---
 
@@ -38,6 +67,8 @@ Each rule follows this pattern:
 - **Why**: Downstream logistics systems snapshot the order at shipment time; modifications would cause fulfillment mismatches.
 - **Enforced in**: `OrderStateMachine.validateTransition()` rejects edits on shipped orders.
 - **Example**: A customer tries to change their shipping address 5 minutes after shipment. The system returns a 409 Conflict with instructions to contact support for a redirect request instead.
+- **Counterexample**: If the system allowed edits after shipment, the warehouse would ship to the old address while the customer sees the new one — causing a lost package and a support ticket.
+- **Source**: `[SOURCE: user-story]`
 
 ## Workflows & State Transitions
 
@@ -61,6 +92,22 @@ stateDiagram-v2
 | Pending -> Rejected | Admin rejects | Rejection reason is required |
 | Approved -> Completed | System fulfills | External service confirms fulfillment |
 
+## Decision Trees
+
+Use sequential if-then format for multi-branch conditional logic. Mark mutually exclusive paths explicitly.
+
+```
+IF [condition A]
+  THEN [action/outcome 1]
+ELSE IF [condition B]           ← mutually exclusive with A
+  IF [sub-condition B1]
+    THEN [action/outcome 2]
+  ELSE
+    THEN [action/outcome 3]
+ELSE                            ← default / fallback
+  THEN [action/outcome 4]
+```
+
 ## Integration Points
 
 External systems, APIs, webhooks, or other domain areas this module interacts with. Note any contracts or assumptions.
@@ -72,3 +119,11 @@ External systems, APIs, webhooks, or other domain areas this module interacts wi
 Non-obvious behaviors that have caused bugs or confusion before. These are extremely high-value for AI assistants.
 
 - **[Gotcha title]**: Description of the non-obvious behavior, why it exists, and what to watch out for when modifying related code.
+
+<!--
+Staleness markers — use these in comments to flag items for review:
+
+<!-- TODO: clarify with team -->
+<!-- TODO: add code location after implementation -->
+<!-- STALE? last verified YYYY-MM-DD — needs review -->
+-->