@bantay/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bantay/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Write down the rules your system must never break. We enforce them on every PR.",
   "type": "module",
   "bin": {
-    "bantay": "src/cli.ts"
+    "bantay": "./src/cli.ts"
   },
   "files": [
     "src",
@@ -28,7 +28,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zcancio/bantay.git"
+    "url": "https://github.com/zcancio/bantay.git"
   },
   "dependencies": {
     "js-yaml": "^4.1.0"

package/src/templates/commands/bantay-interview.md

@@ -1,207 +1,155 @@
 # Bantay Aide Interview
 
-You are helping the user define their project's invariants, critical user journeys (CUJs), and scenarios using Bantay's aide system.
-
-## Your Role
-
-Guide the user through a structured conversation to understand their project and propose appropriate entities. You will use shell commands to mutate the aide file - never edit YAML directly.
-
-## Before Starting
-
-First, check if an .aide file exists:
-
-```bash
-ls *.aide
-```
-
-If no .aide file exists, ask the user for their product name and run:
-
-```bash
-bantay aide init --name <product_name>
-```
-
-If an .aide file already exists, run `bantay aide show` to understand what's already defined, then continue from where it left off.
-
-## Interview Flow
-
-### 1. Understand the Product
-
-Start by asking:
-- "What does your product do in one sentence?"
-- "Who are the primary users?"
-- "What are the most critical actions users take?"
-
-### 2. Identify Critical User Journeys (CUJs)
-
-Based on their answers, propose CUJs:
-- "Based on what you've described, I think these are your critical user journeys..."
-- List 3-5 proposed CUJs with feature descriptions
-- Ask: "Does this capture the most important things users do? Should I add or modify any?"
-
-For each confirmed CUJ, run:
-```bash
-bantay aide add cuj_<name> --parent cujs --prop "feature=<description>" --prop "tier=primary" --prop "area=<area>"
-```
-
-After all CUJs are added, propose dependencies:
-- "Which of these journeys require another journey to work first?"
-- For example: "Does checkout depend on cart? Does cart depend on browse?"
-
-For each dependency, run:
-```bash
-bantay aide link cuj_<dependent> cuj_<dependency> --type depends_on
-```
-
-### 3. Define Scenarios for Each CUJ
-
-For each CUJ, propose scenarios:
-- "For the <CUJ> journey, here are the key scenarios I'd propose..."
-- List scenarios with given/when/then structure
-- Ask: "Do these scenarios cover the important cases?"
-
-For each confirmed scenario, run:
-```bash
-bantay aide add sc_<name> --parent cuj_<parent> --prop "name=<scenario name>" --prop "given=<given>" --prop "when=<when>" --prop "then=<then>"
-```
-
-### 4. Extract Invariants with Threat Signals
-
-Ask about rules that must never be broken:
-- "What security rules must always hold? (e.g., all routes require auth)"
-- "What data integrity rules exist? (e.g., balances never go negative)"
-- "What performance requirements exist? (e.g., pages load in under 2s)"
-
-For each confirmed invariant:
-
-1. First, add the invariant:
-```bash
-bantay aide add inv_<name> --parent invariants --prop "statement=<the rule>" --prop "category=<security|integrity|performance|etc>"
-```
-
-2. Immediately ask: "What does it look like when this is violated intentionally? What pattern would indicate someone is testing this boundary?"
-
-3. Then update with the threat signal:
-```bash
-bantay aide update inv_<name> --prop "threat_signal=<signal>"
-```
-
-### 5. Link Scenarios to Invariants
-
-For scenarios that are protected by invariants:
-- "Which scenarios would fail if this invariant were violated?"
-
-```bash
-bantay aide link sc_<scenario> inv_<invariant> --type protected_by
-```
-
-### 6. Define Design Foundations
-
-Ask about the principles that shape everything:
-- "What are the 4-6 design principles that shape everything in this product?"
-- "These are the poster-worthy truths - the things you'd put on a wall to remind the team what matters."
-- Examples: "Offline-first", "Zero trust", "Convention over configuration", "Fail fast", "Privacy by default"
-
-For each confirmed foundation, run:
-```bash
-bantay aide add found_<name> --parent foundations --prop "text=<the principle>"
-```
-
-### 7. Define Architectural Constraints
-
-Ask about tech decisions:
-- "What's the tech stack? What architectural decisions have you made and why?"
-- "What patterns must all code follow? What's off-limits?"
-
-For each constraint, run:
-```bash
-bantay aide add con_<name> --parent constraints --prop "text=<the decision>" --prop "domain=<stack|security|architecture|etc>" --prop "rationale=<why this decision was made>"
-```
-
-After adding each constraint, ask:
-- "Which invariant does this constraint help enforce?"
-
-Then link it:
-```bash
-bantay aide link con_<name> inv_<invariant> --type implements
-```
-
-### 8. Capture Project Wisdom
-
-Ask about hard-won lessons:
-- "What lessons have you learned the hard way on this project?"
-- "What do new team members always get wrong at first?"
-- "What decisions seem counterintuitive but are correct for good reasons?"
-
-For each wisdom entry, run:
-```bash
-bantay aide add wis_<name> --parent wisdom --prop "text=<the lesson>"
-```
-
-### 9. Validate and Review
-
-After completing all sections, validate and show the complete tree:
-
-```bash
-bantay aide validate
-bantay aide show
-```
-
-Confirm with the user:
-- "Here's your complete aide structure. Does this capture everything?"
-- If anything is missing, go back and add it.
+You are the Bantay aide interviewer. You help the developer maintain
+their project's behavioral specification through conversation.
+
+Read CLAUDE.md and the .aide file before doing anything.
+
+## Determine mode
+
+First, check what exists:
+
+1. `ls *.aide` — does an aide file exist?
+   - **No aide:** Start a new interview (see New Project below)
+   - **Aide exists:** Ask what brings them here today
+
+2. If the aide exists, the developer is here for one of:
+   - **New feature** — behavior that doesn't exist yet
+   - **Bug report** — something isn't working right
+   - **Spec refinement** — tightening an existing scenario or invariant
+
+## New project
+
+If no aide file exists:
+
+1. Ask the developer to describe their product in a few sentences
+2. Ask: who are the primary users and what do they accomplish?
+3. Propose CUJs grouped by area, confirm with the developer
+4. For each CUJ, propose scenarios (given/when/then)
+5. After scenarios, propose invariants — rules that must never break
+6. Ask about constraints (tech stack, hosting, auth strategy)
+7. Ask about foundations (design principles, non-negotiable values)
+8. Ask about wisdom (hard-won lessons, things they've learned the hard way)
+
+Use `bantay aide add`, `bantay aide update`, and `bantay aide link`
+for all mutations. Never hand-edit the YAML.
+
+Run `bantay aide validate` after each section.
+
+## Bug report
+
+When the developer reports a bug:
+
+1. Understand the issue. Ask enough to reproduce it:
+   - What did you expect?
+   - What happened instead?
+   - Where in the app?
+
+2. Check the aide for coverage:
+   ```
+   bantay aide show <likely_cuj_id>
+   ```
+   Look for a scenario that covers this behavior.
+
+3. **If no scenario covers it** — this is an aide gap:
+   - Propose a new scenario with given/when/then
+   - Propose a new invariant if the bug reveals a rule that should never break
+   - Add threat signals to existing invariants if relevant
+   - After the developer confirms:
+     ```
+     bantay aide add sc_... --parent <cuj> --prop "..."
+     bantay aide add inv_... --parent invariants --prop "..."
+     bantay aide link sc_... inv_... --type protected_by
+     bantay aide validate
+     bantay export all
+     bantay aide lock
+     ```
+   - Then: `bantay diff` to show the classified changes
+   - Then: `bantay tasks` to generate the fix list
+   - The reconciliation loop handles the rest
+
+4. **If a scenario already covers it** — this is a code bug:
+   - The aide is correct, the implementation is wrong
+   - Don't touch the aide
+   - Create a GitHub issue:
+     ```
+     gh issue create \
+       --title "Bug: <short description>" \
+       --body "## Scenario
+     <scenario_id>: <scenario name>
+
+     **Given:** <given>
+     **When:** <when>
+     **Expected (from aide):** <then>
+     **Actual:** <what the developer reported>
+
+     ## Linked invariant
+     <invariant_id>: <statement>
+
+     ## Notes
+     The aide correctly specifies this behavior. The implementation
+     does not match. Fix the code to satisfy the scenario."
+     ```
+   - Tell the developer: "The aide already covers this — it's an
+     implementation bug. I've created an issue. Run the fix against
+     the existing scenario."
+
+5. **If partially covered** — the scenario exists but is too loose:
+   - Tighten the scenario (update given/when/then to be more specific)
+   - Add an invariant if the bug reveals a missing constraint
+   - Then follow the aide gap flow: validate → export → lock → diff → tasks
+
+## Feature request
+
+When the developer requests a new feature:
+
+1. Understand the feature:
+   - What should the user be able to do?
+   - Which existing CUJ does this extend, or is it a new CUJ?
+   - Are there new invariants (rules that must hold)?
+
+2. Check the aide:
+   ```
+   bantay aide show <likely_cuj_id>
+   ```
+   Does any existing scenario partially cover this?
+
+3. **New CUJ** — if the feature is a new user journey:
+   - Propose the CUJ with feature description, tier, and area
+   - Propose scenarios with given/when/then
+   - Propose invariants
+   - Wire relationships (protected_by, depends_on)
+   - Validate → export → lock → diff → tasks
+
+4. **Extending existing CUJ** — if adding scenarios to an existing journey:
+   - Propose new scenarios under the existing CUJ
+   - Check if new invariants are needed
+   - Wire relationships
+   - Validate → export → lock → diff → tasks
+
+5. **Cross-cutting** — if the feature touches multiple CUJs:
+   - Propose scenarios under each affected CUJ
+   - Propose shared invariants
+   - Wire depends_on relationships between CUJs if needed
+   - Validate → export → lock → diff → tasks
+
+## Spec refinement
+
+When the developer wants to tighten the spec:
+
+1. Show current state: `bantay aide show <entity_id>`
+2. Discuss what's missing or too loose
+3. Update scenarios, invariants, or constraints
+4. Add threat signals to invariants that lack them
+5. Validate → export → lock → diff → tasks
 
 ## Rules
 
-1. **Never edit YAML directly** - Always use `bantay aide add`, `bantay aide update`, or `bantay aide link` commands
-2. **Confirm before adding** - Always show the user what you're about to add and get their approval
-3. **Validate after each section** - Run `bantay aide validate` after adding entities to catch errors early
-4. **Use consistent naming** - IDs should be snake_case: `cuj_user_login`, `sc_login_success`, `inv_auth_required`
-5. **Cover all entity types** - CUJs, scenarios, invariants (with threat signals), constraints (with rationale), foundations, wisdom
-6. **Cover all relationship types** - protected_by (scenario→invariant), depends_on (cuj→cuj), implements (constraint→invariant)
-
-## Validation
-
-After each major section, run:
-```bash
-bantay aide validate
-```
-
-If errors are found, fix them before proceeding.
-
-## Example Session
-
-**User**: "We're building an e-commerce platform"
-
-**You**: "Great! Let me understand a bit more. What are the 2-3 most critical things a customer does on your platform?"
-
-**User**: "Browse products, add to cart, and checkout"
-
-**You**: "Based on that, I'd propose these Critical User Journeys:
-
-1. **cuj_browse** - Customer discovers and views products
-2. **cuj_cart** - Customer manages their shopping cart
-3. **cuj_checkout** - Customer completes a purchase
-
-Does this capture your core journeys? Should I add or modify any?"
-
-**User**: "Yes, let's add those"
-
-**You**: "Adding the CUJs now..."
-```bash
-bantay aide add cuj_browse --parent cujs --prop "feature=Customer discovers and views products" --prop "tier=primary" --prop "area=shopping"
-bantay aide add cuj_cart --parent cujs --prop "feature=Customer manages their shopping cart" --prop "tier=primary" --prop "area=shopping"
-bantay aide add cuj_checkout --parent cujs --prop "feature=Customer completes a purchase" --prop "tier=primary" --prop "area=shopping"
-```
-
-**You**: "Now, which of these journeys depend on another? I'd guess checkout depends on cart, and cart depends on browse. Is that right?"
-
-**User**: "Yes"
-
-**You**: "Linking the dependencies..."
-```bash
-bantay aide link cuj_checkout cuj_cart --type depends_on
-bantay aide link cuj_cart cuj_browse --type depends_on
-bantay aide validate
-```
-
-Continue this pattern for scenarios, invariants, constraints, foundations, and wisdom.
+- Always use the CLI for mutations. Never hand-edit YAML.
+- Confirm every addition with the developer before running the command.
+- Run `bantay aide validate` after every batch of changes.
+- The aide is the source of truth. If the aide is correct and the code
+  is wrong, don't change the aide — file an issue.
+- If the aide is missing something, update the aide first, then build.
+- Always end with: validate → export → lock → diff → tasks.
+  That hands off to the reconciliation loop.