ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/skills/code-specs/SKILL.md

@@ -0,0 +1,69 @@
+# SKILL: Code Specs for AI
+
+**Purpose:** Maintain AI-readable markdown documentation in `.ai-assistance/code/` so that future AI agents don't need to re-analyse code from scratch. These docs are shortcuts, not replacements — when real analysis is needed, always update them.
+
+---
+
+## When to Use
+
+- After analysing a new area of the codebase.
+- Before starting work in an area — check if a doc exists and whether it's stale.
+- After making changes that alter the understanding of an area.
+- Periodically (especially at project cycle-end) — use Gemini Assist to spot stale sections.
+
+---
+
+## Document Structure
+
+Each code spec document (`.ai-assistance/code/<area>.md`) must include:
+
+```markdown
+# Code Spec: <Area Name>
+
+**Scope:** What this document covers. What it explicitly does NOT cover.
+**Last updated:** YYYY-MM-DD
+**Key files:** List of the most important files in this area.
+
+---
+
+## Overview
+Brief description of what this area does and its role in the gem.
+
+## Key Classes / Modules
+For each significant class: one-line purpose, key public methods/interface.
+
+## Patterns & Conventions
+Design patterns, inheritance chains, naming conventions specific to this area.
+
+## Dependencies
+What this area depends on (internal and external). What depends on it.
+
+## Gotchas / Non-Obvious Behaviours
+Things that would cause confusion or bugs if not known upfront.
+
+## TODOs / Open Questions
+Pending items specific to this area. Link to project TODO if applicable.
+```
+
+---
+
+## Naming & Placement
+
+Mirror the `lib/` structure:
+
+| Code area | Doc path |
+|-----------|---------|
+| `lib/ecoportal/api/graphql/model/` | `.ai-assistance/code/model.md` |
+| `lib/ecoportal/api/graphql/input/` | `.ai-assistance/code/input.md` |
+| `lib/ecoportal/api/graphql/logic/` | `.ai-assistance/code/logic.md` |
+| Whole gem overview | `.ai-assistance/code/OVERVIEW.md` |
+
+For deeply nested areas, use subdirectories: `.ai-assistance/code/model/location_structure.md`
+
+---
+
+## Keeping Docs Fresh
+
+- When you read a file and find something the doc doesn't mention — add it.
+- When a refactor changes a class — update the corresponding doc.
+- Use the `gemini-assist` skill for batch reviews of multiple docs vs. current code.

data/.ai-assistance/skills/corporate-policies/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: corporate-policies
+version: 1.0.0
+description: >
+  Check current work against ecoPortal's corporate policies and compliance requirements.
+  Flags potential policy violations before code is committed or an MR is opened.
+  Invoke before any MR touching data handling, IAM, external integrations, AI tooling,
+  or customer-facing behaviour.
+triggers:
+  - check policies
+  - compliance check
+  - corporate policies
+  - policy review
+  - is this compliant
+  - corporate-policies
+  - DevOps approval
+applicable_to:
+  - any
+---
+
+# SKILL: Corporate Policies Check
+
+**Purpose:** Check current work against ecoPortal corporate policies before committing
+or opening an MR. Sources: ecoPortal Confluence space `EP` → "ecoPortal Policies"
+(parent page 843284546). Policies are available as corpus files prefixed `policy_`.
+
+---
+
+## Policy sources (Confluence EP space)
+
+| Policy | Page ID | Relevance to AI work |
+|---|---|---|
+| AI Usage Policy | 2058158100 | **Primary** — tool approval, customer data, HITL |
+| Information Security Policy | 882343949 | Data handling, access, confidentiality |
+| Privacy Compliance Policy | 1026916353 | PII protection, consent, privacy-by-design |
+| GDPR Compliance Policy | 1036353542 | EU/EEA data subjects, processing obligations |
+| Data Management Policy | 863862785 | Classification, retention, confidential data |
+| Secure Development Policy | 885751824 | Security in dev lifecycle, privacy-by-design |
+| Access Control Policy | 860684291 | Least privilege, credential management |
+| Secure Engineering Principles | 970391561 | Least privilege, auditability, fail-safe defaults |
+| Risk Management Policy | 883753045 | Risk assessment for data-handling systems |
+
+---
+
+## Universal directives — ALL agents and ALL AI-assisted work
+
+These directives apply regardless of agent type, project, or task. Each lists the
+source policy so compliance decisions can be traced.
+
+### 1. Human oversight required before any customer-impacting decision
+**Source:** AI Usage Policy — "Allowing AI tools to make autonomous decisions that
+impact customers without human oversight" is **prohibited**.
+
+In practice:
+- Operator agents (`platform/engineer`, `platform/cicd`) must have a HITL gate before
+  any external write action (GitLab commit, Jira update, MR creation)
+- AI-generated content sent to customers must be reviewed by a human first
+- AI must not autonomously change customer data, permissions, or billing
+
+### 2. All AI output must be reviewed before use in business decisions
+**Source:** AI Usage Policy — "Users must evaluate the accuracy, fairness, and
+reliability of AI-generated outputs before using them in business decisions or
+customer-facing materials."
+
+In practice:
+- Gemini architectural review output → verify each claim against actual code
+- Agent-generated code → developer reviews before committing
+- AI-drafted communications → reviewed and reworded before sending
+- Flag: "AI-generated content" or "AI-assisted" in any output sent upward
+
+### 3. Transparency about AI involvement
+**Source:** AI Usage Policy — "Be transparent about when AI has supported your work."
+
+In practice:
+- MR descriptions note when code was AI-generated
+- Reports note when AI assistance was used (see report template)
+- No presenting AI output as purely human-authored
+
+### 4. Customer data classification before processing by any AI tool
+**Source:** AI Usage Policy — "It is your team lead's responsibility to classify data
+being processed and confirm if it includes customer information, PII, or sensitive
+content."
+
+In practice:
+- Before sending ANY content to an AI API: classify it first
+- If data is classified as containing PII or customer data → it must be scrubbed first
+  (category substitution as per ADR-010) OR the tool must be pre-approved by DevOps
+- The corpus pipeline PII scrubber handles this for Confluence content
+
+### 5. DevOps approval for AI tools processing customer data
+**Source:** AI Usage Policy — "Any AI tool, platform, or service that processes or
+accesses customer data must be approved in advance by the DevOps team."
+
+**Currently approved tools** (from AI Usage Policy approval table):
+- Claude Code (Claude Sonnet) — approved by DevOps, Business tier, free use
+- Claude Platform on AWS — approved (covered under ecoPortal AI platform initiative)
+- Google Workspace AI (Gemini) — approved, ecoPortal accounts only
+- GitHub Copilot — approved by DevOps
+- JetBrains IDEs (AI features) — approved by DevOps
+
+**NOT approved for customer data:**
+- ChatGPT (personal account) — discouraged; requires paid licence for PII use
+- Any tool not in the approved list above
+
+### 6. Least privilege for all system components
+**Source:** Access Control Policy — "ecoPortal shall determine the type and level of
+access granted to individual users based on the principle of least privilege."
+**Source:** Secure Engineering Principles — "Each system component should have the
+minimum permissions required to perform its function."
+
+In practice:
+- Lambda IAM roles scoped to specific resources (not wildcard)
+- Agent credentials limited to read-only where possible
+- No shared credentials between agents or developers
+
+### 7. All actions must be auditable and logged
+**Source:** Secure Engineering Principles — "All actions should be logged and tracked
+so that any security breaches can be traced and investigated."
+**Source:** Information Security Policy — access and change logging required.
+
+In practice:
+- Corpus pipeline Lambda logs every PII encounter (SHA-256 audit trail)
+- Session logs retain enough metadata to reconstruct what happened (never raw PII)
+- Agent actions (MR creation, Jira updates) logged with timestamp and actor
+
+### 8. PII must be protected with category substitution and irreversible hashing
+**Source:** Privacy Compliance Policy — "technical, physical, and administrative
+safeguards to maintain the security, confidentiality, and privacy of personal data."
+**Source:** GDPR Compliance Policy — applies to EU/EEA data subjects.
+
+In practice: ADR-010 (category substitution, SHA-256 + salt). See `standards/security/pii-handling.md`.
+
+### 9. Input validation and secure coding practices required
+**Source:** Secure Development Policy — "secure coding practices including input
+validation, error handling, and other security controls."
+**Source:** Secure Engineering Principles — "input validation" listed as a mandatory
+secure coding practice.
+
+In practice:
+- External API responses never used directly in file paths (path traversal risk)
+- SQL/command injection prevention for any Lambda that builds queries
+- See `docs/CONVENTIONS.md` → "TypeScript / Node" section
+
+---
+
+## Specialist agent additional directives
+
+For agents that interact with customer-facing workflows:
+
+### 10. No automatic learning from customer sessions
+**Source:** AI Usage Policy — autonomous decisions prohibited.
+See `standards/security/pii-handling.md` and ADR-010.
+
+### 11. Legal review before any customer-facing agent goes live
+**Source:** Privacy Compliance Policy + GDPR Compliance Policy — consent mechanism
+and lawful basis for data processing must be established.
+
+---
+
+## Operator agent additional directives
+
+### 12. HITL gate + token ceiling before `published` status
+**Source:** AI Usage Policy — autonomous decisions on customers prohibited.
+See `agents/README.md` → activation checklist.
+
+### 13. All external write actions require explicit human confirmation
+**Source:** AI Usage Policy — "AI shouldn't be the final decision-maker."
+
+---
+
+## Workflow — how to use this skill
+
+1. Identify which policy areas the current work touches (see table above)
+2. For each relevant area, check the directive list above
+3. Report findings in this format:
+   ```
+   Policy check: <description of change>
+
+   POLICY COMPLIANT
+   ✓ Least privilege: Lambda role scoped to specific table ARN
+   ✓ Auditability: PII encounters logged with SHA-256 hash
+
+   POLICY CONCERN
+   ✗ DevOps approval: this new AI tool (X) processes customer emails
+     → ACTION: submit Tool Request to devops@ecoportal.com before deployment
+
+   POLICY NOTE
+   ~ GDPR: this feature serves EU customers — confirm lawful basis with Legal
+   ```
+4. Blocking concerns (✗) must be resolved before MR is opened
+5. Notes (~) must be documented in the MR description
+6. For novel situations not covered by these directives: contact devops@ecoportal.com
+
+---
+
+## What this skill does NOT do
+
+- Does not make final compliance decisions — flags for human review
+- Does not cover HR, contractual, or Code of Conduct policies
+- Does not replace Legal review for customer-facing agents (hard gate in ADR-010)
+- Does not cover physical security, visitor management, or non-technical policies

data/.ai-assistance/skills/dep-graph/SKILL.md

@@ -0,0 +1,139 @@
+# SKILL: Dependency Graph
+
+**Purpose:** Generate a JSON structural map of the gem's class/module hierarchy and
+inter-file relationships — zero new gem dependencies (uses Ruby stdlib only).
+Feed the output to Claude before any cross-namespace refactor, feature addition, or
+`require` chain change to avoid broken references and wasted grep passes.
+
+---
+
+## When to Use
+
+- Before refactoring any area that spans multiple files or namespaces.
+- Before adding a new class that needs to fit into the existing hierarchy.
+- When Code asks "where is X defined?" or "what includes Y?" — run this first.
+- After a significant set of changes, to verify the structure matches intent.
+
+---
+
+## Rake Task
+
+Add to `Rakefile` (one-time setup — see **Branch Setup** below):
+
+```ruby
+desc 'Generate JSON dependency/structure map → .ai-assistance/code/dep-graph.json'
+task :dep_graph do
+  require 'json'
+  require_relative '.ai-assistance/scripts/dep_graph'
+  DepGraph.run(
+    lib_dir:     'lib',
+    output_path: '.ai-assistance/code/dep-graph.json'
+  )
+  puts "Written → .ai-assistance/code/dep-graph.json"
+end
+```
+
+Run it:
+
+```bash
+bundle exec rake dep_graph
+```
+
+---
+
+## Script
+
+The script lives at `.ai-assistance/scripts/dep_graph.rb`.
+
+What it captures per file:
+- `defines`  — every `module`/`class` name (fully qualified, tracking nesting)
+- `requires` — every `require_relative` path
+- `includes` — every `include`, `extend`, `prepend` target
+
+Output format:
+
+```json
+{
+  "lib/ecoportal/api/graphql/model/action.rb": {
+    "defines":  ["Ecoportal::API::GraphQL::Model::Action"],
+    "requires": [],
+    "includes": ["Ecoportal::API::Common::GraphQL::Model::AsInput"]
+  }
+}
+```
+
+---
+
+## Asking Claude to Summarise a Namespace
+
+After running `rake dep_graph`, ask:
+
+> "Read `.ai-assistance/code/dep-graph.json` and summarise the dependency structure
+> of the `Ecoportal::API::GraphQL::Logic` namespace as a Mermaid class diagram."
+
+Claude will emit a scannable diagram like:
+
+```mermaid
+classDiagram
+  direction LR
+  class BaseQuery
+  class Query
+  class Mutation
+  class QueryConnection
+  Query --|> BaseQuery
+  Mutation --|> BaseQuery
+  QueryConnection --|> BaseQuery
+```
+
+---
+
+## Workflow
+
+1. Run `bundle exec rake dep_graph` — takes < 1 second.
+2. Read `.ai-assistance/code/dep-graph.json` (or ask Claude to summarise a slice of it).
+3. Proceed with the refactor / feature work with full structural context.
+4. Re-run after changes to verify the structure is consistent with intent.
+
+---
+
+## Branch Setup
+
+This skill requires two one-time changes on branch `feature/dep-graph-skill`:
+
+### 1. Rakefile — add the `dep_graph` task
+
+```ruby
+desc 'Generate JSON dependency/structure map → .ai-assistance/code/dep-graph.json'
+task :dep_graph do
+  require 'json'
+  load '.ai-assistance/scripts/dep_graph.rb'
+  DepGraph.run(
+    lib_dir:     'lib',
+    output_path: '.ai-assistance/code/dep-graph.json'
+  )
+  puts "Written → .ai-assistance/code/dep-graph.json"
+end
+```
+
+### 2. `.gitignore` — exclude the generated output
+
+```
+.ai-assistance/code/dep-graph.json
+```
+
+The script itself (`.ai-assistance/scripts/dep_graph.rb`) is committed.
+The generated output is not — it is always fresh on demand.
+
+No gemspec changes needed. No new runtime or development gems required.
+
+---
+
+## Notes
+
+- **rubrowser** (gem) was evaluated and rejected: its runtime deps (`puma`, `litecable`,
+  `websocket`) are disproportionate for JSON-only output. The stdlib approach here gives
+  identical structural data with zero overhead.
+- The script uses regex + a nesting stack rather than a full AST parser. This is
+  intentional: it is fast, has no deps, and the codebase's consistent `module`/`class`/`end`
+  style makes regex reliable here. If the codebase ever uses single-line class definitions
+  or heavy metaprogramming, revisit.