ai-core-framework 0.1.0

package/core/templates/project/project-structure.yaml

@@ -0,0 +1,76 @@
+# Project-specific structure map copied by /setup-project into config/project-structure.yaml
+# core remains framework-only. Runtime state and project docs live outside core.
+
+state:
+  root: "project"
+  tickets: "project/tickets"
+  backlog: "project/backlog"
+  bugs: "project/bugs"
+  sprints: "project/sprints"
+  releases: "project/releases"
+  metrics: "project/metrics"
+  views: "project/views"
+  test_runs: "project/test-runs"
+  incidents: "project/incidents"
+  audit_log: "project/audit-log.jsonl"
+
+project_docs:
+  root: "docs/project"
+  product: "docs/project/product"
+  planning: "docs/project/planning"
+  specs: "docs/project/specs"
+  user_stories: "docs/project/user-stories"
+  plans: "docs/project/plans"
+  requirements: "docs/project/requirements"
+  api: "docs/project/api"
+
+runtime_docs:
+  root: "docs/runtime"
+  refactor: "docs/runtime/refactor"
+  adr: "docs/runtime/adr"
+  technical: "docs/runtime/technical"
+  runbooks: "docs/runtime/runbooks"
+  qa: "docs/runtime/qa"
+  test_runs: "docs/runtime/test-runs"
+  verifications: "docs/runtime/verifications"
+  incidents: "docs/runtime/incidents"
+
+backlog:
+  source_of_truth: "project/backlog/backlog.json"
+  ticket_details: "project/tickets/TICKET-XXX.json"
+  generated_views: "project/views"
+
+ticket_docs:
+  spec_path_field: "spec_path"
+  spec_dir: "docs/project/specs"
+  implementation_plan_path_field: "implementation_plan_path"
+  plan_dir: "docs/project/plans"
+
+refactor:
+  plan_dir: "docs/runtime/refactor"
+  template: "core/templates/technical/refactor-plan-template.md"
+  requires_ticket_breakdown: true
+  requires_adr_when_architectural: true
+
+release:
+  records: "project/releases/vX.Y.Z.json"
+  schema: "core/config/release.schema.json"
+  template: "core/templates/release/release-record-template.json"
+  requires_rollback_verification: true
+  requires_post_release_smoke: true
+
+scripts:
+  canonical: "core/scripts"
+  generated_root: "scripts"
+  command_runner: "core/scripts/ai-core.sh"
+  workflow_handlers: "core/scripts/workflow.sh"
+  audit_validator: "core/scripts/validate-audit-log.sh"
+  audit_log: "project/audit-log.jsonl"
+
+ci:
+  governance_template: "core/templates/ci/ai-core-governance.yml"
+  app_templates: "core/templates/ci"
+
+docs_policy:
+  project_override: "config/docs-policy.json"
+  default: "core/config/docs-policy.default.json"

package/core/templates/qa/bug-report-template.md

@@ -0,0 +1,371 @@
+<!--
+Bug Report Template
+Used by: /report-bug command (QA agent, or any reporter)
+Consumed by: /triage-bug (scrum-master), /implement-task (developer), /verify-fix (QA)
+
+Instructions:
+- Fill ALL required sections (marked *)
+- Be specific, not vague
+- Include evidence (screenshots, logs)
+- Redact sensitive data (passwords, real PII)
+- Stay factual (no blame, no emotions)
+-->
+
+# BUG-XXX: [Short descriptive title] *
+
+<!--
+Title guidelines:
+- Max 80 chars
+- Describe what's broken + condition
+- ❌ "App is broken"
+- ❌ "Login issue"
+- ✅ "Login returns 500 for emails containing + character"
+- ✅ "Checkout crashes when cart has > 100 items"
+-->
+
+---
+
+## 📋 Metadata *
+
+| Field | Value |
+|-------|-------|
+| **Bug ID** | `BUG-XXX` |
+| **Type** | `bug` |
+| **Severity** | `SEV-1` \| `SEV-2` \| `SEV-3` \| `SEV-4` |
+| **Priority** | `MUST` \| `SHOULD` \| `COULD` |
+| **Status** | `NEW` (auto at creation) |
+| **Filed by** | [Agent/person name] |
+| **Filed at** | YYYY-MM-DD HH:MM UTC |
+| **Assignee** | (empty, filled at triage) |
+
+---
+
+## 🎯 Summary *
+
+<!-- 1-2 sentences: what's wrong, under what condition -->
+
+---
+
+## 🔄 Steps to Reproduce *
+
+<!--
+Exact, numbered, copy-pasteable steps.
+Assume reader has never used this app.
+-->
+
+### Preconditions
+<!-- What state must the system be in? -->
+- [e.g., "User account exists with email containing +"]
+- [e.g., "On staging environment"]
+
+### Steps
+1. Go to [URL or screen]
+2. [Specific action]
+3. [Specific action]
+4. [Observe result]
+
+### Test data (if applicable)
+```
+Email: user+test@example.com
+Password: TestPass123!
+(Use test account, not real user)
+```
+
+---
+
+## ✅ Expected Behavior *
+
+<!-- What SHOULD happen -->
+
+---
+
+## ❌ Actual Behavior *
+
+<!-- What DOES happen (the bug) -->
+
+---
+
+## 📸 Evidence *
+
+<!-- Screenshots, recordings, logs. At least 1 required. -->
+
+### Screenshots / Recordings
+- `evidence/screenshot-1.png`: [brief description]
+- `evidence/recording.mp4`: [brief description]
+
+### Error messages (if any)
+```
+[Copy-paste exact error text, redact sensitive data]
+```
+
+### Server log excerpt (if available)
+```
+[Timestamp] [Level] [Message]
+(Redact tokens, PII. Link to full log file if long.)
+```
+
+### Network trace (if relevant)
+- `evidence/network.har`
+- **Request**: POST /api/...
+- **Response**: 500
+
+### Browser console errors (if UI bug)
+```
+Uncaught TypeError: ...
+  at file.js:42
+```
+
+---
+
+## 🌍 Environment *
+
+| Field | Value |
+|-------|-------|
+| **Environment** | `dev` \| `staging` \| `pre-prod` \| `production` |
+| **Build / Version** | `v1.2.0-rc.3` |
+| **Commit** | `abc1234` |
+| **Deployed at** | YYYY-MM-DD HH:MM UTC |
+| **Browser** | Chrome 134.0.6998.88 (or N/A for API) |
+| **OS** | macOS 14.4 |
+| **Device** | Desktop / iPhone 15 / etc. |
+| **Screen size** | 1920x1080 (if responsive issue) |
+| **User agent** | [Full UA string if relevant] |
+| **User role** | admin / standard user / anonymous |
+| **Locale** | en-US / vi-VN / etc. |
+| **Observed at** | YYYY-MM-DD HH:MM UTC |
+
+---
+
+## 🔁 Frequency *
+
+<!-- How often does it happen? Be precise. -->
+
+- [ ] **Always** (10/10 attempts reproducible)
+- [ ] **Usually** (7-9/10 attempts)
+- [ ] **Sometimes** (3-6/10 attempts)
+- [ ] **Rarely** (1-2/10 attempts)
+- [ ] **Once** (1 observation, cannot reliably reproduce)
+
+### Attempts
+Attempted: [N] times
+Reproduced: [N] times
+
+### Conditions that trigger it
+<!-- Specific state, timing, data -->
+- 
+- 
+
+---
+
+## 📊 Impact Analysis *
+
+### Users affected
+<!-- Estimate scope -->
+- [ ] All users (100%)
+- [ ] Many users (majority, e.g., all Chrome users)
+- [ ] Specific segment (e.g., "Users with + in email, ~2-5%")
+- [ ] Few users (edge case)
+- [ ] Specific individual(s)
+
+### Business impact
+<!-- Revenue, operations, reputation -->
+- 
+
+### User experience impact
+<!-- From user's perspective -->
+- 
+
+### Data impact (if any)
+<!-- Data loss, corruption, exposure -->
+- 
+
+### Security impact (if any)
+<!-- Exposes secrets, permissions, PII -->
+- 
+
+### Workaround
+<!-- Can users do anything to avoid this? -->
+- [ ] No workaround
+- [ ] Difficult workaround: [describe]
+- [ ] Easy workaround: [describe]
+
+---
+
+## 🎯 Severity Justification *
+
+<!--
+Why this severity level?
+Reference severity matrix in rules/03-security.md or commands/qa/report-bug.md
+-->
+
+**SEV-X** because:
+- Users affected: [count/percentage]
+- Business impact: [describe]
+- Workaround: [exists/absent]
+- Data/security: [implications]
+
+**Not SEV-(X-1)** because:
+- [why not more severe]
+
+**Not SEV-(X+1)** because:
+- [why not less severe]
+
+---
+
+## 💡 Hypothesis (optional)
+
+<!--
+Your best guess about cause, but labeled as hypothesis.
+Don't put this as fact - devs will investigate.
+-->
+
+**Hypothesis (not verified)**:
+
+Looking at [code/logs/pattern], might be caused by [explanation].
+
+Suggested investigation:
+- [ ] Check [specific area]
+- [ ] Test [specific scenario]
+
+---
+
+## 🔗 Related
+
+### Feature ticket
+<!-- If this bug is in a recently released feature -->
+- TICKET-XXX: [title]
+
+### Similar past bugs
+<!-- Search bug history -->
+- BUG-YYY: [title] (resolved, might be recurrence)
+- BUG-ZZZ: [title] (similar pattern)
+
+### Affected components
+<!-- Code areas -->
+- `src/handlers/login.ts`
+- `src/auth/validators.ts`
+
+### Relevant ADRs
+<!-- Architecture decisions -->
+- ADR-0003: [title]
+
+### External
+<!-- External tracking IDs -->
+- Sentry: https://sentry.io/issues/12345
+- Support ticket: #1234 (customer XYZ reported)
+- Incident: INC-2026-042
+
+---
+
+## 🔎 Investigation Notes
+
+<!-- 
+Added during triage and investigation.
+Initial filer may leave empty.
+-->
+
+### Triaged by
+<!-- Filled by /triage-bug -->
+- Triager: [name]
+- Triaged at: YYYY-MM-DD
+- Severity confirmed: [final severity]
+- Assigned to: [developer]
+
+### Developer investigation
+<!-- Filled during /implement-task -->
+- Root cause: [explanation]
+- Fix approach: [brief]
+
+### Fix verification
+<!-- Filled by /verify-fix -->
+- PR: #XXX
+- Deployed: YYYY-MM-DD
+- Verified in: [environment]
+- Regression test: [path/to/test]
+
+---
+
+## 🎯 Acceptance Criteria for Fix
+
+<!-- 
+What does "fixed" mean for this bug?
+These become test cases.
+-->
+
+### AC 1: Original bug fixed *
+```gherkin
+Given [original conditions]
+When [original trigger]
+Then [correct behavior - not the bug]
+```
+
+### AC 2: Regression - no new bug introduced *
+```gherkin
+Given [related feature still works]
+When [test related flow]
+Then [still works correctly]
+```
+
+### AC 3: Test coverage
+```gherkin
+Given [code deployed with fix]
+When [running test suite]
+Then [regression test for BUG-XXX exists and passes]
+```
+
+---
+
+## 📝 Additional Context
+
+<!-- Anything else not captured above -->
+
+### User quotes (if from support)
+> [Exact quote from user/customer]
+
+### Time-sensitivity
+<!-- Any deadlines? -->
+- 
+
+### Related recent changes
+<!-- Deploys, config changes that might correlate -->
+- 
+
+---
+
+## 🚨 Escalation Log (SEV-1 / SEV-2)
+
+<!-- Filled for high-severity bugs -->
+
+- [ ] **Tech Lead notified**: [name, time]
+- [ ] **Scrum Master notified**: [name, time]
+- [ ] **Engineering Manager** (if > 1h unresolved): [name, time]
+- [ ] **Executive team** (if > 2h SEV-1): [name, time]
+- [ ] **Customer communication** (if user-facing): [who, what, when]
+
+---
+
+## 🔄 Status History
+
+<!-- Auto-populated -->
+
+| Date | Status | By | Note |
+|------|--------|----|----|
+| YYYY-MM-DD | NEW | [agent] | Initial filing |
+
+---
+
+## 🤝 Handoff
+
+**Current assignee**: [to be filled at triage]
+**Next step**: `/triage-bug BUG-XXX`
+**Expected next action**: Severity confirmation + sprint assignment
+
+---
+
+<!--
+DO NOT EDIT BELOW - auto-populated
+-->
+
+<!-- TEMPLATE_VERSION: 1.0.0 -->
+<!-- SCHEMA: core/config/bug.schema.json -->
+<!-- FILED_BY_AGENT: [agent-name] -->

package/core/templates/qa/test-plan-template.md

@@ -0,0 +1,57 @@
+# Test Plan Template
+
+## Metadata
+
+- Ticket ID:
+- Feature:
+- QA owner:
+- Environment:
+- Build/version:
+- Date:
+
+## Scope
+
+### In Scope
+
+- 
+
+### Out of Scope
+
+- 
+
+## Acceptance Criteria Coverage
+
+| AC Scenario | Test Type | Steps | Expected Result | Status |
+|-------------|-----------|-------|-----------------|--------|
+| | | | | |
+
+## Regression Areas
+
+- 
+
+## Test Data
+
+| Data | Source | Reset needed |
+|------|--------|--------------|
+| | | |
+
+## Non-Functional Checks
+
+- Performance:
+- Security:
+- Accessibility:
+- Browser/device:
+- Observability:
+
+## Risks and Blockers
+
+| Risk/Blocker | Impact | Owner | Resolution |
+|--------------|--------|-------|------------|
+| | | | |
+
+## Exit Criteria
+
+- All AC scenarios pass.
+- No critical/high regressions.
+- Bugs filed with evidence.
+- QA report saved.

package/core/templates/release/release-record-template.json

@@ -0,0 +1,67 @@
+{
+  "version": "v0.0.0",
+  "status": "PLANNED",
+  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
+  "created_by": "scrum-master-agent",
+  "released_at": null,
+  "source_branch": "release/v0.0.0",
+  "tag": null,
+  "scope": {
+    "tickets": [],
+    "bugs": [],
+    "excluded_tickets": []
+  },
+  "approvals": {
+    "tech_lead": {
+      "approved": false,
+      "by": "",
+      "at": "YYYY-MM-DDTHH:MM:SSZ",
+      "notes": ""
+    },
+    "qa": {
+      "approved": false,
+      "by": "",
+      "at": "YYYY-MM-DDTHH:MM:SSZ",
+      "notes": ""
+    },
+    "release_owner": {
+      "approved": false,
+      "by": "",
+      "at": "YYYY-MM-DDTHH:MM:SSZ",
+      "notes": ""
+    },
+    "security": {
+      "approved": false,
+      "by": "",
+      "at": "YYYY-MM-DDTHH:MM:SSZ",
+      "notes": ""
+    },
+    "known_issues": {
+      "approved": false,
+      "by": "",
+      "at": "YYYY-MM-DDTHH:MM:SSZ",
+      "notes": ""
+    }
+  },
+  "rollback_plan": {
+    "owner": "",
+    "command_or_steps": "",
+    "data_impact": "",
+    "time_limit_minutes": 30,
+    "verified": false
+  },
+  "qa": {
+    "evidence_path": "",
+    "post_release_smoke_required": true,
+    "post_release_smoke_path": null,
+    "post_release_smoke_passed": false
+  },
+  "security": {
+    "dependency_audit_passed": false,
+    "sast_passed": false,
+    "scan_url": null
+  },
+  "known_issues": [],
+  "changelog_path": "CHANGELOG.md",
+  "release_notes_path": null
+}

package/core/templates/requirements/PRD-template.md

@@ -0,0 +1,58 @@
+# Product Requirements Document Template
+
+## Overview
+
+- Product/area:
+- Author:
+- Date:
+- Status:
+
+## Problem Statement
+
+Describe the user or business problem.
+
+## Goals
+
+- 
+
+## Non-Goals
+
+- 
+
+## Users and Personas
+
+| Persona | Need | Pain point |
+|---------|------|------------|
+| | | |
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Signal |
+|----|-------------|----------|-------------------|
+| | | | |
+
+## User Stories
+
+- As a ..., I want ..., so that ...
+
+## Success Metrics
+
+| Metric | Baseline | Target |
+|--------|----------|--------|
+| | | |
+
+## Risks and Assumptions
+
+| Type | Description | Owner |
+|------|-------------|-------|
+| | | |
+
+## Open Questions
+
+- 
+
+## Links
+
+- Designs:
+- Analytics:
+- Support/customer evidence: