@hanzlaa/rcode 3.6.16 → 4.1.0

package/rihal/agents/rules/executor/task-commit-protocol.md

@@ -1,309 +0,0 @@
-# Rihal Executor: Task Commit Protocol
-
-## Commit Workflow for Each Task
-
-After completing a task's implementation, follow this protocol to atomically commit changes.
-
----
-
-## Step 0: Detect Project Commit Standard (Run Once Per Sprint)
-
-Before writing any commit messages, read the project's commit standard from source — do NOT invent one or ask the user unless nothing is found.
-
-**Check in this order — enforcement configs first, docs last (stop at first hit):**
-
-1. `.git/hooks/commit-msg` — the active enforcement hook (if exists and non-empty, read it to detect the validator)
-2. `.husky/commit-msg` — husky-managed commit hook
-3. `.commitlintrc`, `.commitlintrc.json`, `.commitlintrc.yaml`, `.commitlintrc.js`, `commitlint.config.js`, `commitlint.config.cjs` — commitlint config
-4. `package.json` → `"commitlint"` or `"config.commitizen"` key — commitizen config
-5. `.czrc` — commitizen standalone config
-6. `.github/COMMIT_CONVENTION.md` — explicit doc (lower priority than machine configs)
-7. `CONTRIBUTING.md` — look for a "Commit" or "Git" section (lowest priority)
-
-**If a standard is found:** Use it silently for all commits in this sprint. No need to confirm with user.
-
-**If nothing is found:** Default to Conventional Commits (`type(scope): subject`). Mention the format once in your sprint opening summary — do not ask the user to choose.
-
-**Never ask the user "what commit format do you want?"** — that's noise. Read first, decide, proceed.
-
----
-
-## Step 1: Check Git Status
-```bash
-git status --short
-```
-
-Example output:
-```
-M  src/auth/login.ts
-M  src/types/user.ts
-?? src/auth/refresh.ts
-```
-
-Understand what changed:
-- `M` = Modified file
-- `??` = Untracked (new) file
-- `D` = Deleted file
-
----
-
-## Step 2: Stage Files Individually
-
-**NEVER use `git add .` or `git add -A`**
-
-Stage each file explicitly:
-```bash
-git add src/auth/login.ts
-git add src/types/user.ts
-git add src/auth/refresh.ts
-```
-
-Or for multiple related files:
-```bash
-git add src/auth/
-```
-
-Only stage files changed by this task. If other files were modified (e.g., from previous unrelated work), leave them unstaged.
-
----
-
-## Step 3: Determine Commit Type
-
-Match the change to a conventional commit type:
-
-| Type | When | Example |
-|------|------|---------|
-| `feat` | New feature, endpoint, component | "Add JWT refresh token rotation" |
-| `fix` | Bug fix, error handling | "Fix null check in auth middleware" |
-| `test` | Test file creation/modification | "Add test suite for login flow" |
-| `refactor` | Code improvement (no feature change) | "Extract auth validation to utility" |
-| `chore` | Build, config, deps | "Add prisma migration" |
-| `docs` | Documentation updates | "Document auth strategy" |
-
----
-
-## Step 4: Choose Scope
-
-Scope is the **subsystem or domain** affected, in parentheses — NOT the phase/sprint number.
-
-- `feat(auth)` - authentication feature
-- `fix(payments)` - payments bug fix
-- `test(api)` - API tests
-- `refactor(ui)` - UI code cleanup
-
-**NEVER use a phase or sprint number as the scope.** `fix(114):` or `feat(114-03):` are wrong.
-Use the name of the subsystem the task touches (e.g., `sequence-builder`, `auth`, `dashboard`, `api`).
-If no obvious subsystem exists, omit the scope: `fix: correct delay type in email templates`.
-
----
-
-## Step 5: Single vs Multi-Repo Commits
-
-### Single Repository (Standard)
-```bash
-git commit -m "feat(auth): add JWT refresh token rotation"
-```
-
-Extract and save the commit hash:
-```bash
-HASH=$(git rev-parse HEAD)
-echo "Task committed: $HASH"
-```
-
-### Multiple Repositories (Sub-repos)
-Use the `commit-to-subrepo` tool:
-```bash
-node ".rihal/bin/rihal-tools.cjs" commit-to-subrepo \
-  --repo frontend \
-  --message "feat(ui): redesign login form" \
-  --files src/pages/login.tsx
-```
-
-The tool:
-1. Commits to the sub-repo
-2. Returns the sub-repo commit hash
-3. Then commits a reference in the parent repo
-
-Extract both hashes from response.
-
----
-
-## Step 6: Check Untracked Files
-
-After commit, verify no accidental files were left:
-```bash
-git status --short | grep '^??'
-```
-
-If untracked files appear:
-- **If generated (node_modules, .next, build/):** Add to .gitignore
-- **If intentional:** Stage and commit in a new commit
-- **If accidental:** Delete and update .gitignore
-
-Example:
-```bash
-# Untracked: console.log.tmp
-# Accidental → delete
-rm src/console.log.tmp
-
-# Untracked: src/features/auth.generated.ts
-# Generated code → add to .gitignore
-echo "**/*.generated.ts" >> .gitignore
-```
-
----
-
-## Step 7: Record Task Completion
-
-Track the committed task:
-```javascript
-{
-  taskNumber: 1,
-  taskName: "Task: Implement JWT refresh tokens",
-  commitHash: "a1b2c3d",
-  commitMessage: "feat(auth): add JWT refresh token rotation",
-  filesModified: ["src/auth/login.ts", "src/types/user.ts", "src/auth/refresh.ts"],
-  status: "complete"
-}
-```
-
----
-
-## Common Commit Patterns
-
-### TDD Pattern
-Three commits per task:
-
-1. **Test commit** (RED phase):
-   ```bash
-   git add src/auth.test.ts
-   git commit -m "test(auth): add failing test for password validation"
-   ```
-
-2. **Implementation commit** (GREEN phase):
-   ```bash
-   git add src/auth.ts
-   git commit -m "feat(auth): implement password validation"
-   ```
-
-3. **Refactor commit** (if needed):
-   ```bash
-   git add src/auth.ts
-   git commit -m "refactor(auth): extract validation logic to utility"
-   ```
-
-### Bug Fix Pattern
-```bash
-git add src/component.tsx
-git commit -m "fix(ui): prevent double-click on submit button"
-```
-
-### Multiple File Pattern
-```bash
-git add src/api/auth/route.ts src/lib/jwt.ts src/types/auth.ts
-git commit -m "feat(auth): implement login endpoint with JWT generation"
-```
-
----
-
-## Commit Message Format
-
-All commits must follow Conventional Commits:
-
-```
-<type>(<scope>): <subject>
-
-<body (optional)>
-```
-
-Rules:
-- **Type:** Lowercase (feat, fix, test, refactor, chore, docs)
-- **Scope:** Lowercase, no spaces
-- **Subject:** Imperative mood ("add", not "adds" or "added"), lowercase first letter, NO period at end, under 72 characters
-- **Body:** Explain WHY if needed (not WHAT, commit diff shows that)
-
-Good:
-```
-feat(auth): add JWT refresh token rotation
-fix(payments): handle stripe webhook retries
-refactor(ui): extract form validation to utility
-```
-
-Bad:
-```
-feat(auth): Adds JWT refresh tokens.
-fix: I fixed the payment thing
-Updated auth code
-fix(114): correct delay type       ← phase number as scope — WRONG
-feat(114-03): add drag-and-drop    ← sprint ID as scope — WRONG
-```
-
----
-
-## Multi-Repo Workflow
-
-When plan spans multiple repositories (e.g., frontend + backend):
-
-1. **Per-repo commits:** Commit to each repo separately
-2. **Extract hashes:** Save each repo's commit hash
-3. **Orchestrator commit:** Parent repo records all hashes
-
-Example:
-```bash
-# Frontend repo
-cd frontend
-git add src/pages/login.tsx
-git commit -m "feat(ui): redesign login form"
-FRONTEND_HASH=$(git rev-parse HEAD)
-
-# Backend repo
-cd ../backend
-git add src/routes/auth.ts
-git commit -m "feat(api): add passwordless login endpoint"
-BACKEND_HASH=$(git rev-parse HEAD)
-
-# Parent repo (records cross-repo work)
-cd ..
-git add .planning/phases/01-auth/01-login-SUMMARY.md
-git commit -m "docs(01-auth): complete login feature (frontend: $FRONTEND_HASH, backend: $BACKEND_HASH)"
-```
-
----
-
-## Troubleshooting Commits
-
-### "Committed wrong file"
-1. Don't force-push (violates AGENTS.md rule)
-2. Create a new commit fixing it
-3. Document in task notes
-
-### "Need to split large commit"
-1. Use `git reset HEAD~1` (undoes last commit, leaves changes staged)
-2. Stage part of changes
-3. Commit
-4. Stage remainder
-5. Commit again
-
-### "Forgot to add a file"
-1. Stage the file
-2. Use `git commit --amend` (modifies last commit)
-3. OR create a new commit if last commit already pushed
-
-### Merge conflicts after commit
-1. Pull latest from origin
-2. Resolve conflicts
-3. Create new "fix(merge):" commit documenting resolution
-4. Never force-push
-
----
-
-## Automation Note
-
-The `.rihal/bin/rihal-tools.cjs` provides a `commit` helper:
-
-```bash
-node ".rihal/bin/rihal-tools.cjs" commit "feat(auth): implement login" \
-  --files src/auth.ts src/types/auth.ts
-```
-
-This ensures consistency and can integrate with project hooks.

package/rihal/agents/rules/executor/tdd-flow.md

@@ -1,294 +0,0 @@
-# Rihal Executor: TDD Execution Flow
-
-## Test-Driven Development Phases
-
-For tasks with `tdd="true"`, execute in three phases:
-
----
-
-## Phase 1: RED — Write Failing Tests
-
-**Objective:** Establish expected behavior before implementation.
-
-### Step 1: Create Test File
-Create test file alongside implementation (or in tests/ directory):
-- Implementation: `src/auth.ts` → Test: `src/auth.test.ts` or `tests/auth.spec.ts`
-- Implementation: `src/api/users/route.ts` → Test: `src/api/users/route.test.ts`
-
-### Step 2: Write Test Cases
-From task `<behavior>` block, write tests that define expectations:
-
-Example from task:
-```xml
-<behavior>
-  - Test 1: Valid email returns true
-  - Test 2: Invalid email (no @) returns false
-  - Test 3: Empty string returns false
-</behavior>
-```
-
-Write tests:
-```typescript
-import { validateEmail } from './auth';
-
-describe('validateEmail', () => {
-  it('returns true for valid email', () => {
-    expect(validateEmail('user@example.com')).toBe(true);
-  });
-
-  it('returns false for invalid email (no @)', () => {
-    expect(validateEmail('userexample.com')).toBe(false);
-  });
-
-  it('returns false for empty string', () => {
-    expect(validateEmail('')).toBe(false);
-  });
-});
-```
-
-### Step 3: Verify Tests FAIL
-```bash
-npm test -- --filter=auth
-# Expected: FAILED (function doesn't exist yet)
-```
-
-**CRITICAL:** Tests MUST fail at this point. If they pass, you're not testing anything.
-
-### Step 4: Commit RED
-```bash
-git add src/auth.test.ts
-git commit -m "test({scope}): add failing test for {feature}"
-```
-
-Example:
-```bash
-git commit -m "test(auth): add failing test for email validation"
-```
-
----
-
-## Phase 2: GREEN — Write Minimal Implementation
-
-**Objective:** Make tests pass with minimal code (no over-engineering).
-
-### Step 1: Write Implementation
-Implement ONLY what's needed to pass tests. Resist over-engineering:
-
-```typescript
-// MINIMAL implementation (passes test)
-export function validateEmail(email: string): boolean {
-  return email.includes('@') && email.length > 0;
-}
-
-// NOT this (over-engineered, but test wouldn't catch it)
-export function validateEmail(email: string): boolean {
-  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-  return regex.test(email);
-}
-```
-
-### Step 2: Verify Tests PASS
-```bash
-npm test -- --filter=auth
-# Expected: PASSED
-```
-
-If test fails, fix implementation. Don't change the test.
-
-### Step 3: Commit GREEN
-```bash
-git add src/auth.ts
-git commit -m "feat({scope}): implement {feature}"
-```
-
-Example:
-```bash
-git commit -m "feat(auth): implement email validation"
-```
-
----
-
-## Phase 3: REFACTOR — Clean Up (If Needed)
-
-**Objective:** Improve code quality while keeping tests passing.
-
-Only refactor if:
-- Tests still pass after refactoring
-- Code is genuinely hard to read or maintain
-- No behavior change
-
-Example refactoring:
-```typescript
-// BEFORE (verbose, GREEN state)
-export function validateEmail(email: string): boolean {
-  return email.includes('@') && email.length > 0 && email.indexOf('@') !== 0 && email.indexOf('@') !== email.length - 1;
-}
-
-// AFTER (clearer, still passes test)
-export function validateEmail(email: string): boolean {
-  const hasAtSign = email.includes('@');
-  const notEmpty = email.length > 0;
-  const atNotAtStart = email.indexOf('@') !== 0;
-  const atNotAtEnd = email.indexOf('@') !== email.length - 1;
-  
-  return hasAtSign && notEmpty && atNotAtStart && atNotAtEnd;
-}
-
-// Verify tests still pass
-npm test -- --filter=auth
-# Expected: PASSED
-```
-
-### REFACTOR Commit
-```bash
-git add src/auth.ts
-git commit -m "refactor(auth): clarify email validation logic"
-```
-
-**Skip refactor if:** Tests pass and code is already clear.
-
----
-
-## TDD Workflow Summary
-
-```
-RED PHASE:
-  ├─ Create test file
-  ├─ Write failing tests
-  ├─ Run: npm test → FAIL ✓
-  └─ Commit: test(scope): add failing test
-
-GREEN PHASE:
-  ├─ Write minimal implementation
-  ├─ Run: npm test → PASS ✓
-  ├─ Verify no cheating (all tests pass legitimately)
-  └─ Commit: feat(scope): implement
-
-REFACTOR PHASE (optional):
-  ├─ Improve code clarity
-  ├─ Run: npm test → PASS ✓ (unchanged)
-  └─ Commit: refactor(scope): clean up (or skip)
-```
-
----
-
-## Common TDD Patterns
-
-### API Endpoint (REST)
-```typescript
-// Test
-describe('POST /api/users', () => {
-  it('creates user with valid data', async () => {
-    const response = await fetch('/api/users', {
-      method: 'POST',
-      body: JSON.stringify({ email: 'user@test.com', password: 'Pass123!' })
-    });
-    expect(response.status).toBe(201);
-    const user = await response.json();
-    expect(user.email).toBe('user@test.com');
-  });
-
-  it('returns 400 for invalid email', async () => {
-    const response = await fetch('/api/users', {
-      method: 'POST',
-      body: JSON.stringify({ email: 'invalid', password: 'Pass123!' })
-    });
-    expect(response.status).toBe(400);
-  });
-});
-
-// Implementation (minimal)
-export async function POST(request: Request) {
-  const { email, password } = await request.json();
-
-  if (!email.includes('@')) {
-    return new Response(JSON.stringify({ error: 'Invalid email' }), { status: 400 });
-  }
-
-  const user = await db.users.create({ email, password });
-  return new Response(JSON.stringify(user), { status: 201 });
-}
-```
-
-### React Component
-```typescript
-// Test
-describe('LoginForm', () => {
-  it('calls onSubmit with form data when submitted', async () => {
-    const onSubmit = jest.fn();
-    render(<LoginForm onSubmit={onSubmit} />);
-
-    await userEvent.type(screen.getByPlaceholderText('Email'), 'user@test.com');
-    await userEvent.type(screen.getByPlaceholderText('Password'), 'Pass123!');
-    await userEvent.click(screen.getByText('Login'));
-
-    expect(onSubmit).toHaveBeenCalledWith({ email: 'user@test.com', password: 'Pass123!' });
-  });
-
-  it('disables submit button while submitting', async () => {
-    const onSubmit = jest.fn(() => new Promise(r => setTimeout(r, 100)));
-    render(<LoginForm onSubmit={onSubmit} />);
-
-    await userEvent.type(screen.getByPlaceholderText('Email'), 'user@test.com');
-    await userEvent.click(screen.getByText('Login'));
-
-    expect(screen.getByText('Login')).toBeDisabled();
-  });
-});
-
-// Implementation (minimal)
-export function LoginForm({ onSubmit }: { onSubmit: (data: LoginData) => Promise<void> }) {
-  const [isSubmitting, setIsSubmitting] = useState(false);
-
-  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault();
-    setIsSubmitting(true);
-    const formData = new FormData(e.currentTarget);
-    await onSubmit({
-      email: formData.get('email') as string,
-      password: formData.get('password') as string,
-    });
-    setIsSubmitting(false);
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input name="email" placeholder="Email" required />
-      <input name="password" type="password" placeholder="Password" required />
-      <button disabled={isSubmitting}>Login</button>
-    </form>
-  );
-}
-```
-
----
-
-## Red Flags in TDD
-
-### Test Passes Immediately After Writing
-Problem: Your test doesn't actually test anything.
-Solution: Verify function doesn't exist, or test is checking wrong thing.
-
-### Too Many Tests Failing at Once
-Problem: Can't tell which fix makes which test pass.
-Solution: Write fewer, simpler tests first.
-
-### Implementation Becomes Complex
-Problem: Minimal code is hard to understand.
-Solution: Extract helper functions during refactor phase, keep tests simple.
-
-### Tests Are Brittle
-Problem: Small implementation change breaks many tests.
-Solution: Test behavior, not implementation details. Avoid testing internal state.
-
----
-
-## Skipping Refactor
-
-Refactor phase is optional. Skip if:
-- Code is already clean
-- Tests pass and behavior is correct
-- No repeated logic
-- No naming clarity issues
-
-In most TDD tasks, RED → GREEN is sufficient. REFACTOR adds polish.