eco-helpers 3.2.18 → 3.3.0

data/.ai-assistance/scripts/token-report.ts

@@ -1,158 +0,0 @@
-/**
- * token-report.ts
- *
- * Cross-project token usage report. Reads weekly session logs from all aligned
- * projects (via local/paths.md) and produces a management-ready summary.
- *
- * Usage:
- *   npx ts-node .ai-assistance/scripts/token-report.ts
- *   npx ts-node .ai-assistance/scripts/token-report.ts --week 2026-W24
- *   npx ts-node .ai-assistance/scripts/token-report.ts --format json
- *
- * Output: Markdown table (default) or JSON (--format json)
- * The report is printed to stdout — redirect to a file or pipe to your reporting tool.
- */
-
-import * as fs   from "fs";
-import * as path from "path";
-
-const SCRIPTS_DIR = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
-const AI_DIR      = path.join(SCRIPTS_DIR, "..");
-const CWD         = path.join(AI_DIR, "..", "..");
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-function isoWeek(d: Date): string {
-  const jan4 = new Date(d.getFullYear(), 0, 4);
-  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
-  return `${d.getFullYear()}-W${String(Math.ceil(((d.getTime() - s.getTime()) / 86400000 + 1) / 7)).padStart(2, "0")}`;
-}
-
-function loadJson<T>(p: string, fb: T): T {
-  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; }
-}
-
-interface ProjectPath { alias: string; localPath: string; }
-
-function loadProjectPaths(): ProjectPath[] {
-  const pathsFile = path.join(AI_DIR, "local", "paths.md");
-  if (!fs.existsSync(pathsFile)) return [{ alias: path.basename(CWD), localPath: CWD }];
-  const projects: ProjectPath[] = [];
-  const seen = new Set<string>();
-  for (const line of fs.readFileSync(pathsFile, "utf8").split("\n")) {
-    const m = line.match(/\|\s*`([^`]+)`\s*\|\s*`([^`]+)`/);
-    if (!m) continue;
-    const [, alias, rawPath] = m;
-    const localPath = rawPath.replace(/\//g, path.sep);
-    const real = fs.existsSync(localPath) ? fs.realpathSync(localPath) : localPath;
-    if (!seen.has(real) && fs.existsSync(localPath)) { projects.push({ alias, localPath }); seen.add(real); }
-  }
-  return projects.length ? projects : [{ alias: path.basename(CWD), localPath: CWD }];
-}
-
-interface WeeklyData {
-  week_id: string;
-  total_tokens: number;
-  projects: Record<string, { project: string; priority: string; tokens: number; tool_calls: number; turns: number; }>;
-}
-
-interface SessionTurn {
-  ts: string; session_id: string; project: string; priority: string;
-  week_id: string; turn_tokens: number; session_total_tokens: number;
-  tool_calls: number; estimated: boolean;
-}
-
-// ── Main ───────────────────────────────────────────────────────────────────
-
-const args    = process.argv.slice(2);
-const weekArg = args.includes("--week") ? args[args.indexOf("--week") + 1] : null;
-const format  = args.includes("--format") ? args[args.indexOf("--format") + 1] : "text";
-const weekId  = weekArg || isoWeek(new Date());
-
-const projects = loadProjectPaths();
-
-// Aggregate across all projects
-const byProject: Record<string, {
-  tokens: number; tool_calls: number; turns: number;
-  priority: string; sessions: number; estimated: number;
-}> = {};
-
-let grandTotal = 0;
-
-for (const { localPath } of projects) {
-  const kpiDir     = path.join(localPath, ".ai-assistance", "local", "kpi");
-  const weeklyFile = path.join(kpiDir, `weekly-${weekId}.json`);
-  const budget     = loadJson<any>(path.join(localPath, ".ai-assistance", "token-budget.json"), {});
-  const projectName= budget.project?.name || path.basename(localPath);
-  const priority   = budget.project?.priority || "medium";
-
-  if (!fs.existsSync(weeklyFile)) continue;
-
-  const weekly = loadJson<WeeklyData>(weeklyFile, { week_id: weekId, total_tokens: 0, projects: {} });
-
-  // Sum sessions for this project
-  let tokens = 0, toolCalls = 0, turns = 0, sessions = 0, estimated = 0;
-  for (const s of Object.values(weekly.projects)) {
-    if (s.project === projectName) {
-      tokens    += s.tokens;
-      toolCalls += s.tool_calls || 0;
-      turns     += s.turns || 0;
-      sessions++;
-    }
-  }
-
-  // Count estimated sessions from JSONL
-  const jsonl = path.join(kpiDir, `sessions-${weekId}.jsonl`);
-  if (fs.existsSync(jsonl)) {
-    const lines = fs.readFileSync(jsonl, "utf8").split("\n").filter(Boolean);
-    estimated = lines.filter(l => { try { return JSON.parse(l).estimated; } catch { return false; } }).length;
-  }
-
-  if (tokens > 0) {
-    byProject[projectName] = { tokens, tool_calls: toolCalls, turns, priority, sessions, estimated };
-    grandTotal += tokens;
-  }
-}
-
-if (format === "json") {
-  console.log(JSON.stringify({ week_id: weekId, grand_total_tokens: grandTotal, projects: byProject }, null, 2));
-  process.exit(0);
-}
-
-// ── Text report ────────────────────────────────────────────────────────────
-
-const sortedProjects = Object.entries(byProject)
-  .sort(([, a], [, b]) => b.tokens - a.tokens);
-
-console.log(`\n${"=".repeat(70)}`);
-console.log(`  Token Usage Report — ${weekId}`);
-console.log(`  Generated: ${new Date().toISOString().slice(0, 16)}`);
-console.log(`${"=".repeat(70)}\n`);
-console.log(`  Grand total: ${grandTotal.toLocaleString()} tokens across ${sortedProjects.length} project(s)\n`);
-
-console.log(`  ${"Project".padEnd(30)} ${"Priority".padEnd(10)} ${"Tokens".padStart(10)} ${"Share".padStart(7)} ${"Tool calls".padStart(12)} ${"Turns".padStart(6)}`);
-console.log(`  ${"-".repeat(78)}`);
-
-for (const [name, data] of sortedProjects) {
-  const share = grandTotal > 0 ? Math.round((data.tokens / grandTotal) * 100) : 0;
-  const est   = data.estimated > 0 ? " ~" : "  ";
-  console.log(`  ${name.padEnd(30)} ${data.priority.padEnd(10)} ${est}${data.tokens.toLocaleString().padStart(8)} ${`${share}%`.padStart(7)} ${data.tool_calls.toString().padStart(12)} ${data.turns.toString().padStart(6)}`);
-}
-
-console.log(`\n  ~ = some sessions used token estimation (transcript had no usage data)`);
-
-// Priority allocation analysis
-const targetPct = 75;
-const weights   = { high: 50, medium: 30, low: 20 };
-console.log(`\n  Priority allocation vs actuals (target utilization: ${targetPct}%):`);
-for (const priority of ["high", "medium", "low"]) {
-  const w = (weights as any)[priority];
-  const actual = Object.values(byProject)
-    .filter(p => p.priority === priority)
-    .reduce((s, p) => s + p.tokens, 0);
-  const actualPct = grandTotal > 0 ? Math.round((actual / grandTotal) * 100) : 0;
-  const projects  = Object.entries(byProject).filter(([, p]) => p.priority === priority).map(([n]) => n).join(", ") || "(none)";
-  console.log(`    ${priority.padEnd(8)} target ~${w}%  actual ${`${actualPct}%`.padStart(4)}  — ${projects}`);
-}
-
-console.log(`\n${"=".repeat(70)}\n`);

data/.ai-assistance/scripts/token-session-start.js

@@ -1,66 +0,0 @@
-#!/usr/bin/env node
-/**
- * token-session-start.js
- *
- * Claude Code SessionStart hook.
- * Checks current week's token usage, warns if over allocation,
- * and shows the budget status for this project.
- *
- * Wired in .claude/settings.json:
- *   "SessionStart": [{ "type": "command", "command": "node .ai-assistance/scripts/token-session-start.js" }]
- */
-
-const fs   = require("fs");
-const path = require("path");
-
-function isoWeek(d) {
-  const jan4 = new Date(d.getFullYear(), 0, 4);
-  const s = new Date(jan4); s.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
-  return `${d.getFullYear()}-W${String(Math.ceil(((d - s) / 86400000 + 1) / 7)).padStart(2, "0")}`;
-}
-function loadJson(p, fb) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fb; } }
-
-async function main() {
-  let event = {};
-  try { event = JSON.parse(fs.readFileSync("/dev/stdin", "utf8")); } catch {}
-
-  const cwd     = event.cwd || process.cwd();
-  const weekId  = isoWeek(new Date());
-  const budget  = loadJson(path.join(cwd, ".ai-assistance", "token-budget.json"), {});
-  const weekly  = loadJson(path.join(cwd, ".ai-assistance", "local", "kpi", `weekly-${weekId}.json`), { total_tokens: 0, projects: {} });
-
-  const project  = budget.project?.name || path.basename(cwd);
-  const priority = budget.project?.priority || "medium";
-  const total    = budget.weekly_quota?.total_tokens;
-  const targetPct= (budget.weekly_quota?.target_utilization_pct || 75);
-
-  // My project's tokens this week across all sessions
-  const myTokens = Object.values(weekly.projects)
-    .filter(p => p.project === project)
-    .reduce((s, p) => s + p.tokens, 0);
-
-  const lines = [`\n[token-budget] Week ${weekId} | Project: ${project} (${priority})`];
-  lines.push(`  All projects this week: ${weekly.total_tokens.toLocaleString()} tokens`);
-  lines.push(`  This project this week: ${myTokens.toLocaleString()} tokens`);
-
-  if (total) {
-    const usedPct = Math.round((weekly.total_tokens / total) * 100);
-    const weights = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
-    const myAlloc = Math.round(total * (targetPct / 100) * ((weights[priority] || 30) / 100));
-    const myPct   = myAlloc > 0 ? Math.round((myTokens / myAlloc) * 100) : 0;
-    lines.push(`  Week quota: ${usedPct}% used (target ${targetPct}%) | This project: ${myPct}% of ${myAlloc.toLocaleString()} alloc`);
-    if (usedPct >= targetPct) lines.push(`  !! Over weekly target — consider deferring low-priority work`);
-    if (myPct >= 90)          lines.push(`  !! This project near allocation limit`);
-  }
-
-  process.stderr.write(lines.join("\n") + "\n");
-
-  // Also run bridge-init if it exists
-  const bridgeInit = path.join(cwd, ".ai-assistance", "scripts", "bridge-init.sh");
-  if (fs.existsSync(bridgeInit)) {
-    const { execSync } = require("child_process");
-    try { execSync(`bash "${bridgeInit}"`, { stdio: "inherit" }); } catch {}
-  }
-}
-
-main().catch(() => {});

data/.ai-assistance/skills/ep-ai-manager/SKILL.md

@@ -1,417 +0,0 @@
----
-name: ep-ai-manager
-version: 2.2.0
-description: >
-  Manages alignment between this project's AI setup and the ecoPortal AI standards.
-  Phase 2: automated checklist checking against all standards, end-of-session KPI
-  and learning capture, migration plan application, token budget reporting.
-  Invoke at: session start, session end, or when you suspect drift.
-triggers:
-  - check AI standards
-  - AI alignment
-  - standards update
-  - eP_AI_Manager
-  - is my AI setup current
-  - apply migration
-  - end of session
-  - session wrap-up
-  - capture learnings
-  - token report
-  - file standards request
-  - report gap
-  - standards gap
-  - report to ep-ai-standards
-  - request standard
-standards_gitlab: "https://gitlab.ecoportal.co.nz/oscar/ep-ai-standards"
-standards_version_file: ".ai-assistance/standards-version.json"
-applicable_to:
-  - any
----
-
-# ep-ai-manager
-
-## Path resolution — always do this first
-
-Before any file access, resolve the ep-ai-standards path:
-
-1. Read `.ai-assistance/local/paths.json` in the current repo
-2. Find the entry with key `ep-standards` → use its `local_path` value as `<EP_STANDARDS>`
-3. If `paths.json` is missing or has no `ep-standards` entry:
-   ```
-   [ep-ai-manager] Cannot locate ep-ai-standards on this machine.
-   Fix: bash <ep-ai-standards>/scripts/install.sh --target . --mode retrofit
-   ```
-   Then stop — do not proceed with relative-path guesses.
-
-All file paths in these instructions that reference `<EP_STANDARDS>` mean this resolved value.
-
----
-
-## Role
-
-You are the AI standards alignment manager for this project. You run automated
-checks, capture session metrics, surface drift, and apply migration plans.
-You do not make changes without explicit developer confirmation.
-
----
-
-## On SESSION START — run automatically
-
-### 1. Token budget status
-
-Read `.ai-assistance/local/kpi/weekly-<YYYY-WNN>.json` (current ISO week).
-Report in one line:
-```
-[token-budget] Week YYYY-WNN: N tokens used across M sessions this project | budget: X% of allocation
-```
-If `.ai-assistance/token-budget.json` has `total_tokens: null`, report actuals only.
-If usage ≥ 80% of the project's priority allocation: warn in bold.
-
-### 2. Overdue deferral check
-
-Read `.ai-assistance/standards-version.json` → `deferred` array.
-For each deferred item, compare `deferred-at` + allowed window (60 days medium,
-14 days high, 0 days critical) to today.
-Report any overdue deferrals as: `[OVERDUE] <standard> deferred since <date> — must action now`
-
-### 3. Component version drift
-
-Read `.ai-assistance/standards-version.json` → `installed-components` map.
-Read `<EP_STANDARDS>/component-manifest.json` → `components` map.
-
-For each skill key in `installed-components`:
-- Look up the same key in the manifest
-- If not found in manifest: skip (local skill, not tracked)
-- Compare versions using semver. If local is `0.0.0` or `unknown`: treat as outdated (pre-versioning install)
-- If outdated: check `migration_required_from` — does any semver range key cover the local version?
-  - No match → classify **auto-apply** (file copy only)
-  - Match found → classify **migration-required** (note the migration folder ID)
-
-Report only when outdated components exist:
-```
-[standards-sync] N component(s) outdated — say "sync standards" to auto-apply:
-
-  skills/ep-ai-manager   2.0.0 → 2.1.0   auto-apply    (CHANGELOG 1.4.0)
-  skills/code-specs      0.0.0 → 1.0.0   auto-apply    (pre-versioning install)
-  skills/ruby-scripting  0.0.0 → 0.1.0   migration     run "apply migration 0002-slug"
-```
-
-If all components current:
-`[standards] All skills up to date — ep-ai-standards v{manifest.standards_release}`
-
-If `installed-components` key is missing from `standards-version.json` entirely:
-`[standards] installed-components not yet recorded — run "sync standards" to initialise`
-
----
-
-## On SESSION END / when explicitly invoked for wrap-up
-
-### 4. KPI capture prompt
-
-Ask the developer:
-```
-Session wrap-up — quick capture (skip any with 's'):
-
-1. Main task category today?
-   coding / bug_fixing / bug_prevention / documentation / communication /
-   post_release / troubleshooting / integration_delivery / skills_development
-
-2. Rough minutes saved by AI? (e.g. 60, or 's' to skip)
-
-3. Any skills developed? (e.g. ai-platform-architecture, s to skip)
-
-4. Any learnings worth capturing for the EPAI knowledge base?
-   Type a brief description, or 's' to skip.
-```
-
-On answers received:
-- Create/update `.ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl` with a record
-  matching the schema in `<EP_STANDARDS>/kpi/schema.json`
-- If a learning was described: create a draft at
-  `.ai-assistance/local/epai-drafts/EPAI-<date>-<slug>.md` using the format from
-  `<EP_STANDARDS>/standards/agents/corpus-source-taxonomy.md` → "Page template"
-
-### 5. Policy compliance reminder (if working on AI-related files)
-
-If the session involved changes to `agents/`, `iam/`, `lambdas/`, `config/`, or
-`.ai-assistance/skills/`:
-```
-[policy-check] Run before pushing: python3 scripts/policy-check.py --changed-only
-```
-
-### 6. LEARNING capture
-
-After the KPI prompt, ask:
-```
-Any learnings worth capturing? (one per line, or 's' to skip)
-Format: [type] description
-Types: gotcha | pattern | gap | lesson | correction
-
-Example: gotcha  bash here-docs with unicode fail on Windows cp1252
-```
-
-For each learning provided:
-- Write a `<!-- LEARNING: type -->` block to the current worklog entry (append to the
-  current session's Done section)
-- Create a draft file at `.ai-assistance/local/epai-drafts/EPAI-<YYYY-MM-DD>-<slug>.md`
-  using this template:
-  ```markdown
-  ---
-  type: <type>
-  project_origin: <project slug>
-  contributor_email: <developer email from KPI record>
-  date: <today>
-  status: draft
-  ---
-
-  # <one-line title>
-
-  <full description — self-contained, no assumed context>
-
-  ## Where it applies
-  <which agents/projects/patterns this affects>
-  ```
-
-Phase 1 note: once the EPAI Confluence space is created, this step will also create a
-Confluence page draft via Rovo MCP. Until then, drafts accumulate in local/epai-drafts/.
-
----
-
-## On-demand: FULL ALIGNMENT CHECK
-
-Run when explicitly invoked with "check alignment" or "check AI standards".
-
-For each standard in `<EP_STANDARDS>/standards/`:
-
-### standards/agents/skill-schema.md
-- [ ] Every directory in `agents/` has either `SKILL.md` or `system_prompt_file` in `agent.yaml`
-- [ ] SKILL.md frontmatter contains `name:`, `description:`, `triggers:`
-- [ ] `name:` follows `<team>-<agent>` format (grep: `^name: [a-z]+-[a-z]`)
-- [ ] Customer-facing SKILL.md has `<!-- BEGIN privacy_directive` marker
-
-### standards/agents/agent-manifest.md
-- [ ] Every `agents/` subdirectory that has a SKILL.md also has an `agent.yaml`
-- [ ] Every `agent.yaml` has: `name`, `team`, `role`, `status`, `owner`
-- [ ] Specialist agents have `corpus_prefix:`
-- [ ] Customer-facing agents have `automatic_learning_guard: true`
-- [ ] Operator agents have `escalation:` and `access_restriction:` blocks
-- [ ] No agent has `status: published` without being in the activation checklist
-
-### standards/agents/role-taxonomy.md
-- [ ] No operator agent appears in any orchestrator's `triggers:` or skill list
-- [ ] Operator agents have `escalation:` → `required: true`
-
-### standards/workflows/session-handoff.md
-- [ ] `docs/worklog.md` exists
-- [ ] `CLAUDE.md` contains the string "worklog"
-- [ ] Worklog has an entry within the last 5 working sessions (check for dated `## ` headings)
-
-### standards/security/pii-handling.md
-- [ ] No `real_value` field in any DynamoDB table definition or Lambda code
-- [ ] Customer-facing SKILL.md has complete `BEGIN/END privacy_directive` block
-- [ ] PII scrubber exists if corpus pipeline is used (check lambdas/)
-
-### standards/tooling/token-budget-management.md
-- [ ] `.ai-assistance/token-budget.json` exists
-- [ ] `project.name` and `project.priority` are filled in (not `{{PLACEHOLDER}}`)
-- [ ] `.claude/settings.json` has `Stop` and `SessionStart` hooks with `token-logger.js`
-- [ ] `.ai-assistance/local/` is in `.gitignore`
-
-### standards/tooling/cross-platform-ai-guidelines.md
-- [ ] No bash scripts in the repo exceed ~200 lines (check with `wc -l`)
-- [ ] No hardcoded `api.anthropic.com` (use AWS endpoint)
-
-### standards/kpi/schema.md
-- [ ] `kpi/records/` or `.ai-assistance/local/` is in `.gitignore`
-- [ ] At least one KPI session record exists (if AI has been used in the project)
-
-**For each check:**
-- PASS: note briefly
-- FAIL: give the specific file, what's wrong, what to do
-- WARN: note for awareness
-
-After all checks: `[alignment] N pass, N warn, N fail — project at ep-ai-standards vX.Y.Z`
-
----
-
-## On-demand: SYNC STANDARDS
-
-When the developer says "sync standards", "sync skills", or "apply auto updates":
-
-1. Re-read `installed-components` from `standards-version.json` and `component-manifest.json`.
-2. Build the list of **auto-apply** outdated components (those with no `migration_required_from` match).
-3. For each auto-apply component:
-   - Copy `<EP_STANDARDS>/{source}` to `.ai-assistance/skills/{skill-name}/SKILL.md`
-   - Update `installed-components["skills/{skill-name}"]` to the new version in `standards-version.json`
-   - Report: `[sync] Updated skills/ep-ai-manager 2.0.0 → 2.1.0`
-4. If `installed-components` was missing entirely, scan `.ai-assistance/skills/*/SKILL.md` now,
-   read each version, and write the full `installed-components` map before syncing.
-5. Update `ep-ai-standards-version` to `manifest.standards_release` and `applied-at` to today.
-6. Final summary: `[sync] N skill(s) updated. Run "check AI standards" to verify alignment.`
-7. If migration-required items remain: list them.
-   `[sync] N item(s) need migration — run "apply migration <id>" for each.`
-
-Never auto-apply a migration-required component without explicit "apply migration <id>" confirmation.
-
----
-
-## On-demand: APPLY MIGRATION PLAN
-
-When the developer says "apply migration" or "update standards":
-
-1. Read `.ai-assistance/standards-version.json` → current version
-2. Check if `<EP_STANDARDS>/migration/v{current}-to-v{target}/` exists
-3. Read `MIGRATION.md` — show the developer what will change and effort estimate
-4. **Ask for explicit confirmation before proceeding**
-5. If automated steps exist: `bash <EP_STANDARDS>/migration/.../automated/apply.sh --target .`
-6. Run verify.sh — show results
-7. Update `.ai-assistance/standards-version.json` → new version + `applied-at: today`
-
-Never run apply.sh without showing the developer its contents first.
-
----
-
-## On-demand: FILE STANDARDS REQUEST
-
-When the developer says "file a standards request", "report a gap", "standards gap",
-"report to ep-ai-standards", "request standard", or similar:
-
-1. Resolve `<EP_STANDARDS>` path (see Path resolution above).
-
-2. Prompt the developer (one message, all fields):
-   ```
-   Standards request — quick capture (press Enter to skip optional fields):
-
-   1. Type?  gap / inconsistency / improvement / error
-   2. Area?  skill / standard / template / convention / script
-   3. Affected?  e.g. skills-library/ep-ai-manager/SKILL.md
-   4. Title?  brief description (e.g. "ep-ai-manager trigger wording unclear")
-   5. Description?  what's wrong — be specific
-   6. Suggested fix?  (optional)
-   ```
-
-3. Build the request file:
-   - **repo-slug**: current repo's folder name, lowercased, spaces→hyphens
-     (e.g. `ecoportal-api-graphql` or `eco-extension`)
-   - **id**: 7 lowercase hex characters derived from the title (e.g. `a3f2b1c`)
-   - **slug**: title lowercased, spaces→hyphens, non-alphanumeric stripped, max 40 chars
-   - **filename**: `{repo-slug}-{id}-{slug}.md`
-
-4. Write to `<EP_STANDARDS>/.ai-assistance/local/standards-requests/{filename}`:
-
-   ```markdown
-   # STANDARDS REQUEST: {title}
-
-   STATUS: PENDING
-   FILED: {ISO 8601 timestamp}
-   FROM_REPO: {repo-slug}
-   TYPE: {type}
-   AREA: {area}
-   AFFECTED: {affected}
-
-   ## Description
-   {description}
-
-   ## Context
-   Filed during a {repo-slug} AI session.
-
-   ## Suggested fix
-   {suggested fix, or "None provided."}
-   ```
-
-5. Confirm to the developer:
-   ```
-   [standards-request] Filed: {filename}
-   Will be reviewed in the next ep-ai-standards session.
-   ```
-
----
-
-## On-demand: STANDARDS VERSION UPDATE
-
-When the developer says "update standards version" after manually applying changes:
-
-1. Ask: "Which version are you updating to? (e.g. 1.1.0)"
-2. Read `<EP_STANDARDS>/CHANGELOG.md` to confirm the version exists
-3. Update `.ai-assistance/standards-version.json` → `ep-ai-standards-version` and `applied-at`
-4. Confirm: "Updated to v{version}. Run full alignment check to verify?"
-
----
-
-## Deferral recording
-
-When a developer chooses to defer a finding:
-
-```json
-// Add to .ai-assistance/standards-version.json → deferred array:
-{
-  "standard": "tooling/claude-code",
-  "from-version": "1.0.0",
-  "severity": "medium",
-  "deferred-by": "oscar@ecoportal.co.nz",
-  "deferred-at": "2026-06-10",
-  "reason": "Bridge refactor planned for Q3",
-  "review-by": "2026-09-10"
-}
-```
-
-Calculate `review-by` automatically: medium = +60 days, high = +14 days.
-Critical deferrals are not recorded — escalate to Oscar immediately.
-
----
-
-## Severity handling
-
-| Severity | Deferral | At session start |
-|---|---|---|
-| `low` | Unlimited | Mention only if asked |
-| `medium` | 60 days | Warn after 30 days |
-| `high` | 14 days | Warn every session after 7 days |
-| `critical` | None | Block — escalate to Oscar |
-
----
-
-## EPAI draft format
-
-When capturing a learning, write to `.ai-assistance/local/epai-drafts/EPAI-<date>-<slug>.md`:
-
-```markdown
-# [<TYPE>] <Brief title>
-
-<!-- PAGE PROPERTIES -->
-contributor_email:     <developer email>
-project_origin:        <project name>
-consent_timestamp:     <today>
-usage_scope:           agent-corpus-eligible
-evidence_link:         <link to worklog session, commit, or MR>
-last_verified:         <today>
-source_type:           primary
-<!-- END PAGE PROPERTIES -->
-
-**Labels:** `epai-type:<type>` `epai-area:<area>` `epai-status:needs-review`
-
-## Observed Behaviour
-<What actually happened — factual, specific>
-
-## Why it matters
-<Impact if you don't know this>
-
-## Fix / Pattern
-<What to do>
-
----
-*Curator: verify evidence link before promoting to Consolidated*
-```
-
-Valid types: `gotcha`, `pattern`, `anti-pattern`, `gap`, `lesson`, `correction`,
-`environment-quirk`, `prompt-trigger`.
-
----
-
-## What this skill does NOT do
-
-- Does not make file changes without explicit developer confirmation
-- Does not apply migration scripts without showing contents first
-- Does not defer `critical` findings
-- Does not mark a check as PASS without verifying the actual file
-- Does not create EPAI drafts without the developer providing the learning