ai-core-framework 0.1.0

package/core/rules/01-git-workflow.md

@@ -0,0 +1,388 @@
+# 🔒 RULE 01: Git Workflow (Strict)
+
+> **Non-negotiable git discipline** for this project.
+> Enforced by: pre-commit hooks + CI + agent rules.
+
+---
+
+## 🎯 Branching Strategy: GitHub Flow + Release branches
+
+Small Agile team (2-5 people). Use **GitHub Flow** (simpler than Git Flow) with release branches for production releases.
+
+### Branches
+
+```
+main           ← production (stable, tagged releases)
+  ↑
+develop        ← integration (latest features, passing CI)
+  ↑
+feature/*      ← individual work (branched from develop)
+bugfix/*       ← bug fixes in sprint (branched from develop)
+hotfix/*       ← emergency production fixes (branched from main)
+release/*      ← release preparation (branched from develop)
+chore/*        ← non-code: docs, deps, config
+refactor/*     ← code cleanup, no behavior change
+```
+
+### Flow
+
+```
+Normal feature:
+  develop → feature/TICKET-XXX → PR → merge to develop → release/vX.Y.Z → main
+
+Hotfix:
+  main → hotfix/TICKET-XXX → PR → merge to main → cherry-pick to develop
+```
+
+---
+
+## 🔒 Rules
+
+### RULE GIT-001: Branch naming strict
+
+**Format**: `<type>/TICKET-<number>-<slug>`
+
+Regex: `^(feature|bugfix|hotfix|chore|refactor|release)/(TICKET-\d+-[a-z0-9-]+|v\d+\.\d+\.\d+)$`
+
+**Examples**:
+- ✅ `feature/TICKET-042-password-reset`
+- ✅ `bugfix/TICKET-089-login-500`
+- ✅ `hotfix/TICKET-101-payment-crash`
+- ✅ `chore/TICKET-050-upgrade-node-20`
+- ✅ `release/v1.2.0`
+- ❌ `my-branch`
+- ❌ `TICKET-042` (missing type prefix)
+- ❌ `feature/password-reset` (missing TICKET-XXX)
+- ❌ `Feature/TICKET-042-X` (uppercase)
+- ❌ `feature/TICKET-042-password_reset` (underscore instead of dash)
+
+**Slug rules**:
+- lowercase only
+- kebab-case (dash separator)
+- ≤ 50 chars
+- Descriptive (not `fix-thing`)
+
+### RULE GIT-002: Protected branches
+
+**MUST NOT** direct push to:
+- `main`
+- `master`
+- `develop`
+- `release/*`
+- `staging`
+- `production`
+
+Changes to protected branches MUST go through PR only.
+
+**Enforced by**: GitHub branch protection + local pre-push hook.
+
+### RULE GIT-003: Conventional Commits
+
+**Format**:
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types** (allowed):
+- `feat`: new feature
+- `fix`: bug fix
+- `docs`: documentation only
+- `style`: formatting (no code change)
+- `refactor`: code cleanup (no feature, no bug fix)
+- `perf`: performance improvement
+- `test`: adding/modifying tests
+- `chore`: maintenance (deps, config)
+- `build`: build system changes
+- `ci`: CI pipeline changes
+- `revert`: revert previous commit
+
+**Scope**: `TICKET-XXX` or module name. Required.
+
+**Subject**:
+- Imperative mood: "add", "fix", not "added", "fixes"
+- Lowercase first letter
+- No period at end
+- ≤ 72 chars
+
+**Examples**:
+- ✅ `feat(TICKET-042): add password reset endpoint`
+- ✅ `fix(TICKET-089): handle null email in login`
+- ✅ `refactor(auth): extract token validation to middleware`
+- ✅ `docs(TICKET-050): update API docs for v2 endpoints`
+- ❌ `Added password reset` (no type, capitalized)
+- ❌ `feat: stuff` (no scope, vague)
+- ❌ `feat(TICKET-042): Add password reset.` (capital, period)
+
+### RULE GIT-004: Commit body for complex changes
+
+If commit changes > 50 lines or touch > 3 files, **MUST** include a body explaining WHY, not only WHAT.
+
+Format:
+```
+feat(TICKET-042): add password reset endpoint
+
+Implements password reset flow with email verification:
+- New endpoint: POST /auth/reset-password
+- Rate limiting: 5 req/hour/email
+- Token: crypto.randomBytes(32), 24h expiration
+- Email: HTML template with reset link
+
+Decisions:
+- Using JWT instead of DB session (stateless, horizontal scale)
+- SendGrid chosen over AWS SES (team familiarity)
+
+Refs: ADR-0012
+Closes: TICKET-042
+```
+
+### RULE GIT-005: Atomic commits
+
+1 commit = 1 logical change. 
+
+**MUST NOT**:
+- Mix feature + refactor
+- Mix 2 features
+- Commit partial work called "WIP" (squash before push to shared branches)
+- Commit broken code (must at least compile, preferably tests pass)
+
+**SHOULD**:
+- Separate commits for tests vs implementation (TDD)
+- Separate refactor commits
+
+### RULE GIT-006: No force push to shared
+
+**MUST NOT** `git push --force` to:
+- Any branch someone else collaborates on
+- `main`, `develop`, release branches
+
+**MAY** force push to own feature branch pre-review.
+
+**Use `--force-with-lease`** instead of `--force` to avoid overwriting others work.
+
+### RULE GIT-007: Keep branches short-lived
+
+Feature branches **SHOULD** merge within ≤ 5 days.
+
+If > 5 days:
+- Sync with develop daily (`git rebase develop` or `git merge develop`)
+- Consider splitting ticket
+- Flag in standup
+
+Rule enforced by: `/branch-status` flag stale branches.
+
+### RULE GIT-008: Squash merge strategy
+
+PR merge strategy: **Squash and merge** (default).
+
+Reasons:
+- Clean develop/main history
+- 1 ticket = 1 commit in history
+- Easier revert
+
+**Exception**: Release PRs use merge commits (preserve history).
+
+**Squash commit message format**:
+```
+<type>(TICKET-XXX): <PR title> (#<PR-number>)
+
+<PR description summary>
+
+Refs: ADR-XXXX (if any)
+Closes: TICKET-XXX
+```
+
+### RULE GIT-009: Delete branch after merge
+
+Merged feature/bugfix branches **MUST** be deleted (local + remote).
+
+Auto via GitHub setting: "Automatically delete head branches".
+
+Local cleanup: `/cleanup-branches` (weekly).
+
+### RULE GIT-010: No sensitive data
+
+**MUST NEVER** commit:
+- API keys, tokens
+- Passwords (including in tests)
+- Private keys (`.pem`, `.key`, `.ppk`)
+- `.env` files with real values
+- Customer PII
+- Internal URLs with credentials embedded
+
+**Pre-commit hook scans for patterns**:
+```
+pattern                           | action
+----------------------------------|----------
+[a-z0-9]{32,}                    | warn (might be token)
+api[_-]?key\s*[:=]               | block
+password\s*[:=]\s*['"](?!mock)   | block
+AKIA[A-Z0-9]{16}                 | block (AWS key)
+-----BEGIN .* PRIVATE KEY        | block
+```
+
+**If accidentally committed**:
+1. **IMMEDIATELY** rotate the secret
+2. Remove from history: `git filter-repo` or BFG
+3. Force push (coordinate with team)
+4. Post-mortem: add pattern to pre-commit hook
+
+### RULE GIT-011: Sign commits (if configured)
+
+If project has GPG signing enabled:
+- **MUST** sign all commits
+- CI rejects unsigned commits
+- See `docs/git-signing-setup.md`
+
+Optional for projects not yet set up.
+
+### RULE GIT-012: No merge commits in feature branch
+
+**MUST** use rebase, or merge from develop, never from feature, to sync.
+
+**MUST NOT**:
+```
+# BAD
+git checkout feature/TICKET-042
+git merge feature/TICKET-043   # ❌ merging another feature
+```
+
+**OK**:
+```
+# Good: sync with develop
+git checkout feature/TICKET-042
+git rebase develop
+# or
+git merge develop
+```
+
+### RULE GIT-013: PR requirements
+
+Every PR **MUST**:
+- [ ] Link ticket (auto from branch name)
+- [ ] Pass all CI checks
+- [ ] Have ≥1 approval from tech-lead
+- [ ] Coverage ≥ 80% diff
+- [ ] All review comments resolved
+- [ ] No merge conflicts
+- [ ] Filled PR template
+
+See `templates/pr/pull-request-template.md`.
+
+### RULE GIT-014: Release tagging
+
+Release tags **MUST** follow SemVer: `v<major>.<minor>.<patch>`.
+
+**When to bump**:
+- **Major**: Breaking API change
+- **Minor**: New feature, backward compatible
+- **Patch**: Bug fix, backward compatible
+
+Examples:
+- `v1.0.0` - first stable release
+- `v1.1.0` - added feature
+- `v1.1.1` - fixed bug
+- `v2.0.0` - breaking change
+
+**Tag format**: Annotated tags with message:
+```bash
+git tag -a v1.2.0 -m "Release v1.2.0: Password reset + rate limiting"
+```
+
+### RULE GIT-015: Gitignore hygiene
+
+`.gitignore` **MUST** include:
+- Build artifacts (`dist/`, `build/`, `*.pyc`)
+- Dependencies (`node_modules/`, `venv/`, `.env`)
+- IDE files (`.vscode/`, `.idea/` - except shared settings)
+- OS files (`.DS_Store`, `Thumbs.db`)
+- Logs (`*.log`)
+- Local configs (`.env.local`, `.env.*.local`)
+
+**MUST NOT** ignore:
+- `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` (commit lockfiles)
+- `requirements.txt`, `Pipfile.lock`, `poetry.lock`
+- CI config files (`.github/`, `.gitlab-ci.yml`)
+
+---
+
+## 🔧 Pre-commit Hooks (recommended)
+
+Setup in `.githooks/pre-commit`:
+
+```bash
+#!/bin/bash
+set -e
+
+# 1. Lint check
+npm run lint --silent || { echo "Lint failed"; exit 1; }
+
+# 2. Type check (if TS)
+npm run typecheck --silent || { echo "Type check failed"; exit 1; }
+
+# 3. Run tests on changed files
+npm run test:changed --silent || { echo "Tests failed"; exit 1; }
+
+# 4. Scan for secrets
+git diff --cached | grep -iE "(api[_-]?key|password|token|secret)\s*[:=]\s*['\"][^'\"]{8,}" && {
+  echo "❌ Possible secret detected in diff"
+  exit 1
+} || true
+
+# 5. Validate commit message (if using commit-msg hook)
+# See .githooks/commit-msg
+```
+
+## 🔧 Commit-msg Hook
+
+```bash
+#!/bin/bash
+commit_msg=$(cat "$1")
+
+# Conventional commits regex
+pattern='^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\([a-zA-Z0-9_-]+\))?: .{1,72}$'
+
+if ! echo "$commit_msg" | head -1 | grep -qE "$pattern"; then
+  echo "❌ Commit message doesn't follow Conventional Commits format"
+  echo "Expected: <type>(scope): <subject>"
+  echo "Example: feat(TICKET-042): add password reset endpoint"
+  exit 1
+fi
+```
+
+---
+
+## 🚨 Violation Consequences
+
+### Minor violations (warning)
+- Typo in commit message → amend
+- Branch name slightly wrong → rename before PR
+
+### Major violations (block)
+- Direct push to main → blocked by GitHub protection
+- Secrets committed → CI block, rotate secret, rewrite history
+- Missing tests → PR blocked by CI
+- Force push to shared branch → escalate to tech-lead
+
+---
+
+## 💡 Common Issues & Fixes
+
+| Issue | Fix |
+|-------|-----|
+| Merge conflict | `git rebase develop`, resolve, `git rebase --continue` |
+| Committed to wrong branch | `git reset HEAD~N`, `git stash`, checkout correct branch, `git stash pop` |
+| Committed secret | Revoke NOW, `git filter-repo`, force push, post-mortem |
+| Typo in commit message | `git commit --amend` (if not pushed) |
+| Forgot ticket in branch name | Rename: `git branch -m new-name` |
+| Long-lived branch gone stale | `git rebase develop`, resolve conflicts incrementally |
+
+---
+
+**Version**: 1.0.0
+**Last updated**: 2026-04-18
+**Maintainer**: Tech Lead
+**Next review**: End of each sprint

package/core/rules/02-code-quality.md

@@ -0,0 +1,77 @@
+# 🔒 RULE 02: Code Quality
+
+> Applies to all production code, tests, scripts, and configuration changes. Quality gates are blocking unless explicitly labeled as advisory.
+
+---
+
+## 🎯 Core Principle
+
+Code must be understandable, maintainable, testable, and safe to evolve. Passing tests alone is not sufficient.
+
+## 🔒 Rules
+
+### RULE CQ-001: Small cohesive units
+Functions SHOULD be under 50 lines and files SHOULD be under 500 lines. If exceeded, document why or refactor.
+
+### RULE CQ-002: Complexity limit
+Cyclomatic complexity MUST NOT exceed the configured threshold in `config/project-config.yaml`, default 10.
+
+### RULE CQ-003: Clear naming
+Names MUST describe intent. Avoid vague names such as `data`, `thing`, `stuff`, `tmp`, except for narrow local use.
+
+### RULE CQ-004: No dead code
+Production changes MUST NOT introduce commented-out code, unused exports, unused variables, or unreachable branches.
+
+### RULE CQ-005: Error handling required
+External calls, parsing, IO, database access, and network calls MUST handle failure paths explicitly.
+
+### RULE CQ-006: Type safety
+Typed projects MUST NOT use unsafe escapes such as `any`, unchecked casts, or ignored compiler errors without a ticket reference and justification.
+
+### RULE CQ-007: Logging discipline
+Logs MUST be useful, structured where possible, and free of secrets or PII. Debug logs MUST NOT be committed unless guarded and justified.
+
+### RULE CQ-008: Dependency discipline
+New dependencies MUST have a purpose, license check, security check, and version pin. Prefer existing project dependencies.
+
+### RULE CQ-009: Public interface stability
+Changes to public APIs MUST preserve backward compatibility or document breaking change impact and migration path.
+
+### RULE CQ-010: CI green is mandatory
+Lint, format, type check, test, and security gates configured for the project MUST pass before review and merge.
+
+## ✅ Examples
+
+Good:
+
+- Small function with single responsibility.
+- Explicit error handling with actionable messages.
+- Tests covering edge cases.
+- Dependency added with reason and audit result.
+
+Bad:
+
+- Large function mixing validation, business logic, and IO.
+- Swallowing errors with empty catch blocks.
+- `TODO` without `TICKET-XXX`.
+- Adding library for a trivial helper.
+
+## 🛠️ Enforcement
+
+- Agent self-review during `/implement-task`.
+- Tech Lead review during `/techlead-review`.
+- Hooks in `.githooks/pre-commit`.
+- CI workflow in `.github/workflows/ci.yml`.
+
+## 🚨 Failure Modes
+
+If quality fails:
+
+1. Keep ticket in current state.
+2. Document failed gate.
+3. Fix root cause.
+4. Re-run tests and validation.
+5. Re-request review only after gates pass.
+
+**Version**: 1.0.0
+**Owner**: Tech Lead

package/core/rules/03-security.md

@@ -0,0 +1,78 @@
+# 🔒 RULE 03: Security
+
+> Security rules apply to every agent, command, and code change. Security gates outrank delivery speed.
+
+---
+
+## 🎯 Core Principle
+
+Protect users, data, infrastructure, and secrets by default. If security impact is unclear, escalate to Tech Lead before implementation.
+
+## 🔒 Rules
+
+### RULE SEC-001: No secrets in repository
+MUST NOT commit tokens, passwords, private keys, certificates, `.env` files, customer data, or production credentials.
+
+### RULE SEC-002: Least privilege
+New permissions, scopes, IAM policies, database grants, and API keys MUST use least privilege and documented purpose.
+
+### RULE SEC-003: Input validation
+All external input MUST be validated at trust boundaries, including HTTP requests, jobs, webhooks, CLI args, uploaded files, and third-party payloads.
+
+### RULE SEC-004: Authentication and authorization
+Protected operations MUST check both authentication and authorization. Do not rely on frontend hiding or route naming.
+
+### RULE SEC-005: Sensitive data handling
+PII, credentials, tokens, payment data, and confidential business data MUST be minimized, encrypted where required, and never logged.
+
+### RULE SEC-006: Dependency security
+New or upgraded dependencies MUST be audited. High or critical vulnerabilities block merge unless formally accepted with mitigation.
+
+### RULE SEC-007: OWASP review
+User-facing and API changes MUST be checked against relevant OWASP Top 10 risks: injection, broken auth, access control, crypto failures, SSRF, XSS, insecure design, and logging/monitoring gaps.
+
+### RULE SEC-008: Secure defaults
+Features MUST default to safe behavior. Feature flags, debug modes, permissive CORS, public buckets, or relaxed auth MUST NOT be enabled by default.
+
+### RULE SEC-009: Auditability
+Security-relevant actions SHOULD emit audit events without sensitive payloads.
+
+### RULE SEC-010: Incident escalation
+Suspected data exposure, credential leak, production compromise, or auth bypass MUST trigger immediate escalation and likely `/hotfix`.
+
+## ✅ Examples
+
+Good:
+
+- Password reset endpoint returns generic response for unknown email.
+- API checks ownership before returning resource.
+- Tokens are stored hashed or encrypted based on use case.
+- Logs include request ID, not raw token.
+
+Bad:
+
+- `console.log(req.headers.authorization)`.
+- Admin endpoint protected only by hidden UI.
+- S3 bucket opened publicly for quick test.
+- Dependency added despite critical CVE.
+
+## 🛠️ Enforcement
+
+- Pre-commit secret scanning.
+- CI secret/dependency/SAST scans.
+- Tech Lead security review.
+- QA negative tests for auth and access control.
+
+## 🚨 Failure Modes
+
+If security gate fails:
+
+1. Stop delivery.
+2. Document risk and affected files.
+3. Remove or mitigate issue.
+4. Rotate exposed credentials if needed.
+5. Add regression test or scanning rule.
+6. Resume only after Tech Lead approval.
+
+**Version**: 1.0.0
+**Owner**: Tech Lead / Security Reviewer

package/core/rules/04-documentation.md

@@ -0,0 +1,72 @@
+# 🔒 RULE 04: Documentation
+
+> Documentation is part of the deliverable. Undocumented behavior is unfinished behavior.
+
+---
+
+## 🎯 Core Principle
+
+Anyone maintaining or using the system should understand what changed, how to run it, how to test it, and how to recover from failure.
+
+## 🔒 Rules
+
+### RULE DOC-001: Public APIs documented
+Public functions, classes, CLI commands, endpoints, events, and packages MUST document purpose, inputs, outputs, errors, and examples.
+
+### RULE DOC-002: README stays current
+If setup, scripts, environment variables, architecture, or developer workflow changes, the relevant README MUST be updated in the same PR.
+
+### RULE DOC-003: ADR for architecture decisions
+Major architecture decisions MUST have an ADR covering context, decision, alternatives, consequences, and rollback considerations.
+
+### RULE DOC-004: Changelog for user-visible change
+Features, bug fixes, breaking changes, migrations, and operational changes SHOULD be reflected in changelog or release notes.
+
+### RULE DOC-005: Runbooks for operations
+Deployments, rollbacks, migrations, incident response, and recurring operations MUST have runbook steps when applicable.
+
+### RULE DOC-006: Comments explain why
+Inline comments SHOULD explain non-obvious reasoning, constraints, or tradeoffs. Do not comment obvious syntax.
+
+### RULE DOC-007: Examples must be safe
+Documentation examples MUST NOT include real secrets, customer data, internal-only hostnames, or misleading insecure patterns.
+
+### RULE DOC-008: Generated docs are marked
+Generated docs MUST identify source and generation command to avoid manual drift.
+
+### RULE DOC-009: Docs are testable where possible
+Commands and examples SHOULD be copy-pasteable and verified during review.
+
+### RULE DOC-010: Outdated docs block release
+Known misleading docs for changed behavior MUST be fixed before release.
+
+## ✅ Required Documentation by Change Type
+
+| Change type | Required docs |
+|-------------|---------------|
+| New API | API reference, examples, error cases |
+| Setup change | README and env example |
+| Architecture decision | ADR |
+| Migration | Runbook and rollback notes |
+| User-visible feature | Release notes and help docs if applicable |
+| Hotfix | Incident summary and follow-up ticket |
+
+## 🛠️ Enforcement
+
+- Developer checklist in `/implement-task`.
+- PR template in `core/templates/pr/`.
+- Tech Lead review.
+- Release checklist in `/release`.
+- `bash scripts/validate-docs.sh` blocks missing documentation evidence in CI and pre-commit.
+- DONE tickets require machine-readable `dod_checklist`, documentation paths, and QA evidence where applicable.
+
+## 🚨 Failure Modes
+
+If docs are missing:
+
+1. Keep PR in review.
+2. Add docs or create explicit follow-up only for non-blocking internal gaps.
+3. Re-run review checklist.
+
+**Version**: 1.0.0
+**Owner**: Tech Lead + Scrum Master