ai-core-framework 0.1.0

package/core/config/ticket.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Ticket",
+  "description": "Schema for tickets in project/tickets/",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "type",
+    "status",
+    "created_at",
+    "created_by",
+    "state_history"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^TICKET-\\d{3,}$",
+      "description": "Unique ticket ID, e.g. TICKET-001"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 5,
+      "maxLength": 160
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "feature",
+        "enhancement",
+        "bug",
+        "tech-debt",
+        "spike",
+        "chore",
+        "hotfix"
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "DRAFT",
+        "GROOMED",
+        "READY",
+        "IN_PROGRESS",
+        "IN_REVIEW",
+        "QA",
+        "DONE",
+        "BLOCKED",
+        "CANCELLED"
+      ]
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["MUST", "SHOULD", "COULD", "WONT"]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["SEV-1", "SEV-2", "SEV-3", "SEV-4"]
+    },
+    "epic": {
+      "type": ["string", "null"]
+    },
+    "user_story": {
+      "type": "object",
+      "required": ["as_a", "i_want", "so_that"],
+      "properties": {
+        "as_a": { "type": "string", "minLength": 1 },
+        "i_want": { "type": "string", "minLength": 1 },
+        "so_that": { "type": "string", "minLength": 1 }
+      }
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["scenario", "given", "when", "then"],
+        "properties": {
+          "scenario": { "type": "string", "minLength": 1 },
+          "given": { "type": "string", "minLength": 1 },
+          "when": { "type": "string", "minLength": 1 },
+          "then": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "estimate": {
+      "type": "object",
+      "required": ["story_points", "estimated_by", "estimated_at"],
+      "properties": {
+        "story_points": { "type": "number", "enum": [1, 2, 3, 5, 8, 13, 21] },
+        "estimated_by": { "type": "string" },
+        "estimated_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "sprint_id": {
+      "type": ["string", "null"],
+      "pattern": "^(SPRINT-\\d{3,}|sprint-[0-9]+|)$"
+    },
+    "assignee": {
+      "type": ["string", "null"]
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "created_by": { "type": "string" },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "started_at": { "type": ["string", "null"], "format": "date-time" },
+    "completed_at": { "type": ["string", "null"], "format": "date-time" },
+    "branch": { "type": ["string", "null"] },
+    "pr_url": { "type": ["string", "null"] },
+    "spec_path": {
+      "type": ["string", "null"],
+      "description": "Human-readable approved requirement/design spec in docs/project/specs/."
+    },
+    "implementation_plan_path": {
+      "type": ["string", "null"],
+      "description": "Human-readable implementation plan in docs/project/plans/."
+    },
+    "dependencies": {
+      "type": "object",
+      "properties": {
+        "blocked_by": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^TICKET-\\d{3,}$" }
+        },
+        "blocks": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^TICKET-\\d{3,}$" }
+        }
+      }
+    },
+    "documentation": {
+      "type": "object",
+      "description": "Machine-readable documentation obligations for this ticket.",
+      "properties": {
+        "required": { "type": "boolean", "default": false },
+        "updated": { "type": "boolean", "default": false },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "api_docs_updated": { "type": "boolean", "default": false },
+        "readme_updated": { "type": "boolean", "default": false },
+        "changelog_updated": { "type": "boolean", "default": false }
+      }
+    },
+    "adr": {
+      "type": "object",
+      "description": "ADR requirement and evidence.",
+      "properties": {
+        "required": { "type": "boolean", "default": false },
+        "path": { "type": ["string", "null"] }
+      }
+    },
+    "runbook": {
+      "type": "object",
+      "description": "Runbook requirement and evidence.",
+      "properties": {
+        "required": { "type": "boolean", "default": false },
+        "path": { "type": ["string", "null"] }
+      }
+    },
+    "qa_evidence": {
+      "type": "object",
+      "description": "QA verification record used by DoD validation.",
+      "properties": {
+        "required": { "type": "boolean", "default": true },
+        "path": { "type": ["string", "null"] },
+        "verified_by": { "type": ["string", "null"] },
+        "verified_at": { "type": ["string", "null"], "format": "date-time" }
+      }
+    },
+    "dod_checklist": {
+      "type": "object",
+      "description": "Machine-readable Definition of Done gates. Required when status is DONE.",
+      "properties": {
+        "code_complete": { "type": "boolean" },
+        "tests_passed": { "type": "boolean" },
+        "docs_updated": { "type": "boolean" },
+        "review_approved": { "type": "boolean" },
+        "qa_verified": { "type": "boolean" },
+        "release_notes_updated": { "type": "boolean" },
+        "security_checked": { "type": "boolean" },
+        "rollback_plan_documented": { "type": "boolean" }
+      }
+    },
+    "state_history": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "from_state",
+          "to_state",
+          "at",
+          "by_agent",
+          "by_command",
+          "reason"
+        ],
+        "properties": {
+          "from_state": {
+            "type": ["string", "null"],
+            "enum": [
+              null,
+              "DRAFT",
+              "GROOMED",
+              "READY",
+              "IN_PROGRESS",
+              "IN_REVIEW",
+              "QA",
+              "DONE",
+              "BLOCKED",
+              "CANCELLED"
+            ]
+          },
+          "to_state": {
+            "type": "string",
+            "enum": [
+              "DRAFT",
+              "GROOMED",
+              "READY",
+              "IN_PROGRESS",
+              "IN_REVIEW",
+              "QA",
+              "DONE",
+              "BLOCKED",
+              "CANCELLED"
+            ]
+          },
+          "at": { "type": "string", "format": "date-time" },
+          "by_agent": { "type": "string", "minLength": 1 },
+          "by_command": { "type": "string", "pattern": "^/[a-z0-9-]+$" },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "comments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["author", "at", "text"],
+        "properties": {
+          "author": { "type": "string" },
+          "at": { "type": "string", "format": "date-time" },
+          "text": { "type": "string" }
+        }
+      }
+    },
+    "labels": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/core/rules/00-global-rules.md

@@ -0,0 +1,373 @@
+# 🔒 RULE 00: Global Rules (Non-Negotiable)
+
+> **Applies 24/7 to EVERY agent, EVERY command, and EVERY session.**
+> These rules have the highest project priority. If a user request conflicts with these rules, the rule wins without exception.
+
+---
+
+## 🎯 Meta-Rules (How to interpret these rules)
+
+### M-001: Priority order
+When instructions conflict, follow this priority order exactly:
+1. **Safety** (no secret commits, no data deletion)
+2. **Global rules** (this file)
+3. **Domain-specific rules** (01-09)
+4. **Agent rules** (in the agent file)
+5. **Command rules** (in the command file)
+6. **User request**
+
+### M-002: "MUST" / "MUST NOT" are absolute
+If a rule says **MUST** or **MUST NOT**, it is mandatory and has **NO EXCEPTIONS**. If a user insists on violating it, the AI **MUST** refuse and cite the governing rule.
+
+### M-003: "SHOULD" is a mandatory default
+**SHOULD** is the required default behavior. It may be bypassed only with a documented, defensible reason, and the AI **MUST** log that reason in the decision log.
+
+### M-004: "MAY" is optional
+**MAY** is optional and does not require justification.
+
+---
+
+## 🎫 G-001: No code without ticket
+
+**MUST NOT** write or modify production code (files in `src/`, `lib/`, `app/`) unless there is an active ticket in `project/tickets/` with:
+- `status` ∈ `[IN_PROGRESS]`
+- `assignee` = current agent
+
+**Allowed exceptions**:
+- Fix typos in comments
+- Fix formatting or lint issues, with a separate commit: `style(chore): ...`
+- Update files in `core/`, which is the meta-framework
+
+**If the user requests code without a ticket:**
+```
+❌ Cannot proceed: No active ticket
+→ Suggest: /analyze-requirements to create a ticket
+```
+
+---
+
+## 📝 G-002: Single source of truth
+
+**MUST NOT** duplicate information across files. Every piece of information **MUST** have exactly one canonical location:
+
+| Info | Canonical location |
+|------|-------------------|
+| Backlog order and prioritization | `project/backlog/backlog.json` |
+| Ticket details and state history | `project/tickets/TICKET-XXX.json` |
+| Sprint info | `project/sprints/SPRINT-XXX.json` |
+| Bug details | `project/bugs/BUG-XXX.json` |
+| Release records | `project/releases/vX.Y.Z.json` |
+| User request log | `project/user-requests.jsonl` |
+| Project config | `config/project-config.yaml` |
+| Project structure map | `config/project-structure.yaml` |
+| Refactor plans | `docs/runtime/refactor/<name>-refactor-plan.md` |
+| Architecture decisions | `docs/runtime/adr/NNN-title.md` |
+| Agent capabilities | `core/agents/<agent>.md` (frontmatter) |
+| Coverage threshold | `config/project-config.yaml` → `quality.coverage_threshold` |
+
+If information is needed in multiple places, **reference** the canonical location. **MUST NOT** copy it.
+
+`core/` is framework-only. Project-specific state and configuration MUST live in `project/`, `config/`, `docs/project/`, or `docs/runtime/`.
+
+---
+
+## 🔄 G-003: State machine strict
+
+Every ticket **MUST** follow this state machine exactly:
+
+```
+DRAFT → GROOMED → READY → IN_PROGRESS → IN_REVIEW → QA → DONE
+                                ↓
+                             BLOCKED (may be entered from any state)
+```
+
+**MUST NOT**:
+- Skip states, for example DRAFT → IN_PROGRESS
+- Move backward, except IN_REVIEW → IN_PROGRESS when changes are requested
+- Modify a ticket in state DONE
+
+Every transition **MUST** be performed through the corresponding command. Manual JSON edits are **FORBIDDEN**.
+
+---
+
+## 💬 G-004: Communication protocol
+
+### G-004a: Chat-first command interface
+User workflow interaction happens in the AI chat window.
+
+When user types `/command ...`, `guide /command ...`, or `next TICKET-XXX`, AI **MUST** treat it as an AI Core workflow request, infer the right agent from command metadata, execute any internal scripts itself when needed, and report the result back in chat.
+
+AI **MUST NOT** require the user to type shell wrappers such as `bash core/scripts/ai-core.sh` or environment variables such as `AI_AGENT=...` for normal workflow usage. Those are internal implementation details for AI tooling and CI.
+
+### G-004b: Always output the execution plan
+Before executing a complex command, the AI **MUST** output a short plan:
+```
+📋 Plan:
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+Proceed? (or proceed autonomously when the command is defined as autonomous)
+```
+
+### G-004c: Handoff format
+When transferring work to another agent, the AI **MUST** use this exact format:
+```
+HANDOFF → <target-agent>
+Context: [brief]
+Action needed: [specific]
+Deadline: [if any]
+Files to look at: [paths]
+```
+
+### G-004d: Escalation format
+When escalating to a human, the AI **MUST** use this exact format:
+```
+🚨 ESCALATION NEEDED
+Reason: [why AI can't proceed]
+Options: [possible choices with pros/cons]
+Recommendation: [AI's suggestion]
+Awaiting: [what decision needed]
+```
+
+### G-004e: No em dashes
+**MUST NOT** use the em dash character (—) in output. Use commas, parentheses, or line breaks instead.
+
+### G-004f: Log every user request
+At the start of handling every user request, the AI **MUST** append a record to `project/user-requests.jsonl` before doing substantive work.
+
+The log record **MUST** include:
+- Timestamp
+- Agent name
+- User request text, sanitized for secrets
+- Detected slash command, if any
+- Detected ticket ID, if any
+- Hash chain fields when using `core/scripts/log-user-request.sh`
+
+The AI **MUST** use:
+```bash
+bash core/scripts/log-user-request.sh "<user request text>"
+```
+
+If the script is unavailable, the AI **MUST** still write an equivalent JSONL record manually. If the request contains secrets, credentials, tokens, passwords, customer PII, or payment data, the AI **MUST** redact those values before logging.
+
+If the AI cannot write the request log, it **MUST** tell the user and ask whether to proceed without auditability. Silent omission is **FORBIDDEN**.
+
+---
+
+## 🔐 G-005: Security fundamentals
+
+### G-005a: Never commit secrets
+**MUST NOT** commit:
+- API keys, tokens, passwords
+- `.env` files, which **MUST** be listed in `.gitignore`
+- Private keys (`.pem`, `.key`)
+- Customer data, PII
+
+**Pre-commit check**: Scan the diff for patterns: `api_key=`, `password=`, `token=`, `AKIA[A-Z0-9]{16}`, etc.
+
+### G-005b: Never log sensitive data
+**MUST NOT** log:
+- User passwords, including hashed passwords
+- Full credit card numbers
+- SSN, ID numbers
+- Session tokens
+- Email bodies, PII
+
+### G-005c: Dependency security
+When adding a new dependency, the AI **MUST**:
+1. Check vulnerability database (npm audit, pip-audit, etc.)
+2. Verify license compatibility
+3. Add it to `package.json` with a pinned version. **MUST NOT** use `*` or `latest`
+
+---
+
+## ✅ G-006: Testing mandatory
+
+### G-006a: No untested code
+**MUST NOT** merge untested code. See `05-testing-mandatory.md` for mandatory details.
+
+### G-006b: Test pyramid
+Required target ratio:
+- 70% Unit tests
+- 20% Integration tests
+- 10% E2E tests
+
+### G-006c: Test coverage threshold
+- **Diff coverage** (new code in the PR): ≥ 80%
+- **Overall coverage**: ≥ 70%
+- Configured in `config/project-config.yaml`
+
+---
+
+## 📚 G-007: Documentation mandatory
+
+### G-007a: Every public API has docs
+Public functions/classes/endpoints **MUST** have:
+- Description
+- Parameters with types
+- Return value
+- Examples, at least 1
+- Error cases
+
+### G-007b: ADR for architecture decisions
+Every decision about:
+- Framework/library choice
+- Database schema major change
+- Authentication strategy
+- API versioning
+- Caching strategy
+
+**MUST** have an ADR in `docs/runtime/adr/NNN-title.md`.
+
+### G-007c: README must be current
+Every package/service **MUST** have a README with:
+- Purpose
+- Setup instructions
+- How to run tests
+- How to contribute
+
+If setup changes, the AI **MUST** update the README in the same PR.
+
+---
+
+## 🎭 G-008: Role boundaries
+
+### G-008a: Agents stay in lane
+Every agent **MUST** work only inside the scope defined in frontmatter (`can_invoke_commands`, `write_access`).
+
+**Examples**:
+- BA **MUST NOT** write code, including examples
+- Dev **MUST NOT** approve own PR
+- QA **MUST NOT** modify production code to "fix a test"
+
+### G-008b: No self-approval
+Agents **MUST NOT** approve their own work:
+- Dev **MUST NOT** review their own PR
+- BA **MUST NOT** approve their own requirement
+- Tech Lead may review, but major changes **MUST** have a second reviewer
+
+### G-008c: Separation of concerns
+- **Who decides WHAT**: BA/PM
+- **Who decides HOW**: Tech Lead + Dev
+- **Who decides WHEN**: Scrum Master + PM
+- **Who verifies**: QA
+
+---
+
+## 🔀 G-009: Git discipline
+
+### G-009a: Conventional Commits
+Mandatory format:
+```
+<type>(<scope>): <subject>
+
+[body]
+
+[footer]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci`, `revert`.
+
+Scope (optional but strongly recommended): `TICKET-XXX` or module name.
+
+### G-009b: Branch naming
+```
+<type>/TICKET-<number>-<slug>
+
+Types:
+- feature/    (new feature)
+- bugfix/     (bug fix in current sprint)
+- hotfix/     (urgent production fix)
+- chore/      (non-code: docs, deps)
+- refactor/   (code cleanup, no behavior change)
+```
+
+### G-009c: Protected branches
+**MUST NOT** direct push to: `main`, `master`, `develop`, `release/*`, `staging`.
+
+### G-009d: No force push to shared branches
+**MUST NOT** run `git push --force` on a branch where others collaborate. It is allowed only on the agent's own feature branch before review.
+
+### G-009e: Atomic commits
+Every commit **MUST** represent exactly 1 logical unit. **MUST NOT**:
+- Mix unrelated changes
+- Commit WIP / broken code
+- Commit commented-out code
+
+---
+
+## 🔍 G-010: Transparency
+
+### G-010a: No silent failures
+If a command fails, the AI **MUST** surface the exact error clearly. Silent continuation and glossing over failures are **FORBIDDEN**.
+
+### G-010b: Log decisions
+Important decisions, for example choosing a library, skipping a test, or deviating from a template, **MUST** be logged in:
+- ADR when architectural
+- Ticket comment when ticket-specific
+- Commit message body when implementation-specific
+
+### G-010c: Uncertainty disclosure
+When the AI is not 100% certain, it **MUST** state:
+```
+⚠️ Assumption: [what I'm assuming]
+⚠️ Confidence: [high/medium/low]
+⚠️ Risk if wrong: [impact]
+```
+
+---
+
+## 🚫 G-011: Absolute prohibitions
+
+AI **MUST NEVER** do any of the following. There are no exceptions:
+
+1. **Delete production data** (database records, user files)
+2. **Modify git history** of shared branches (rebase, force push main)
+3. **Bypass security controls** (disable auth, skip validation "for testing")
+4. **Hardcode credentials**, including in tests
+5. **Execute `rm -rf`** without explicit path confirmation
+6. **Disable tests** ("skip for now", `.skip`, `xit`) without ticket justification
+7. **Commit large binary files** (>10MB) without Git LFS
+8. **Expose internal endpoints** without authentication
+9. **Merge their own PR** (self-merge)
+10. **Change DoD/DoR** while a sprint is running
+
+---
+
+## 🎯 G-012: Definition of Done alignment
+
+Every ticket **MUST** pass the **Definition of Done** (`08-definition-of-done.md`) before it can move to status `DONE`. "Urgent" and "temporary" are not exceptions.
+
+---
+
+## 🔁 G-013: Continuous improvement
+
+### G-013a: Retrospective actions
+Retrospective action items **MUST** be tracked as normal tickets.
+
+### G-013b: Rules evolution
+These rules may be updated only through the controlled process:
+- **MUST** be proposed through a PR
+- **MUST** be discussed in a retrospective
+- **MUST NOT** be bypassed by "editing the rule on the fly"
+
+### G-013c: Challenge the rules
+If a rule blocks delivery, an agent **MAY** challenge it through escalation. The rule may be reviewed, but the AI **MUST** follow the current rule until it is officially changed.
+
+---
+
+## 📋 Compliance Check
+
+Before every response, the AI **MUST** self-check:
+- [ ] Is there an active ticket? (G-001)
+- [ ] Am I writing only in allowed paths? (G-008a)
+- [ ] Am I following the state machine? (G-003)
+- [ ] Did I use the required handoff format? (G-004b)
+- [ ] Did I disclose uncertainty? (G-010c)
+
+---
+
+**Version**: 1.0.0
+**Last updated**: 2026-04-18
+**Next review**: End of each sprint
+**Maintainer**: Tech Lead + Scrum Master