eco-helpers 3.2.14 → 3.2.16

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

@@ -0,0 +1,417 @@
+---
+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

data/.ai-assistance/skills/ruby-scripting/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: ruby-scripting
+version: 0.1.0
+description: >
+  AI coding assistant guidelines for internal Ruby scripts that consume ecoPortal's
+  Ruby gem stack (ecoportal-api-graphql, ecoportal-api, eco-helpers). Covers gem
+  authentication, GraphQL query patterns, mutation patterns, error handling, and
+  cross-platform script conventions (Windows/WSL/macOS/Linux).
+triggers:
+  - ruby script
+  - internal script
+  - ecoportal-api
+  - graphql query
+  - ruby-scripting
+  - write a ruby script
+applicable_to:
+  - ruby
+---
+
+# SKILL: Ruby Scripting (ecoPortal Internal)
+
+**Purpose:** Guidelines for AI-assisted authoring of internal Ruby scripts that use the ecoPortal gem stack. These scripts run internally — no customer access; Ruby is not a customer-facing language at ecoPortal.
+
+---
+
+## When to Use
+
+- Writing a new script that queries or mutates ecoPortal data via the GraphQL API
+- Debugging or extending an existing script in `ruby_scripts/` or similar
+- Any task involving `ecoportal-api-graphql`, `ecoportal-api`, or `eco-helpers`
+
+---
+
+## Gem Stack
+
+```
+ecoportal-api-graphql   ← GraphQL client layer (mutations, queries, models)
+       ↑
+ecoportal-api / ecoportal-api-v2   ← REST API + base model infrastructure
+       ↑
+eco-helpers             ← Utility helpers (pagination, bulk ops, etc.)
+```
+
+**Before writing any API call**, check:
+1. Does `eco-helpers` already have a helper for this operation? (It often does.)
+2. Does `ecoportal-api-graphql` already have a model/mutation class?
+3. Read `.ai-assistance/code/dependencies.md` in `ecoportal-api-graphql` for local paths.
+
+---
+
+## Authentication
+
+```ruby
+require 'ecoportal/api'
+
+api = Ecoportal::API::V2.new(
+  key: ENV.fetch('EP_API_KEY'),
+  host: ENV.fetch('EP_API_HOST', 'live.ecoportal.com')
+)
+```
+
+Always use `ENV.fetch` (not `ENV[]`) — raises on missing key rather than silently using nil.
+Store credentials in `.env` (gitignored). Never hardcode.
+
+---
+
+## GraphQL Query Pattern
+
+```ruby
+# Read models via GraphQL
+result = api.graphql.query do |q|
+  q.current_organization do |org|
+    org.name
+    org.users(first: 50) do |conn|
+      conn.nodes do |user|
+        user.id
+        user.email
+      end
+    end
+  end
+end
+
+# Check for errors before using data
+raise result.errors.map(&:message).join(', ') if result.errors.any?
+users = result.data.current_organization.users.nodes
+```
+
+**Pagination:** use `eco-helpers` pagination helpers for large result sets rather than
+writing manual cursor loops.
+
+---
+
+## Mutation Pattern
+
+```ruby
+# Mutations require patchVer for types that use optimistic locking
+# Always fetch before mutate for those types
+current = api.graphql.query { ... }.data.some_item
+result = api.graphql.mutate do |m|
+  m.update_item(input: {
+    id: current.id,
+    patch_ver: current.patch_ver,   # required for patchVer types
+    name: "New Name"
+  }) do |payload|
+    payload.item { |i| i.id; i.name }
+    payload.errors { |e| e.message; e.path }
+  end
+end
+
+raise result.errors.map(&:message).join(', ') if result.errors.any?
+raise result.data.update_item.errors.map(&:message).join(', ') \
+  if result.data.update_item.errors.any?
+```
+
+**patchVer rule:** any schema type with a `patchVer` field requires reading current value
+before any update. See `graphql-schema-analysis` skill for detection.
+
+---
+
+## Cross-Platform Script Conventions
+
+These scripts run on developer machines (Windows/WSL, macOS, Linux CI):
+
+```ruby
+# ✅ Safe: Ruby's File/Pathname handles separators cross-platform
+require 'pathname'
+base = Pathname.new(File.dirname(__FILE__))
+data_file = base / 'data' / 'input.json'
+
+# ❌ Unsafe: hardcoded separators, or shell assumptions
+data_file = "#{__dir__}\\data\\input.json"   # breaks on Linux
+`cat #{data_file}`                            # assumes Unix shell
+```
+
+**Environment detection:**
+```ruby
+WINDOWS = Gem.win_platform?
+# Use for platform-specific paths only — prefer Pathname for everything else
+```
+
+**Output:** use `$stdout.puts` not `print` for script output. Use `$stderr.puts` for
+errors. This allows the script to be piped and combined cleanly.
+
+**Exit codes:** always `exit 0` on success, `exit 1` on error. Never let an unhandled
+exception be the exit mechanism in production scripts.
+
+---
+
+## Error Handling
+
+```ruby
+begin
+  # API calls here
+rescue Ecoportal::API::Errors::ApiError => e
+  $stderr.puts "API error: #{e.message} (status: #{e.status})"
+  exit 1
+rescue => e
+  $stderr.puts "Unexpected error: #{e.class}: #{e.message}"
+  $stderr.puts e.backtrace.first(5).join("\n")
+  exit 1
+end
+```
+
+---
+
+## Script Structure Template
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Script: <name>.rb
+# Purpose: <one sentence>
+# Usage: ruby <name>.rb [options]
+# Dependencies: ecoportal-api-graphql, dotenv
+#
+# Run from repo root: bundle exec ruby scripts/<name>.rb
+
+require 'bundler/setup'
+require 'dotenv/load'
+require 'ecoportal/api'
+# ... other requires
+
+api = Ecoportal::API::V2.new(
+  key: ENV.fetch('EP_API_KEY'),
+  host: ENV.fetch('EP_API_HOST', 'live.ecoportal.com')
+)
+
+begin
+  # main logic here
+rescue => e
+  $stderr.puts "Error: #{e.class}: #{e.message}"
+  exit 1
+end
+```
+
+---
+
+## What NOT to do
+
+- Don't write raw HTTP calls to the EcoPortal API — use the gem stack
+- Don't paginate manually — use `eco-helpers` pagination
+- Don't hardcode API keys, hosts, or org identifiers
+- Don't use `pp` or `binding.pry` in committed scripts — use structured logging
+- Don't assume a Unix shell — use Ruby cross-platform file handling
+
+---
+
+## v0.1.0 limitations
+
+This skill covers general patterns. For area-specific details (specific GraphQL models,
+available mutation inputs, schema patterns), consult:
+- `ecoportal-api-graphql/.ai-assistance/code/` for code specs
+- `ecoportal-api-graphql/.ai-assistance/skills/graphql-schema-analysis/SKILL.md`
+- Live schema introspection (see graphql-schema-analysis skill)

data/.ai-assistance/standards-version.json

@@ -0,0 +1,10 @@
+{
+  "ep-ai-standards-version": "1.5.0",
+  "applied-at": "2026-06-13",
+  "project-type": ["ruby"],
+  "deferred": [],
+  "installed-components": {
+    "skills/ep-ai-manager": "2.1.0",
+    "skills/ruby-scripting": "0.1.0"
+  }
+}

data/.ai-assistance/token-budget.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": "1.0",
+  "project": {
+    "name": "eco-helpers",
+    "priority": "low",
+    "developer": "oscar@ecoportal.co.nz"
+  },
+  "weekly_quota": {
+    "total_tokens": null,
+    "target_utilization_pct": 75,
+    "reset_day": "monday",
+    "note": "total_tokens: null means track actuals without a hard cap. Set to e.g. 1000000 to enforce a budget."
+  },
+  "project_allocation": {
+    "priority_weights": {
+      "high": 50,
+      "medium": 30,
+      "low": 20
+    },
+    "note": "A 'high' priority project gets ~50% of the weekly budget; 'medium' gets ~30%; 'low' gets ~20%. These are soft targets — the system warns, not blocks."
+  },
+  "session_logging": {
+    "enabled": true,
+    "log_dir": ".ai-assistance/local/kpi",
+    "warn_at_pct": 80,
+    "prompt_category_at_stop": true
+  },
+  "task_categories": [
+    "coding",
+    "bug_fixing",
+    "bug_prevention",
+    "documentation",
+    "communication",
+    "post_release",
+    "troubleshooting",
+    "integration_delivery",
+    "skills_development"
+  ]
+}