ecoportal-api 0.10.16 → 0.10.17

data/.ai-assistance/scripts/scrub.py.sha256

@@ -0,0 +1,6 @@
+# Blessed LF-normalized sha256 of scripts/lib/scrub.py (see scripts/rebless-scrub.py).
+# The Gemini egress transports (gemini_ask.rb, gemini-mcp-server.js) and
+# scripts/gemini-scrub-preview.py verify scrub.py against this hash BEFORE trusting it,
+# and REFUSE egress on mismatch. Re-bless ONLY after a human has reviewed the scrub.py
+# change: python scripts/rebless-scrub.py
+b2d56d92e245da489e6e3fe6a7f43235a00810009d38cb8b6a4fea9dc858eed3  scrub.py

data/.ai-assistance/scripts/surface-procedural.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# surface-procedural.sh -- SessionStart wrapper for the procedural-memory ACT stage.
+# Prints a short advisory preamble of distilled routines/traits/blind-spots (if any exist).
+# Reads only; never blocks (always exits 0). Logic lives in surface_procedural.py.
+# Standard: standards/workflows/procedural-memory.md ("Act").
+PY=python3
+command -v python3 >/dev/null 2>&1 || PY=python
+"$PY" "$(dirname "$0")/surface_procedural.py" || true
+exit 0

data/.ai-assistance/scripts/surface_procedural.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+surface_procedural.py -- Procedural-memory ACT stage (SessionStart hook).
+
+Standard: standards/workflows/procedural-memory.md ("Act").
+
+Prints a short preamble at session start summarising the developer's distilled `procedural`
+memory so it shapes the session:
+  - routines  -> "likely next steps" (highest-confidence first)
+  - reasoning-trait -> how to adapt the approach (Adapt by:)
+  - blind-spot -> a dismissable check to surface at the relevant moment (Surface as:)
+
+SessionStart hook stdout is added to the session context, so this preamble is how the Act
+stage reaches the model. It is advisory only -- it never blocks and never grants authority to
+act (HITL rules unchanged). Reads only; never writes. Always exits 0.
+
+Only surfaces entries at or above a display floor so a low-confidence probationary routine
+does not clutter every session.
+"""
+import os
+import re
+import sys
+
+DISPLAY_FLOOR = 0.5
+MAX_ROUTINES = 5
+
+_CONF = re.compile(r"(?im)^\*\*Confidence:\*\*\s*([0-9.]+)")
+_SUBTYPE = re.compile(r"(?im)^\*\*Subtype:\*\*\s*(\w[\w-]*)")
+_TRIGGER = re.compile(r"(?im)^\*\*Trigger:\*\*\s*(.+?)\s*$")
+_ACTION = re.compile(r"(?im)^\*\*Inferred action:\*\*\s*(.+?)\s*$")
+_PATTERN = re.compile(r"(?im)^\*\*Pattern:\*\*\s*(.+?)\s*$")
+_ADAPT = re.compile(r"(?im)^\*\*Adapt by:\*\*\s*(.+?)\s*$")
+_SURFACE = re.compile(r"(?im)^\*\*Surface as:\*\*\s*(.+?)\s*$")
+
+
+def _project_slug(cwd):
+    return os.path.abspath(cwd).replace(":", "-").replace("\\", "-").replace("/", "-")
+
+
+def _is_procedural(text):
+    if not text.startswith("---"):
+        return False
+    end = text.find("\n---", 3)
+    front = text[3:end] if end != -1 else ""
+    return re.search(r"(?im)^\s*type:\s*procedural\b", front) is not None
+
+
+def _collect(memory_dir):
+    routines, traits, blindspots = [], [], []
+    if not os.path.isdir(memory_dir):
+        return routines, traits, blindspots
+    for fn in sorted(os.listdir(memory_dir)):
+        if not fn.endswith(".md") or fn == "MEMORY.md":
+            continue
+        try:
+            text = open(os.path.join(memory_dir, fn), encoding="utf-8").read()
+        except OSError:
+            continue
+        if not _is_procedural(text):
+            continue
+        cm = _CONF.search(text)
+        conf = float(cm.group(1)) if cm else 0.0
+        sm = _SUBTYPE.search(text)
+        subtype = sm.group(1).lower() if sm else "routine"
+        if subtype == "reasoning-trait":
+            p = _PATTERN.search(text); a = _ADAPT.search(text)
+            traits.append((conf, p.group(1) if p else "?", a.group(1) if a else ""))
+        elif subtype == "blind-spot":
+            p = _PATTERN.search(text); s = _SURFACE.search(text)
+            blindspots.append((conf, p.group(1) if p else "?", s.group(1) if s else ""))
+        else:
+            t = _TRIGGER.search(text); a = _ACTION.search(text)
+            if t and a and conf >= DISPLAY_FLOOR:
+                routines.append((conf, t.group(1), a.group(1)))
+    routines.sort(reverse=True)
+    traits.sort(reverse=True)
+    blindspots.sort(reverse=True)
+    return routines, traits, blindspots
+
+
+def main():
+    cwd = os.getcwd()
+    memory_dir = os.environ.get("PROCEDURAL_MEMORY_DIR") or os.path.join(
+        os.path.expanduser("~"), ".claude", "projects", _project_slug(cwd), "memory")
+    routines, traits, blindspots = _collect(memory_dir)
+    if not (routines or traits or blindspots):
+        return 0
+    out = ["[procedural-memory] distilled routines for this repo (advisory -- inferences, not facts):"]
+    for conf, trig, act in routines[:MAX_ROUTINES]:
+        out.append(f"  - when {trig} -> likely next: {act}  (confidence {conf:.2f})")
+    for conf, pat, adapt in traits:
+        out.append(f"  - reasoning: {pat}" + (f" -> adapt: {adapt}" if adapt else ""))
+    for conf, pat, surf in blindspots:
+        out.append(f"  - watch-for (often missed): {pat}" + (f" -> check: {surf}" if surf else ""))
+    out.append("  (Correct a wrong one with <!-- RETIRE: <name> -->; confirm with <!-- CONFIRM: <name> -->.)")
+    print("\n".join(out))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,519 @@
+---
+name: ep-ai-manager
+category: governance
+version: 2.5.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 invocation
+
+Before any other output, do both of the following:
+
+1. Print to the user:
+   `[skill: ep-ai-manager] <one-line description of what you are about to do>`
+   Customise the description for the specific trigger -- for example:
+   - Session start: `[skill: ep-ai-manager] session-start check — token budget, drift, overdue deferrals`
+   - Session end: `[skill: ep-ai-manager] session-end wrap-up — KPI capture and candidate scheduling`
+   - Sync request: `[skill: ep-ai-manager] sync standards — pulling latest skill versions`
+   - Alignment check: `[skill: ep-ai-manager] full alignment check against all standards`
+
+2. Append a usage record to `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
+   (ISO week format: `YYYY-WNN`, e.g. `2026-W24`):
+   ```json
+   {"component": "skill/ep-ai-manager", "action": "<trigger>", "detail": "<same one-liner>", "ts": "<ISO timestamp>", "session_id": "<if known from token-budget session>"}
+   ```
+   Use `action` values: `session-start`, `session-end`, `invoked`, `completed`, `skipped`.
+   If the file or directory does not exist, create it. If writing fails, continue silently.
+
+---
+
+## On SESSION START -- run automatically
+
+### 0. Auto-worker run summary
+
+Check for `.ai-assistance/local/auto-worker-last-run.json`.
+If it exists and `run_date` is within the last 7 days, report:
+
+```
+[auto-worker] Last run: {run_date} — {completed_count} completed, {skipped_count} skipped
+  Branch: {branch} — ready for your review
+  Completed: {item1 brief} | {item2 brief}
+  Skipped: {item} — {reason}
+```
+
+If the file does not exist or `run_date` is older than 7 days: skip silently.
+
+### 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>
+  ```
+
+The EPAI Confluence space is live at https://ecoportal-projects.atlassian.net/wiki/spaces/EPAI/
+When a learning is captured, also create a Confluence page draft via Rovo MCP in that space.
+Local drafts continue to accumulate in local/epai-drafts/ as the source of record.
+
+### 7. Autonomous task candidates
+
+Read TODO.md. Apply the `auto-todo-worker` eligibility rules to find items that could
+run without human presence:
+
+**Eligible if ALL true:**
+- `[ ]` unchecked
+- Self-evident -- no design decision, ambiguity, or external dependency
+- No keywords: `confirm`, `legal`, `DevOps`, `human approval`, `Oscar`, `blocked on`,
+  `CTO`, `decision needed`, `verify with`, `check with`
+- Not ADR creation/modification
+- Not IAM, secrets, credentials, or live infrastructure
+- Not in `agents/` directory
+
+For each eligible item, estimate budget (typical ~30%; complex items ~45-60%).
+Detect simple dependencies: if item B's description references item A's title keywords,
+treat B as dependent on A.
+
+If eligible items exist, present the candidate list:
+```
+[scheduler] Tasks ready to run autonomously after you close:
+
+  1. {brief title}
+     → touches: {directory/area} | depends on: {item N or nothing} | est. ~{N}% budget
+
+  [concurrent: 1, 2] or [1 → 2 sequential]
+
+Say "schedule all", "schedule 1 2", or "skip" to dismiss.
+```
+
+On developer response:
+- `skip` or no response: do nothing
+- `schedule all` or `schedule <numbers>`: write `.ai-assistance/local/auto-worker-queue.json`:
+  ```json
+  {
+    "queued_at": "<ISO timestamp>",
+    "queued_by": "session-wrap-up",
+    "items": [
+      { "description": "<TODO item text, first 120 chars>", "depends_on": [] },
+      { "description": "<TODO item text>", "depends_on": [0] }
+    ]
+  }
+  ```
+  Confirm: `[scheduler] Queue written — auto-todo-worker will pick this up on next run.`
+
+If no eligible items found: skip this step silently.
+
+### 8. Token usage trend -- meta-ai-agent trigger
+
+Read `.ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl` for the current ISO week
+and the previous ISO week.
+
+Compute:
+- `current_median`: median `tokens_used` across all session records in the current week file
+- `prev_median`: median `tokens_used` across all session records in the previous week file
+
+If `current_median` >= 1.2 * `prev_median` (i.e. >= 20% above previous week), print:
+```
+[meta-ai-agent] Token usage up this week — consider running "meta review" to check for inefficiencies
+```
+
+If either week file is absent, or if the files contain no records with a `tokens_used`
+field, skip this step silently. Do not fail -- missing KPI data is not an error.
+
+---
+
+## 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