@tudeorangbiasa/sdd-multiagent-opencode 0.2.2 → 0.3.0

package/.opencode/commands/sdd-quick.md

@@ -1,9 +1,9 @@
 ---
-description: Quick one-shot fix for cosmetic/config changes with lightweight verification
+description: Quick one-shot fix for cosmetic/config changes with CLI wrapper for deterministic checks
 agent: sdd-implementer
 ---
 
-Execute a small, safe change with minimal overhead. No full spec artifacts required.
+Execute a small, safe change with minimal overhead. Uses CLI wrapper for Phase 1-2 (classification, pre-flight) and Phase 4-5 (verification, ledger). LLM is only used for Phase 3 (the actual edit).
 
 ## Usage
 
@@ -12,138 +12,169 @@ Execute a small, safe change with minimal overhead. No full spec artifacts requi
 /sdd-quick "rename isLoading to isFetching in auth.ts"
 ```
 
-## Phase 1: Rule-Based Change Classification
-
-Do NOT guess the change type. Classify using these deterministic rules, evaluated in order. The first matching rule wins.
-
-### Force → CONTRACT (❌ Abort → suggest `/sdd-propose`)
-- Change to any exported function, class, interface, or type name
-- Change to any file matching: `**/api/**`, `**/dto/**`, `**/schema/**`, `**/types/public-api.ts`, `**/graphql/types.ts`
-- Change to function signature (add/remove/rename parameter)
-- Change to any file explicitly marked as `@public` or `@api` in JSDoc
-
-### Force → LOGIC (❌ Abort → suggest `/sdd-propose`)
-- ANY change to operators: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`, `&&`, `||`, `!`, `?:`
-- ANY change to control flow keywords: `if`, `else`, `switch`, `case`, `for`, `while`, `return`, `throw`, `try`, `catch`, `finally`
-- ANY change to a condition expression or boolean logic
-- ANY change to calculation or math expression
-- Adding or removing a function call
-- Changing a function's return value
-
-### Force → CONFIG (⚠️ Allowed with warning)
-- Change to constant value, env var, feature flag, or config file (`*.config.*`, `.env`, `*.json`)
-- Change to a string that is NOT rendered in a UI component
-
-### Default → COSMETIC (✅ Allowed)
-- Typo fix in string literal or comment
-- Whitespace or formatting change
-- Internal variable rename (not exported)
-- Import reordering or unused import removal
-- Dead code removal
-- Comment addition or update
-
-If the change matches CONTRACT or LOGIC, STOP immediately. Do not proceed. Report why and suggest `/sdd-propose`.
-
-## Phase 2: Pre-Flight Checks
-
-### Lock File Check
-1. Check if `specs/.sdd-lock` exists.
-2. If it exists:
-   - Read the PID from the lock file.
-   - Check if that process is still running (`ps -p <PID>` or equivalent).
-   - If PID is alive → Warn: "Another SDD process is active. Proceed anyway? (yes/no)"
-   - If PID is dead → Remove stale lock and continue.
-3. If no lock exists → Create `specs/.sdd-lock` with current PID and command name.
-
-### Cross-File Impact Scan
-1. Identify the symbol, string, or pattern that will change.
-2. Run a project-wide grep for that pattern.
-3. Count references:
-   - ≤ 5 references → ✅ Continue
-   - > 5 references → ⚠️ Flag as "Ripple Risk", show user the affected files, ask for confirmation before proceeding.
-
-### String Length Check (for string changes only)
-1. Calculate the length delta: `|new_length - old_length|`
-2. Calculate percentage change: `delta / old_length * 100`
-3. If delta > 20 characters OR percentage increase > 50%:
-   - Flag as "UI Layout Risk"
-   - Check if the string is in a UI component file (`.tsx`, `.vue`, `.jsx`, `.svelte`)
-   - If in UI component → Require explicit user confirmation before proceeding
-4. If the string is in a non-UI file (`.ts` logic, config, etc.) → Allow without flag
-
-## Phase 3: Execute Change
-
-- Make the smallest possible change that satisfies the request.
-- Do NOT touch any file beyond what is strictly necessary.
-- Do NOT create new files.
-- Do NOT refactor or "improve" surrounding code.
-- Do NOT change logic, only what was explicitly requested.
-
-## Phase 4: Verification
-
-### Mandatory Checks
-Run the project's available verification commands. Check `package.json` scripts or equivalent:
-
-1. **Lint**: `npm run lint` (or `pnpm lint`, `yarn lint`, etc.)
-2. **Typecheck**: `npm run typecheck` (or `tsc --noEmit`, `vue-tsc`, etc.)
-
-### Decision Table
+## Architecture: Hybrid CLI + LLM
+
+```
+CLI (0 tokens) → Phase 1a: Keyword scan → PASS/FAIL
+  ↓ (if ambiguous)
+LLM (~50 tokens) → Phase 1b: Context-aware classification
+  ↓
+CLI (0 tokens) → Phase 2: Pre-flight (lock, grep, string delta)
+  ↓
+LLM (~150 tokens) → Phase 3: Edit (full file return for < 500 lines)
+  ↓
+CLI (0 tokens) → Phase 4: Post-flight (actual diff, lint, typecheck, auto-revert)
+  ↓
+CLI (0 tokens) → Phase 5: Atomic ledger append
+```
+
+Total token cost: ~200 tokens (vs ~1000 for all-LLM approach).
+
+## Phase 1: Classification
+
+### Step 1a: CLI Keyword Scan (0 tokens)
+
+Run: `sdd-quick classify "<request>"`
+
+The CLI checks for:
+- Operators: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`, `&&`, `||`, `!`, `?:`
+- Control flow keywords: `if`, `else`, `switch`, `case`, `for`, `while`, `return`, `throw`, `try`, `catch`, `finally`
+- Contract path patterns: `**/api/**`, `**/dto/**`, `**/schema/**`, `**/types/public-api.ts`
+
+**If CLI detects blocking keywords → FAIL immediately.** Output:
+```
+aborted: Quick fix rejected — <slug>
+reason: Request contains <operator/keyword> which indicates a logic change.
+suggestion: Run `/sdd-propose "<request>"` for full workflow.
+```
+
+**If CLI detects no blocking keywords → proceed to Step 1b only if a file path was provided and the file exists.**
+
+### Step 1b: Context-Aware Classification (~50 tokens, only if needed)
+
+If the CLI found ambiguous keywords but a file path was provided, run:
+```
+sdd-quick classify "<request>" <file-path>
+```
+
+The CLI returns a prompt. Send this prompt to the LLM and get back a classification result.
+
+**If LLM says `{"safe": false}` → FAIL.** Report reason and suggest `/sdd-propose`.
+**If LLM says `{"safe": true}` → proceed to Phase 2.**
+
+## Phase 2: Pre-Flight Checks (CLI, 0 tokens)
+
+Run: `sdd-quick preflight "<request>" [file-path] [old-string] [new-string]`
+
+The CLI checks:
+1. **Lock file**: Is another SDD process active? If yes → FAIL.
+2. **Cross-file scan**: How many files reference the pattern? If > 5 → WARN (show user, ask confirmation).
+3. **String length delta**: If old/new strings provided, check delta > 20 chars or > 50% increase → WARN (UI layout risk).
+
+**If preflight FAILS → abort.**
+**If preflight PASSES → proceed to Phase 3.**
+**If preflight WARNS → show user, ask "Proceed? (yes/no)".**
+
+Before proceeding, acquire lock:
+```
+sdd-quick lock acquire "sdd-quick" "<slug>"
+```
+
+## Phase 3: Edit (LLM, ~150 tokens)
+
+### Step 3a: Generate Edit Prompt
+
+Run: `sdd-quick edit-prompt "<request>" <file-path>`
+
+The CLI reads the file and generates an optimized prompt:
+- If file < 500 lines → "Return the ENTIRE file content with the change applied."
+- If file >= 500 lines → "Use search-replace blocks: <<<SEARCH ... >>> <<<REPLACE ... >>>"
+
+### Step 3b: Apply Edit
+
+1. **Backup the file**: Copy to `<file>.sdd-quick-backup`
+2. **Send the prompt to LLM** and get the response.
+3. **Write the response** to the target file.
+   - For full-file return: write directly.
+   - For search-replace blocks: parse and apply each block.
+4. **If write fails** (parse error, etc.) → restore from backup, FAIL.
+
+## Phase 4: Post-Flight Verification (CLI, 0 tokens)
+
+### Step 4a: Verify Actual Changes
+
+Run: `sdd-quick postflight <backup-path> <target-path>`
+
+The CLI checks:
+- Was the file actually changed? If no → FAIL (nothing to commit).
+- Did the LLM add extra lines beyond the request? If > 3 extra lines → AUTO-REVERT, FAIL.
+
+### Step 4b: Run Lint and Typecheck
+
+Run: `sdd-quick lint`
+Run: `sdd-quick typecheck`
+
+**Decision table:**
+
 | Result | Action |
 |--------|--------|
-| Both pass | ✅ Continue to Phase 5 |
-| Lint fails | ❌ Auto-revert all changes, report failure |
-| Typecheck fails | ❌ Auto-revert all changes, report failure |
-| Test fails (if run) | ⚠️ Check if failure is pre-existing or caused by this change. If caused by this change → auto-revert. If pre-existing → allow with warning. |
-
-If the project has NO lint or typecheck script → ❌ Reject, suggest `/sdd-propose` (project lacks safety net for quick changes).
+| Both pass | Continue to Phase 5 |
+| Lint fails | Auto-revert from backup, FAIL |
+| Typecheck fails | Auto-revert from backup, FAIL |
+| Neither available | WARN (project lacks safety net), continue |
 
-## Phase 5: Atomic Ledger Append
+### Step 4c: Cleanup
 
-Do NOT create individual files per change. Append to a single ledger file.
+- Remove backup file.
+- Release lock: `sdd-quick lock release`
 
-### Ledger File: `specs/QUICKFIX_LOG.md`
+## Phase 5: Ledger Append (CLI, 0 tokens)
 
-Format for each entry:
+Run: `sdd-quick ledger append "<entry>"`
 
+Entry format:
 ```markdown
 ## YYYY-MM-DD HH:MM — <kebab-case-slug>
 
 - **Trigger:** `/sdd-quick "<original request>"`
 - **Files:** `<file-path>` (L<line>, L<line>)
 - **Type:** Cosmetic | Config
-- **Verification:** `npm run lint` passed, `npm run typecheck` passed
-- **Cross-file refs:** <count> files affected (list if > 3)
+- **Verification:** lint passed, typecheck passed
+- **Cross-file refs:** <count> files affected
 - **Status:** ✅ Applied | ❌ Reverted (reason)
 ```
 
-### Atomic Write Procedure
-1. Read current content of `specs/QUICKFIX_LOG.md` (create if not exists, with header `# Quick Change Log`)
-2. Append new entry at the END of the file
-3. Write to temp file: `specs/QUICKFIX_LOG.md.tmp`
-4. Atomic rename: replace `specs/QUICKFIX_LOG.md` with temp file
-5. Remove `specs/.sdd-lock`
+The CLI handles atomic write (via temp file + rename) and automatic archiving if ledger exceeds 50 entries.
+
+## Execution Mode: Silent
+
+Do NOT report intermediate steps. Do NOT narrate your process.
+All Phase 1-4 checks must be performed silently via CLI calls.
+
+Output ONLY the final result in the format below.
+No chain of thought. No step-by-step. No "I'm now checking X".
 
-### Ledger Maintenance
-If the ledger exceeds 50 entries:
-- Move the oldest 25 entries to `specs/QUICKFIX_LOG_ARCHIVE.md`
-- Keep only the most recent 25 entries in the main ledger
+If a gate fails → output ONLY the abort message.
+If all gates pass → output ONLY the success message.
 
 ## Anti-Generic Gate
 
 Before final output, verify:
 
-- [ ] Change type was classified using deterministic rules, not AI judgment.
+- [ ] Classification was done via CLI (not AI judgment).
 - [ ] Lock file was checked and cleaned up.
-- [ ] Cross-file scan was performed.
-- [ ] Lint and typecheck were run and passed.
-- [ ] Ledger was updated atomically.
+- [ ] Pre-flight checks passed (or user confirmed warnings).
+- [ ] Edit was applied and post-flight verification passed.
+- [ ] Lint and typecheck were run (or project lacks them).
+- [ ] Ledger was updated atomically via CLI.
 - [ ] No logic, contract, or new files were touched.
+- [ ] No extra lines were added beyond the requested change.
 
 If any item fails, report the failure and do not claim success.
 
 ## Output
 
-End with:
+If successful:
 
 ```markdown
 changed: Quick fix applied — <slug>