ai-core-framework 0.1.0 → 0.3.0

package/README.md

@@ -8,14 +8,14 @@ npx ai-core-framework
 ```
 
 Run the command from the root of the project that should receive AI Core. The
-installer asks which AI CLI to target. Version 0.1 supports Codex and copies the
-contents of this repo's `core/` directory directly into the target project's
+installer asks which AI CLI to target. Version 0.1 supports Codex and copies this
+repo's root-level framework folders directly into the target project's
 `.codex/` directory:
 
 ```text
 .codex/
   agents/
-  config/
+  docs/config/
   rules/
   scripts/
   skills/
@@ -131,24 +131,24 @@ The framework now includes mechanical gates beyond prompt-level rules:
 
 - `scripts/validate-state.sh` validates ticket state transitions, backlog rank integrity, dependency ordering, blocked-ticket unblock evidence, DONE-ticket DoD fields, QA evidence, and release governance records.
 - `scripts/validate-docs.sh` validates documentation obligations from diffs and ticket metadata, including API docs, README/setup docs, migration runbooks, ADRs, changelog/release notes, and DONE-ticket documentation evidence.
-- `scripts/validate-permissions.sh` validates state-history command execution against `core/commands/**` role metadata and blocks obvious self-approval.
-- `core/scripts/` is now the canonical portable script source. Root `scripts/` copies are installed for convenience by setup.
-- `core/scripts/ai-core.sh` is a lightweight command runner that checks command role metadata before dispatching executable handlers.
-- `core/scripts/workflow.sh` provides executable state-transition handlers for `/analyze-requirements`, `/groom-ticket`, `/mark-ready`, `/implement-task`, `/create-pr`, `/merge-pr`, `/smoke-test`, and `/release`.
-- `core/skills/` provides chat-first behavior guidance inspired by skill-based systems: AI Core bootstrap, brainstorming, implementation planning, ticket execution, and verification-before-done.
+- `scripts/validate-permissions.sh` validates state-history command execution against `commands/**` role metadata and blocks obvious self-approval.
+- `scripts/` is the canonical portable script source.
+- `scripts/ai-core.sh` is a lightweight command runner that checks command role metadata before dispatching executable handlers.
+- `scripts/workflow.sh` provides executable state-transition handlers for `/analyze-requirements`, `/groom-ticket`, `/mark-ready`, `/implement-task`, `/create-pr`, `/merge-pr`, `/smoke-test`, and `/release`.
+- `skills/` provides chat-first behavior guidance inspired by skill-based systems: AI Core bootstrap, brainstorming, implementation planning, ticket execution, and verification-before-done.
 - `/analyze-requirements` can create a linked spec in `docs/project/specs/`; `/write-plan` creates a linked implementation plan in `docs/project/plans/`.
-- `core/scripts/validate-audit-log.sh` validates the hash chain in `project/audit-log.jsonl`; executable workflow handlers append audit records.
-- `core/scripts/log-user-request.sh` appends every AI-handled user request to `project/user-requests.jsonl` so the user can review what they asked for.
-- `/request-log` shows recent entries from `project/user-requests.jsonl`.
-- `core/scripts/install-codex-prompts.sh` installs AI Core commands as Codex custom slash prompts in `~/.codex/prompts`.
-- `CODEOWNERS` adds review ownership defaults for `core/`, `config/`, `project/`, ADRs, runbooks, and workflows.
-- `config/docs-policy.json` can override documentation detection paths from `core/config/docs-policy.default.json`.
-- `.github/workflows/ai-core-governance.yml` is the portable governance workflow. App CI remains stack-specific and can be replaced with templates from `core/templates/ci/`.
-- `scripts/setup-project.sh` and `core/scripts/setup-project.sh` make copied `core/` installs executable: project config, runtime state folders, docs folders, backlog seed file, platform sync, and state validation.
+- `scripts/validate-audit-log.sh` validates the hash chain in `docs/runtime/project/audit-log.jsonl`; executable workflow handlers append audit records.
+- `scripts/log-user-request.sh` appends every AI-handled user request to `docs/runtime/project/user-requests.jsonl` so the user can review what they asked for.
+- `/request-log` shows recent entries from `docs/runtime/project/user-requests.jsonl`.
+- `scripts/install-codex-prompts.sh` installs AI Core commands as Codex custom slash prompts in `~/.codex/prompts`.
+- `CODEOWNERS` adds review ownership defaults for framework folders, `docs/config/`, `docs/runtime/project/`, ADRs, runbooks, and workflows.
+- `docs/config/docs-policy.json` can override documentation detection paths from `docs/config/docs-policy.default.json`.
+- `.github/workflows/ai-core-governance.yml` is the portable governance workflow. App CI remains stack-specific and can be replaced with templates from `templates/ci/`.
+- `scripts/setup-project.sh` makes copied root-level framework installs executable: project config, runtime state folders, docs folders, backlog seed file, platform sync, and state validation.
 - `.github/workflows/ci.yml` and `.github/workflows/validate-state.yml` run AI Core governance checks in CI.
 - `.githooks/pre-commit` runs documentation gates before commit after hooks are installed with `bash scripts/install-hooks.sh`.
-- `core/config/release.schema.json` and `core/templates/release/release-record-template.json` define release approval, rollback, QA, security, and known-issue evidence.
-- `scripts/generate-views.sh` now produces dashboard and release readiness views in `project/views/`.
+- `docs/config/release.schema.json` and `templates/release/release-record-template.json` define release approval, rollback, QA, security, and known-issue evidence.
+- `scripts/generate-views.sh` now produces dashboard and release readiness views in `docs/runtime/project/views/`.
 
 Chat-first setup flow:
 
@@ -168,6 +168,6 @@ guide /analyze-requirements "User can reset password"
 next TICKET-001
 ```
 
-The normal interface is the AI chat window. The AI should infer the correct role from command metadata (`owner_agent` / `requires_agents`) and may use `core/scripts/ai-core.sh` internally for deterministic execution and validation. Users should not need to type `bash ...` or `AI_AGENT=...`.
+The normal interface is the AI chat window. The AI should infer the correct role from command metadata (`owner_agent` / `requires_agents`) and may use `scripts/ai-core.sh` internally for deterministic execution and validation. Users should not need to type `bash ...` or `AI_AGENT=...`.
 
 `guide` runs one step, reports the completed command, ticket state before/after, updated `project` files, validation results, and the suggested next chat command. It asks before continuing and does not auto-run steps that still need placeholders such as `<story_points>` or `<pr_url>`.

package/{core/agents → agents}/business-analyst.md

@@ -20,17 +20,17 @@ cannot_invoke_commands:
 read_access:
   - "docs/**"
   - "src/**"  # Read-only for context. MUST NOT modify.
-  - "project/**"
+  - "docs/runtime/project/**"
 write_access:
   - "docs/project/product/**"
   - "docs/project/planning/**"
   - "docs/project/specs/**"
   - "docs/project/requirements/**"
   - "docs/project/user-stories/**"
-  - "project/tickets/**"
-  - "project/backlog/**"
-  - "project/views/**"
-  - "project/sprints/**"
+  - "docs/runtime/project/tickets/**"
+  - "docs/runtime/project/backlog/**"
+  - "docs/runtime/project/views/**"
+  - "docs/runtime/project/sprints/**"
 escalates_to: tech-lead  # When technical input is required
 ---
 
@@ -63,7 +63,7 @@ You are **NOT** a developer. You **MUST NOT** estimate effort. Estimation belong
    - **S**mall
    - **T**estable
 4. **Write Acceptance Criteria** in Gherkin format with at least 3 scenarios: happy path, edge case, error case.
-5. **Create tickets** in `project/tickets/TICKET-XXX.json`.
+5. **Create tickets** in `docs/runtime/project/tickets/TICKET-XXX.json`.
 6. **Prioritize** with MoSCoW (Must/Should/Could/Won't).
 7. **Handoff** to Tech Lead for estimation.
 8. **Reverse-document existing behavior** from source code when `/document-existing-requirements` is invoked.
@@ -94,7 +94,7 @@ Every User Story **MUST** pass INVEST. If it does not, you **MUST** split it int
 A ticket **MUST NOT** transition to `READY` unless it has ≥3 AC scenarios.
 
 ### RULE BA-004: Template enforcement
-You **MUST** use `core/templates/requirements/user-story-template.md`. Freestyle formats are **FORBIDDEN**.
+You **MUST** use `templates/requirements/user-story-template.md`. Freestyle formats are **FORBIDDEN**.
 
 ### RULE BA-005: Bug severity required
 If the input is a **bug report**, you **MUST** determine severity:

package/{core/agents → agents}/developer.md

@@ -32,7 +32,7 @@ write_access:
   - "app/**"
   - "docs/project/api/**"
   - "CHANGELOG.md"
-  - "project/tickets/**"
+  - "docs/runtime/project/tickets/**"
 escalates_to: tech-lead
 collaborates_with:
   - tech-lead
@@ -250,7 +250,7 @@ Use `templates/pr/pull-request-template.md`.
 ### With Tech Lead
 - Ask clarification before coding when anything is unclear.
 - Respond to review gracefully and without defensiveness.
-- Track feedback patterns in `project/dev-learnings.md`.
+- Track feedback patterns in `docs/runtime/project/dev-learnings.md`.
 
 ### With QA
 - Provide clear "how to test" notes in PR.

package/{core/agents → agents}/qa-tester.md

@@ -27,9 +27,9 @@ write_access:
   - "docs/runtime/qa/**"
   - "docs/runtime/test-runs/**"
   - "docs/runtime/verifications/**"
-  - "project/tickets/**"
-  - "project/bugs/**"
-  - "project/test-runs/**"
+  - "docs/runtime/project/tickets/**"
+  - "docs/runtime/project/bugs/**"
+  - "docs/runtime/project/test-runs/**"
 escalates_to: tech-lead
 collaborates_with:
   - developer

package/{core/agents → agents}/scrum-master.md

@@ -17,14 +17,18 @@ can_invoke_commands:
   - /generate-views
   - /ticket-health
 write_access:
-  - "project/sprints/**"
-  - "project/releases/**"
-  - "project/metrics/**"
-  - "project/views/**"
-  - "config/project-config.yaml"
-  - "config/project-structure.yaml"
+  - "docs/runtime/project/sprints/**"
+  - "docs/runtime/project/releases/**"
+  - "docs/runtime/project/metrics/**"
+  - "docs/runtime/project/views/**"
+  - "docs/config/project-config.yaml"
+  - "docs/config/project-structure.yaml"
 read_access:
-  - "core/**"
+  - "agents/**"
+  - "rules/**"
+  - "skills/**"
+  - "templates/**"
+  - "workflows/**"
   - "docs/**"
 forbidden:
   - "Make technical architecture decisions"
@@ -67,16 +71,16 @@ The Scrum Master MUST NOT:
 ## 🔒 Hard Rules
 
 ### RULE SM-001: State machine integrity
-Every ticket transition MUST follow `core/rules/06-approval-gates.md`. The Scrum Master MUST run `/validate-state` before sprint start and before release.
+Every ticket transition MUST follow `rules/06-approval-gates.md`. The Scrum Master MUST run `/validate-state` before sprint start and before release.
 
 ### RULE SM-002: DoR gate ownership
-Only the Scrum Master may execute `/mark-ready`. It MUST verify every item in `core/rules/07-definition-of-ready.md`.
+Only the Scrum Master may execute `/mark-ready`. It MUST verify every item in `rules/07-definition-of-ready.md`.
 
 ### RULE SM-003: Capacity is a hard constraint
 A sprint MUST NOT be planned above configured capacity unless the overflow is explicitly documented as risk and approved by a human.
 
 ### RULE SM-004: No hidden work
-Any work performed in a sprint MUST be represented by a ticket or bug in `project/`.
+Any work performed in a sprint MUST be represented by a ticket or bug in `docs/runtime/project/`.
 
 ### RULE SM-005: Blockers are first-class
 Any ticket blocked longer than the soft threshold in approval gates MUST be surfaced in sprint reports.
@@ -91,14 +95,14 @@ The Scrum Master coordinates, but does not replace BA, Tech Lead, Developer, or
 Velocity, burndown, carryover, defect counts, and cycle time MUST be computed from state files or explicitly labeled as estimates.
 
 ### RULE SM-009: Ceremony outputs are persisted
-Sprint planning, review, retro, and release summaries MUST be written to `project/sprints/`, `project/releases/`, or `project/metrics/`.
+Sprint planning, review, retro, and release summaries MUST be written to `docs/runtime/project/sprints/`, `docs/runtime/project/releases/`, or `docs/runtime/project/metrics/`.
 
 ### RULE SM-010: Escalate ambiguity
 If command preconditions are unclear, STOP and escalate instead of guessing.
 
 ## 🔄 Standard Operating Flow
 
-1. Load `config/project-config.yaml`.
+1. Load `docs/config/project-config.yaml`.
 2. Validate state with `/validate-state`.
 3. Inspect tickets, bugs, active sprint, and release state.
 4. Identify the current ceremony or workflow.

package/{core/agents → agents}/tech-lead.md

@@ -29,9 +29,9 @@ write_access:
   - "docs/runtime/technical/**"
   - "docs/architecture/**"
   - "docs/runtime/refactor/**"
-  - "project/tickets/**"
-  - "project/backlog/**"
-  - "project/prs/**"
+  - "docs/runtime/project/tickets/**"
+  - "docs/runtime/project/backlog/**"
+  - "docs/runtime/project/prs/**"
 escalates_to: human
 collaborates_with:
   - business-analyst
@@ -179,7 +179,7 @@ When invoking `/hotfix`, you **MUST**:
 User: /groom-ticket TICKET-042
 ```
 You receive:
-- Ticket JSON from `project/tickets/TICKET-042.json`
+- Ticket JSON from `docs/runtime/project/tickets/TICKET-042.json`
 - Full AC
 - Related code, if referenced by the ticket
 

package/bin/ai-core-framework.js

@@ -8,7 +8,7 @@ const { stdin, stdout } = require('node:process');
 const { installCodex } = require('../lib/install-codex');
 
 const packageRoot = path.resolve(__dirname, '..');
-const sourceCoreDir = path.join(packageRoot, 'core');
+const sourceFrameworkDir = packageRoot;
 
 function normalizeAnswer(answer) {
   return answer.trim().toLowerCase();
@@ -54,8 +54,8 @@ async function main() {
   const rl = createPrompter();
 
   try {
-    if (!fs.existsSync(sourceCoreDir)) {
-      throw new Error(`Package is missing core assets: ${sourceCoreDir}`);
+    if (!fs.existsSync(path.join(sourceFrameworkDir, 'skills'))) {
+      throw new Error(`Package is missing framework assets: ${sourceFrameworkDir}`);
     }
 
     const selectedCli = await chooseCli(rl);
@@ -71,7 +71,7 @@ async function main() {
 
     const result = await installCodex({
       targetDir,
-      sourceCoreDir,
+      sourceFrameworkDir,
       confirm: (question) => askConflict(rl, question),
     });
 

package/{core → docs}/config/backlog.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Backlog",
-  "description": "Project-specific backlog ordering and prioritization schema for project/backlog/backlog.json",
+  "description": "Project-specific backlog ordering and prioritization schema for docs/runtime/project/backlog/backlog.json",
   "type": "object",
   "required": ["version", "updated_at", "updated_by", "items"],
   "additionalProperties": true,

package/{core → docs}/config/release.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Release",
-  "description": "Schema for release records in project/releases/",
+  "description": "Schema for release records in docs/runtime/project/releases/",
   "type": "object",
   "required": [
     "version",

package/{core → docs}/config/ticket.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Ticket",
-  "description": "Schema for tickets in project/tickets/",
+  "description": "Schema for tickets in docs/runtime/project/tickets/",
   "type": "object",
   "required": [
     "id",

package/hooks/hooks-cursor.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CURSOR_PLUGIN_ROOT}/hooks/session-start\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+SKILL_FILE="${PLUGIN_ROOT}/skills/using-ai-core/SKILL.md"
+
+if [ ! -f "$SKILL_FILE" ]; then
+  context="AI Core is installed, but skills/using-ai-core/SKILL.md was not found. Ask the user to run /setup-project or verify plugin installation."
+else
+  content=$(sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/' "$SKILL_FILE" | tr -d '\n')
+  context="<AI_CORE_BOOTSTRAP>\\nYou are using AI Core. Read and follow this bootstrap skill before workflow work:\\n\\n${content}</AI_CORE_BOOTSTRAP>"
+fi
+
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  printf '{\n  "additional_context": "%s"\n}\n' "$context"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$context"
+else
+  printf '{\n  "additionalContext": "%s"\n}\n' "$context"
+fi

package/lib/install-codex.js

@@ -1,6 +1,18 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const FRAMEWORK_ENTRIES = [
+  'agents',
+  'docs',
+  'hooks',
+  'rules',
+  'scripts',
+  'skills',
+  'templates',
+  'workflows',
+  'README.md',
+];
+
 function listFiles(rootDir) {
   const files = [];
 
@@ -20,13 +32,33 @@ function listFiles(rootDir) {
   return files;
 }
 
-async function installCodex({ targetDir = process.cwd(), sourceCoreDir, confirm }) {
-  if (!sourceCoreDir) {
-    throw new Error('sourceCoreDir is required');
+function listFrameworkFiles(sourceFrameworkDir) {
+  const files = [];
+
+  for (const entry of FRAMEWORK_ENTRIES) {
+    const entryPath = path.join(sourceFrameworkDir, entry);
+
+    if (!fs.existsSync(entryPath)) {
+      continue;
+    }
+
+    if (fs.statSync(entryPath).isDirectory()) {
+      files.push(...listFiles(entryPath));
+    } else {
+      files.push(entryPath);
+    }
+  }
+
+  return files;
+}
+
+async function installCodex({ targetDir = process.cwd(), sourceFrameworkDir, confirm }) {
+  if (!sourceFrameworkDir) {
+    throw new Error('sourceFrameworkDir is required');
   }
 
-  if (!fs.existsSync(sourceCoreDir) || !fs.statSync(sourceCoreDir).isDirectory()) {
-    throw new Error(`Source core directory not found: ${sourceCoreDir}`);
+  if (!fs.existsSync(sourceFrameworkDir) || !fs.statSync(sourceFrameworkDir).isDirectory()) {
+    throw new Error(`Source framework directory not found: ${sourceFrameworkDir}`);
   }
 
   const targetCodexDir = path.join(targetDir, '.codex');
@@ -39,8 +71,8 @@ async function installCodex({ targetDir = process.cwd(), sourceCoreDir, confirm
 
   fs.mkdirSync(targetCodexDir, { recursive: true });
 
-  for (const sourceFile of listFiles(sourceCoreDir)) {
-    const relativePath = path.relative(sourceCoreDir, sourceFile);
+  for (const sourceFile of listFrameworkFiles(sourceFrameworkDir)) {
+    const relativePath = path.relative(sourceFrameworkDir, sourceFile);
     const targetFile = path.join(targetCodexDir, relativePath);
     let shouldCopy = true;
     let overwriting = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-core-framework",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Chat-first enterprise AI SDLC framework installer for AI coding CLIs.",
   "license": "MIT",
   "author": {
@@ -19,8 +19,15 @@
   },
   "files": [
     "bin/",
-    "core/",
+    "agents/",
+    "docs/config/",
+    "hooks/",
     "lib/",
+    "rules/",
+    "scripts/",
+    "skills/",
+    "templates/",
+    "workflows/",
     "README.md",
     ".codex-plugin/",
     ".claude-plugin/",

package/{core/rules → rules}/00-global-rules.md

@@ -29,14 +29,14 @@ If a rule says **MUST** or **MUST NOT**, it is mandatory and has **NO EXCEPTIONS
 
 ## 🎫 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:
+**MUST NOT** write or modify production code (files in `src/`, `lib/`, `app/`) unless there is an active ticket in `docs/runtime/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
+- Update files in root-level framework folders, which are the meta-framework
 
 **If the user requests code without a ticket:**
 ```
@@ -52,22 +52,22 @@ If a rule says **MUST** or **MUST NOT**, it is mandatory and has **NO EXCEPTIONS
 
 | 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` |
+| Backlog order and prioritization | `docs/runtime/project/backlog/backlog.json` |
+| Ticket details and state history | `docs/runtime/project/tickets/TICKET-XXX.json` |
+| Sprint info | `docs/runtime/project/sprints/SPRINT-XXX.json` |
+| Bug details | `docs/runtime/project/bugs/BUG-XXX.json` |
+| Release records | `docs/runtime/project/releases/vX.Y.Z.json` |
+| User request log | `docs/runtime/project/user-requests.jsonl` |
+| Project config | `docs/config/project-config.yaml` |
+| Project structure map | `docs/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` |
+| Agent capabilities | `agents/<agent>.md` (frontmatter) |
+| Coverage threshold | `docs/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/`.
+Root-level framework folders are framework-only. Project-specific state and configuration MUST live in `docs/runtime/project/`, `docs/config/`, `docs/project/`, or `docs/runtime/`.
 
 ---
 
@@ -97,7 +97,7 @@ 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.
+AI **MUST NOT** require the user to type shell wrappers such as `bash 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:
@@ -133,7 +133,7 @@ Awaiting: [what decision needed]
 **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.
+At the start of handling every user request, the AI **MUST** append a record to `docs/runtime/project/user-requests.jsonl` before doing substantive work.
 
 The log record **MUST** include:
 - Timestamp
@@ -141,11 +141,11 @@ The log record **MUST** include:
 - 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`
+- Hash chain fields when using `scripts/log-user-request.sh`
 
 The AI **MUST** use:
 ```bash
-bash core/scripts/log-user-request.sh "<user request text>"
+bash 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.
@@ -195,7 +195,7 @@ Required target ratio:
 ### G-006c: Test coverage threshold
 - **Diff coverage** (new code in the PR): ≥ 80%
 - **Overall coverage**: ≥ 70%
-- Configured in `config/project-config.yaml`
+- Configured in `docs/config/project-config.yaml`
 
 ---
 

package/{core/rules → rules}/02-code-quality.md

@@ -14,7 +14,7 @@ Code must be understandable, maintainable, testable, and safe to evolve. Passing
 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.
+Cyclomatic complexity MUST NOT exceed the configured threshold in `docs/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.

package/{core/rules → rules}/04-documentation.md

@@ -54,7 +54,7 @@ Known misleading docs for changed behavior MUST be fixed before release.
 ## 🛠️ Enforcement
 
 - Developer checklist in `/implement-task`.
-- PR template in `core/templates/pr/`.
+- PR template in `templates/pr/`.
 - Tech Lead review.
 - Release checklist in `/release`.
 - `bash scripts/validate-docs.sh` blocks missing documentation evidence in CI and pre-commit.

package/{core/rules → rules}/05-testing-mandatory.md

@@ -49,7 +49,7 @@ Mandatory workflow for every new feature/fix:
 
 ### RULE TEST-002: Coverage thresholds
 
-Configured in `config/project-config.yaml`:
+Configured in `docs/config/project-config.yaml`:
 
 | Metric | Threshold |
 |--------|-----------|
@@ -201,7 +201,7 @@ Endpoints on critical user flow **MUST** have performance tests:
 - **p95**: < 500ms
 - **p99**: < 1000ms
 
-Thresholds are customizable in `config/project-config.yaml`.
+Thresholds are customizable in `docs/config/project-config.yaml`.
 
 CI runs perf tests on main branch, alerts if regression > 20%.
 

package/{core/rules → rules}/06-approval-gates.md

@@ -221,7 +221,7 @@ Every ticket **MUST** have complete `state_history` array:
 }
 ```
 
-Schema validates this structure (see `config/ticket.schema.json`).
+Schema validates this structure (see `docs/config/ticket.schema.json`).
 
 ### RULE AG-009: Audit trail preserved
 
@@ -332,7 +332,7 @@ Definition of Done checklist (see rules/08-definition-of-done.md):
 Each agent's rules file references this doc. Agents refuse to bypass.
 
 ### Layer 2: JSON schema (medium)
-`config/ticket.schema.json` requires:
+`docs/config/ticket.schema.json` requires:
 - Valid state value
 - state_history array with required fields
 

package/{core/rules → rules}/08-definition-of-done.md

@@ -77,7 +77,7 @@ If a ticket does not pass DoD, it **MUST NOT** be closed. "Ship it, we'll fix la
 - [ ] Help docs updated, if user-facing
 
 ### 10. Ticket Hygiene
-- [ ] Ticket state updated in `project/tickets/`
+- [ ] Ticket state updated in `docs/runtime/project/tickets/`
 - [ ] `completed_at` timestamp set
 - [ ] PR URL linked
 - [ ] Release version tagged after release