ai-core-framework 0.2.0 → 0.4.0

package/skills/qa-report-bug/SKILL.md

@@ -66,7 +66,7 @@ If not → prompt interactive collection.
 
 ### 2. Not duplicate
 Check existing open bugs for similar:
-- Grep bug titles in `project/bugs/*.json`
+- Grep bug titles in `docs/runtime/bugs/*.json`
 - If > 80% similarity → flag, ask if linking to existing
 
 ### 3. Has evidence (soft requirement)
@@ -125,7 +125,7 @@ If missing, still accept but flag in bug.
 │   BUG-NNN (separate sequence from TICKET-)               │
 ├──────────────────────────────────────────────────────────┤
 │ STEP 8: Create bug ticket                                │
-│   Path: project/bugs/BUG-NNN.json                 │
+│   Path: docs/runtime/bugs/BUG-NNN.json                 │
 │   Follow template: templates/qa/bug-report-template.md  │
 │   Initial status: NEW                                    │
 ├──────────────────────────────────────────────────────────┤
@@ -224,7 +224,7 @@ Missing env info = bug 50% harder to fix.
 Don't say "always" if not sure.
 
 ### RULE RB-009: Evidence preservation
-Screenshots, logs, HAR files → save to `project/bugs/evidence/BUG-NNN/`.
+Screenshots, logs, HAR files → save to `docs/runtime/bugs/evidence/BUG-NNN/`.
 
 Don't paste long logs in bug body → link to file.
 
@@ -304,8 +304,8 @@ Auto assess: Data integrity concern → SEV-1.
 Always (5/5 attempts)
 
 ### Evidence
-- Screenshot: `project/bugs/evidence/BUG-005/screenshot-1.png`
-- Network trace: `project/bugs/evidence/BUG-005/har.json`
+- Screenshot: `docs/runtime/bugs/evidence/BUG-005/screenshot-1.png`
+- Network trace: `docs/runtime/bugs/evidence/BUG-005/har.json`
 - Server log excerpt:
   ```
   2026-04-18T18:45:23Z ERROR handler/login.ts:42 
@@ -349,7 +349,7 @@ Likely: URL decoding treating + as space (classic `encodeURIComponent` vs `+` is
 
 ### Ticket File
 
-Created: `project/bugs/BUG-005.json`
+Created: `docs/runtime/bugs/BUG-005.json`
 
 ### Next Steps
 
@@ -405,7 +405,7 @@ Action: /triage-bug BUG-005
 - [ ] Executive team (if not resolved in 2h)
 
 ### Ticket File
-Created: `project/bugs/BUG-006.json`
+Created: `docs/runtime/bugs/BUG-006.json`
 
 ---
 HANDOFF → tech-lead + scrum-master (URGENT)

package/skills/qa-smoke-test/SKILL.md

@@ -79,7 +79,7 @@ curl -sf --max-time 10 "$STAGING_URL/health" || ABORT "Staging not responding"
 Check build version matches expected:
 ```bash
 deployed_commit=$(curl -s "$STAGING_URL/version" | jq -r .commit)
-expected_commit=$(cat project/tickets/${TICKET_ID}.json | jq -r .merge_info.merge_commit_sha)
+expected_commit=$(cat docs/runtime/tickets/${TICKET_ID}.json | jq -r .merge_info.merge_commit_sha)
 # Verify deployed >= expected
 ```
 
@@ -145,7 +145,7 @@ Required test accounts / test data exist. If not, setup before testing.
 │     → File separate regression bug (own ticket)          │
 ├──────────────────────────────────────────────────────────┤
 │ STEP 9: Generate report                                  │
-│   Save to: project/test-runs/TICKET-XXX-YYYYMMDD.md│
+│   Save to: docs/runtime/test-runs/TICKET-XXX-YYYYMMDD.md│
 ├──────────────────────────────────────────────────────────┤
 │ STEP 10: Handoff                                         │
 │   Pass → scrum-master (ready for release)                │
@@ -261,7 +261,7 @@ None 🎉
 Ticket state: QA → DONE ✅
 
 ### Test Run Record
-Saved to: `project/test-runs/TICKET-042-20260418.md`
+Saved to: `docs/runtime/test-runs/TICKET-042-20260418.md`
 
 ---
 HANDOFF → scrum-master

package/skills/qa-verify-fix/SKILL.md

@@ -54,7 +54,7 @@ After developer claims the bug is fixed and PR is merged + deployed:
 
 ### 1. Bug exists + in correct state
 ```bash
-bug_status=$(cat project/bugs/${BUG_ID}.json | jq -r .status)
+bug_status=$(cat docs/runtime/bugs/${BUG_ID}.json | jq -r .status)
 [ "$bug_status" = "FIXED" ] || [ "$bug_status" = "READY_FOR_QA" ] || ABORT
 ```
 
@@ -141,7 +141,7 @@ Check linked PR is merged (not still open).
 │     → HANDOFF → developer                                │
 ├──────────────────────────────────────────────────────────┤
 │ STEP 9: Generate report                                  │
-│   Save to: project/verifications/BUG-XXX-YYYYMMDD.md│
+│   Save to: docs/runtime/verifications/BUG-XXX-YYYYMMDD.md│
 ├──────────────────────────────────────────────────────────┤
 │ STEP 10: Update bug state + notify                       │
 └──────────────────────────────────────────────────────────┘
@@ -267,7 +267,7 @@ Bug status: FIXED → VERIFIED
 - BUG-004 (email HTML rendering): Still open, separate fix
 
 ### Verification Record
-Saved to: `project/verifications/BUG-002-20260418.md`
+Saved to: `docs/runtime/verifications/BUG-002-20260418.md`
 
 ---
 HANDOFF → scrum-master

package/skills/release-hotfix/SKILL.md

@@ -56,7 +56,7 @@ Manual:
 ## 🔄 Execution Flow
 
 1. Triage severity and impact.
-2. Create or link `BUG-NNN` in `project/bugs/`.
+2. Create or link `BUG-NNN` in `docs/runtime/bugs/`.
 3. Create hotfix ticket if needed with minimal AC and status `READY`.
 4. Create branch `hotfix/BUG-NNN-short-slug` or `hotfix/TICKET-NNN-short-slug` from production branch.
 5. Reproduce the issue and write a regression test if feasible.
@@ -69,7 +69,7 @@ Manual:
 12. QA verifies production or pre-prod depending on incident protocol.
 13. Back-merge hotfix into `develop`.
 14. Create follow-up ticket for full DoD, monitoring, and root cause analysis.
-15. Write incident summary in `project/releases/` or `project/incidents/`.
+15. Write incident summary in `docs/runtime/releases/` or `docs/runtime/incidents/`.
 
 ## 🔒 Hard Rules
 

package/skills/release-release/SKILL.md

@@ -65,7 +65,7 @@ Manual:
 5. Confirm QA evidence exists for every included ticket.
 6. Check open bugs and known issues.
 7. Generate changelog with ticket IDs, PRs, bug fixes, migrations, and breaking changes.
-8. Create `project/releases/vX.Y.Z.json` from `templates/release/release-record-template.json` with scope, approvals, risks, deploy plan, rollback plan, and timestamps.
+8. Create `docs/runtime/releases/vX.Y.Z.json` from `templates/release/release-record-template.json` with scope, approvals, risks, deploy plan, rollback plan, and timestamps.
 9. Create or update release branch if configured.
 10. Tag release using `vX.Y.Z`.
 11. Trigger deployment or document manual deployment step.
@@ -93,7 +93,7 @@ Database migrations MUST include forward plan, rollback or mitigation, and backu
 Do not move an existing release tag. Create a new patch release instead.
 
 ### RULE REL-007: Release record schema required
-Every release record MUST satisfy `config/release.schema.json`. Missing approvals, rollback verification, QA evidence, security scan status, or known issue approval blocks release.
+Every release record MUST satisfy `docs/config/release.schema.json`. Missing approvals, rollback verification, QA evidence, security scan status, or known issue approval blocks release.
 
 ### RULE REL-008: Post-release smoke evidence
 If a release is marked `RELEASED` and `qa.post_release_smoke_required=true`, then `qa.post_release_smoke_passed=true` and the evidence path MUST be recorded.

package/skills/release-rollback/SKILL.md

@@ -38,7 +38,7 @@ Restore service safely, preserve audit trail, and start follow-up remediation.
 4. Notify stakeholders and freeze related deploys.
 5. Execute documented rollback steps.
 6. Verify service health and core flows.
-7. Record rollback result in `project/releases/`.
+7. Record rollback result in `docs/runtime/releases/`.
 8. Create follow-up bug/ticket and incident notes.
 
 ## 🔒 Hard Rules

package/skills/review-create-pr/SKILL.md

@@ -79,7 +79,7 @@ fi
 Extract TICKET-XXX from branch name, verify:
 ```bash
 TICKET_ID=$(echo "$current_branch" | grep -oE 'TICKET-[0-9]+')
-test -f "project/tickets/${TICKET_ID}.json" || ABORT
+test -f "docs/runtime/tickets/${TICKET_ID}.json" || ABORT
 ```
 
 ### 3. Ticket in IN_PROGRESS
@@ -203,7 +203,7 @@ fi
 │   - (Optional) Slack notification via webhook            │
 ├──────────────────────────────────────────────────────────┤
 │ STEP 10: Log metrics                                     │
-│   project/metrics/create-pr.jsonl                 │
+│   docs/runtime/metrics/create-pr.jsonl                 │
 └──────────────────────────────────────────────────────────┘
 ```
 

package/skills/review-merge-pr/SKILL.md

@@ -205,7 +205,7 @@ If branch is `hotfix/*`:
 - Merge commit SHA
 - Strategy used
 
-Store in `project/audit-log.jsonl`.
+Store in `docs/runtime/audit-log.jsonl`.
 
 ### RULE MP-009: Rollback plan for risky merges
 If PR flagged as `high-risk` (auth changes, DB migration, payment):

package/skills/using-ai-core/SKILL.md

@@ -42,12 +42,12 @@ If command metadata and user intent conflict, explain the conflict and stop.
 
 ## Source Of Truth
 
-- `project/` is machine-readable runtime state.
-- `docs/` is human-readable project documentation.
-- `config/` is project configuration.
+- `docs/runtime/` is AI Core runtime: state plus operational runtime docs.
+- `docs/project/` is human-readable project and product documentation.
+- `docs/config/` is project configuration.
 - Root-level framework folders are portable framework code.
 
-Do not move backlog, tickets, releases, bugs, sprints, or audit records into `docs/`. Generate human-readable summaries in `project/views/` and keep longer narrative docs in `docs/`.
+Keep backlog, tickets, releases, bugs, sprints, and audit records under `docs/runtime/`. Generate human-readable summaries in `docs/runtime/views/` and keep longer narrative project/product docs in `docs/project/`.
 
 ## Guided Report
 

package/skills/verification-before-done/SKILL.md

@@ -14,7 +14,7 @@ Before saying a workflow step is complete:
 1. Identify what proves the claim.
 2. Run or inspect the relevant verification.
 3. Read the result.
-4. Record evidence in `project/test-runs/`, `project/verifications/`, or the ticket.
+4. Record evidence in `docs/runtime/test-runs/`, `docs/runtime/verifications/`, or the ticket.
 5. Only then report completion.
 
 ## Required Evidence

package/templates/ci/ai-core-governance.yml

@@ -4,10 +4,10 @@ on:
   pull_request:
     paths:
       - "agents/**"
-      - "config/**"
+      - "docs/config/**"
       - "docs/**"
       - "hooks/**"
-      - "project/**"
+      - "docs/runtime/**"
       - "rules/**"
       - "scripts/**"
       - "skills/**"
@@ -18,10 +18,10 @@ on:
     branches: [main, develop, "release/**"]
     paths:
       - "agents/**"
-      - "config/**"
+      - "docs/config/**"
       - "docs/**"
       - "hooks/**"
-      - "project/**"
+      - "docs/runtime/**"
       - "rules/**"
       - "scripts/**"
       - "skills/**"
@@ -55,25 +55,25 @@ jobs:
       - name: Validate ticket schemas
         run: |
           set -e
-          for ticket in project/tickets/*.json; do
+          for ticket in docs/runtime/tickets/*.json; do
             if [ ! -f "$ticket" ]; then continue; fi
-            ajv validate -s config/ticket.schema.json -d "$ticket"
+            ajv validate -s docs/config/ticket.schema.json -d "$ticket"
           done
 
       - name: Validate backlog schema
         run: |
-          if [ ! -f "project/backlog/backlog.json" ]; then
+          if [ ! -f "docs/runtime/backlog/backlog.json" ]; then
             echo "No backlog file, skipping"
             exit 0
           fi
-          ajv validate -s config/backlog.schema.json -d project/backlog/backlog.json
+          ajv validate -s docs/config/backlog.schema.json -d docs/runtime/backlog/backlog.json
 
       - name: Validate release schemas
         run: |
           set -e
-          for release in project/releases/*.json; do
+          for release in docs/runtime/releases/*.json; do
             if [ ! -f "$release" ]; then continue; fi
-            ajv validate -s config/release.schema.json -d "$release"
+            ajv validate -s docs/config/release.schema.json -d "$release"
           done
 
       - name: Validate state
@@ -95,7 +95,7 @@ jobs:
       - name: Check state history immutability
         if: github.event_name == 'pull_request'
         run: |
-          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'project/tickets/*.json' || true)
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'docs/runtime/tickets/*.json' || true)
           if [ -z "$CHANGED" ]; then
             echo "No ticket changes"
             exit 0

package/templates/pr/pull-request-template.md

@@ -11,7 +11,7 @@ Instructions for developer:
 
 <!-- 1-3 sentences: what does this PR do and why? -->
 
-**Ticket**: [TICKET-XXX](./project/tickets/TICKET-XXX.json) <!-- Auto-filled by /create-pr -->
+**Ticket**: [TICKET-XXX](./docs/runtime/tickets/TICKET-XXX.json) <!-- Auto-filled by /create-pr -->
 
 **Type**: <!-- feature | bugfix | hotfix | refactor | chore | docs -->
 

package/templates/project/CODEOWNERS

@@ -7,8 +7,8 @@
 /skills/ @tech-leads
 /templates/ @tech-leads
 /workflows/ @tech-leads
-/config/ @scrum-masters @tech-leads
-/project/ @scrum-masters @tech-leads
+/docs/config/ @scrum-masters @tech-leads
+/docs/runtime/ @scrum-masters @tech-leads
 /docs/runtime/adr/ @tech-leads
 /docs/project/specs/ @product-owners @tech-leads
 /docs/project/plans/ @tech-leads

package/templates/project/docs-policy.json

@@ -1,3 +1,3 @@
 {
-  "extends": "config/docs-policy.default.json"
+  "extends": "docs/config/docs-policy.default.json"
 }

package/templates/project/project-structure.yaml

@@ -1,18 +1,18 @@
-# Project-specific structure map copied by /setup-project into config/project-structure.yaml
+# Project-specific structure map copied by /setup-project into docs/config/project-structure.yaml
 # Framework folders remain framework-only. Runtime state and project docs live outside them.
 
 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"
+  root: "docs/runtime"
+  tickets: "docs/runtime/tickets"
+  backlog: "docs/runtime/backlog"
+  bugs: "docs/runtime/bugs"
+  sprints: "docs/runtime/sprints"
+  releases: "docs/runtime/releases"
+  metrics: "docs/runtime/metrics"
+  views: "docs/runtime/views"
+  test_runs: "docs/runtime/test-runs"
+  incidents: "docs/runtime/incidents"
+  audit_log: "docs/runtime/audit-log.jsonl"
 
 project_docs:
   root: "docs/project"
@@ -36,9 +36,9 @@ runtime_docs:
   incidents: "docs/runtime/incidents"
 
 backlog:
-  source_of_truth: "project/backlog/backlog.json"
-  ticket_details: "project/tickets/TICKET-XXX.json"
-  generated_views: "project/views"
+  source_of_truth: "docs/runtime/backlog/backlog.json"
+  ticket_details: "docs/runtime/tickets/TICKET-XXX.json"
+  generated_views: "docs/runtime/views"
 
 ticket_docs:
   spec_path_field: "spec_path"
@@ -53,8 +53,8 @@ refactor:
   requires_adr_when_architectural: true
 
 release:
-  records: "project/releases/vX.Y.Z.json"
-  schema: "config/release.schema.json"
+  records: "docs/runtime/releases/vX.Y.Z.json"
+  schema: "docs/config/release.schema.json"
   template: "templates/release/release-record-template.json"
   requires_rollback_verification: true
   requires_post_release_smoke: true
@@ -65,12 +65,12 @@ scripts:
   command_runner: "scripts/ai-core.sh"
   workflow_handlers: "scripts/workflow.sh"
   audit_validator: "scripts/validate-audit-log.sh"
-  audit_log: "project/audit-log.jsonl"
+  audit_log: "docs/runtime/audit-log.jsonl"
 
 ci:
   governance_template: "templates/ci/ai-core-governance.yml"
   app_templates: "templates/ci"
 
 docs_policy:
-  project_override: "config/docs-policy.json"
-  default: "config/docs-policy.default.json"
+  project_override: "docs/config/docs-policy.json"
+  default: "docs/config/docs-policy.default.json"

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

@@ -367,5 +367,5 @@ DO NOT EDIT BELOW - auto-populated
 -->
 
 <!-- TEMPLATE_VERSION: 1.0.0 -->
-<!-- SCHEMA: config/bug.schema.json -->
+<!-- SCHEMA: docs/config/bug.schema.json -->
 <!-- FILED_BY_AGENT: [agent-name] -->

package/templates/requirements/user-story-template.md

@@ -378,4 +378,4 @@ DO NOT EDIT BELOW - auto-populated fields
 <!-- TEMPLATE_VERSION: 1.0.0 -->
 <!-- CREATED_BY_AGENT: business-analyst -->
 <!-- NEXT_AGENT: tech-lead -->
-<!-- SCHEMA: config/ticket.schema.json -->
+<!-- SCHEMA: docs/config/ticket.schema.json -->

package/workflows/bug-lifecycle.md

@@ -10,7 +10,7 @@ Make bugs reproducible, prioritized, fixed with regression coverage, and verifie
 
 1. Discovery
    - Any agent or user reports a defect with `/report-bug`.
-   - Bug is created in `project/bugs/` with status `NEW` or `NEEDS_MORE_INFO`.
+   - Bug is created in `docs/runtime/bugs/` with status `NEW` or `NEEDS_MORE_INFO`.
 
 2. Triage
    - BA runs `/triage-bug` with Tech Lead and QA input.
@@ -46,8 +46,8 @@ Make bugs reproducible, prioritized, fixed with regression coverage, and verifie
 
 ## 📊 Artifacts
 
-- `project/bugs/BUG-XXX.json`
-- Linked ticket in `project/tickets/`
+- `docs/runtime/bugs/BUG-XXX.json`
+- Linked ticket in `docs/runtime/tickets/`
 - Verification report
 - Regression tests
 

package/workflows/feature-lifecycle.md

@@ -82,7 +82,7 @@
 3. BA writes User Story (INVEST)
 4. BA writes ≥3 AC scenarios (Gherkin)
 5. BA creates `docs/project/specs/TICKET-XXX-<slug>.md`
-6. BA creates `project/tickets/TICKET-XXX.json` with `spec_path`
+6. BA creates `docs/runtime/tickets/TICKET-XXX.json` with `spec_path`
 7. BA output HANDOFF → tech-lead
 
 ### Gates
@@ -181,7 +181,7 @@ Each requirement should finish in one session (< 30 minutes of BA work).
    - Sort by priority (MUST > SHOULD > COULD)
    - Pull tickets into sprint until capacity is reached (30 points default)
    - Assign tickets to sprint
-3. Create `project/sprints/SPRINT-XXX.json`
+3. Create `docs/runtime/sprints/SPRINT-XXX.json`
 
 ### Gates
 - ✅ Total points ≤ team capacity

package/workflows/sprint-lifecycle.md

@@ -46,8 +46,8 @@ Ensure sprint commitments are realistic, tracked, and closed with factual metric
 
 ## 📊 Artifacts
 
-- `project/sprints/SPRINT-XXX.json`
-- `project/metrics/`
+- `docs/runtime/sprints/SPRINT-XXX.json`
+- `docs/runtime/metrics/`
 - Retrospective notes
 - Sprint report