ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/skills/procedural-memory/SKILL.md

@@ -1,319 +0,0 @@
----
-name: procedural-memory
-category: governance
-version: 0.2.0
-status: draft
-description: >
-  Distills accumulated session signals into stored `procedural` memory entries
-  (recurring routines: a trigger condition + the action that reliably follows) and
-  surfaces them as likely next steps. Invoke on a periodic distill pass or when a
-  developer asks what patterns you have noticed in how they work.
-triggers:
-  - what patterns have you noticed
-  - distill my routines
-  - procedural memory
-  - how do I work
-  - learn my routines
-  - weekly distill
-  - modus operandi
-applicable_to:
-  - any
----
-
-# procedural-memory
-
-## Purpose
-
-Turn the substrate of accumulated session history into stored **`procedural`** memory --
-recurring routines, each expressed as a **trigger condition** and the **inferred action**
-that reliably follows it -- and surface those routines (plus a short "likely next steps"
-list) so the next session starts proactively shaped instead of from scratch.
-
-This skill operationalizes the **Distill** stage of the Observe -> Distill -> Act loop, plus
-the human-facing part of the **Act** stage (surfacing). It implements
-`standards/workflows/procedural-memory.md`. Observation (the `Stop`/`SessionEnd` logging
-substrate) and autonomous execution (the auto-worker) are out of scope here -- this skill
-reads the Observe substrate and writes the inferred routines; it never acts on them itself.
-
-> **v0.2.0 -- draft-aligned, blockers resolved.** This skill tracks
-> `standards/workflows/procedural-memory.md` at v0.2.0 (`status: draft`, ready for consolidation
-> review). It implements the now-decided **decay/retirement lifecycle** (D1) and **Observe-stage
-> privacy policy** (D2). The distill cadence, the minimum-observation threshold, the promotion
-> rule, and the lifecycle numbers (confidence steps, retirement floor, staleness/cool-off
-> windows) are all **provisional** and will firm up when the standard reaches `status: reviewed`.
-> Treat the numbers below as conservative defaults, not settled policy.
-
----
-
-## When to invoke
-
-- **On a periodic distill pass** -- e.g. weekly, or as part of an end-of-week wrap-up. This is
-  the primary mode: a scheduled mining pass over accumulated session history.
-- **On demand** -- when a developer asks "what patterns have you noticed in how I work?",
-  "distill my routines", or similar. Run the same procedure, scoped to the data available.
-
-Do not invoke this skill to *perform* a routine -- it only distils and surfaces. Acting on a
-surfaced routine is gated separately (see HARD CONSTRAINTS).
-
----
-
-## On invocation
-
-Before any other output, do both of the following:
-
-1. Print to the user:
-   `[skill: procedural-memory] <one-line description of what you are about to do>`
-   Examples:
-   - Periodic pass: `[skill: procedural-memory] weekly distill — mining usage log for recurring routines`
-   - On demand: `[skill: procedural-memory] reviewing session history for patterns in how you work`
-
-2. Append a usage record to `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
-   (ISO week format, e.g. `2026-W26`):
-   ```json
-   {"component": "skill/procedural-memory", "action": "invoked", "detail": "<same one-liner>", "ts": "<ISO timestamp>", "session_id": "<if known>"}
-   ```
-   Before writing, run the scrub/redaction pass (see Privacy below) over the record. If the file
-   or directory does not exist, create it. If writing fails, continue silently.
-
-### Consent check (do this first)
-
-The Observe log is **opt-in**. Before reading any `usage-*.jsonl` to mine routines, confirm the
-developer has enabled Observe (`procedural_memory.observe: true` in local settings, or the
-equivalent Observe-hook entry). If consent is not set, report that the Observe stage is not
-enabled, do NOT read the log, and stop. (Writing this skill's own invoked/completed usage
-records is the skill announcing itself and is unaffected by the Observe consent flag.)
-
----
-
-## The procedure
-
-### Step 1 -- Read the Observe substrate
-
-The Observe stage is append-only and machine-local; this skill only reads it. Read only after
-the consent check above has passed.
-
-- Read `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl` across the distill window (default: the
-  current and previous 3 ISO weeks). These records carry only low-sensitivity signal: command/
-  tool names (not arguments), file paths/types touched, components invoked, event types and
-  `action` values, and coarse durations/counts -- never full arguments, file contents, or
-  prompt/response text (see Privacy below). Parse defensively: skip malformed/corrupt JSON lines
-  rather than failing the whole pass.
-- Optionally read `docs/worklog.md` for `<!-- LEARNING: ... -->` markers. These are the
-  human-authored analogue of a `procedural` entry and may seed the distill pass
-  (`standards/workflows/session-handoff.md`).
-
-If no usage log exists, report that the Observe substrate is not yet populated and stop --
-there is nothing to distil. Do not invent routines from a single session.
-
-### Step 2 -- Mine for recurring patterns
-
-A pattern is a **trigger condition** plus the **action that reliably follows it** within the
-same or the next session. Look for:
-
-- An action that consistently follows a specific event (e.g. a code-spec regeneration that
-  follows every merge to `main`).
-- A consistent ordering of actions (e.g. tests -> lint -> commit).
-- A deferral that is consistently picked up at a predictable later point.
-
-**Minimum-observation threshold.** A pattern is only written if it was **observed in >= 3
-distinct sessions** in the window. This default is deliberately conservative to stop a one-off
-coincidence becoming a stored routine; the standard leaves the exact number open, so treat
-this as **provisional**. Below threshold: note it as a *candidate* in the report, but do not
-write a memory entry.
-
-### Step 3 -- Write each confirmed pattern as a `procedural` memory entry
-
-Write each pattern at or above threshold into the repo-scoped memory directory
-`~/.claude/projects/<project>/memory/` (auto memory -- repo-scoped and machine-local), as a
-memory entry of **type `procedural`**. The body carries **Trigger:** and **Inferred action:**
-lines, mirroring how `feedback` entries use **Why:** / **How to apply:**:
-
-```markdown
-## [Short routine name]
-
-**Trigger:** [the observed condition that recurs]
-**Inferred action:** [what the developer reliably does next]
-**Confidence:** 0.6
-**First-observed:** [YYYY-MM-DD]
-**Last-observed:** [YYYY-MM-DD]
-
-Observed in X of Y opportunities across N sessions (source: usage-<YYYY-WNN> ... usage-<YYYY-WNN>).
-```
-
-New entries start at **Confidence: 0.6** (provisional) -- above the retirement floor, below full
-trust, so a freshly inferred routine starts on probation. **First-observed** and **Last-observed**
-are both set to the current distill-pass date on first write. These three lines are required: they
-drive the decay/retirement lifecycle in Step 3b.
-
-Then add the index pointer line to `~/.claude/projects/<project>/memory/MEMORY.md`, matching
-the existing index style:
-
-```markdown
-- [Procedural: <short routine name>](<filename>.md) — <one-line trigger → action summary>
-```
-
-Mark the entry clearly as `procedural` so it stays distinguishable from `user`/`project`
-memory (see HARD CONSTRAINTS).
-
-### Step 3b -- Re-evaluate, decay, and retire existing routines
-
-On every distill pass, before reporting, walk each existing `procedural` entry and update its
-lifecycle metadata (standard D1). Honour forced markers first, then apply the arithmetic.
-
-1. **Forced markers (one-shot, applied first).** Scan `docs/worklog.md` and the memory files for:
-   - `<!-- RETIRE: <short routine name> -->` -- retire that routine immediately (see step 4
-     below), regardless of confidence or recency.
-   - `<!-- CONFIRM: <short routine name> -->` -- set its **Confidence** to `1.0` and refresh
-     **Last-observed** to today.
-   Record that the marker was applied so it is not re-applied on the next pass.
-
-2. **Re-evaluate against this window.** For each routine whose **Trigger** occurred at least once
-   in the window:
-   - trigger fired AND inferred action followed: refresh **Last-observed** to today and
-     **increment Confidence by +0.1**, capped at `1.0`;
-   - trigger fired but action did NOT follow: **decrement Confidence by -0.2** (contradiction
-     costs more than a single confirmation earns -- intentional asymmetry);
-   - trigger did not fire at all: leave Confidence unchanged; do NOT refresh Last-observed.
-
-3. **Retire** a routine when EITHER its **Confidence < 0.3** (floor) OR its **Last-observed** is
-   **older than 90 days** (staleness window). All thresholds provisional.
-
-4. **Archive on retirement -- never silent-delete.** Move the entry file to
-   `~/.claude/projects/<project>/memory/retired/`, appending the retirement date and reason
-   (`confidence floor` / `staleness` / `forced`). Remove its line from `MEMORY.md`. Keep a
-   tombstone (routine name + retirement date + reason). When mining (Step 2), if a re-detected
-   Trigger/Inferred-action pair matches a tombstone retired **within the last 30 days**
-   (cool-off, provisional), do NOT auto-write it -- surface it as a *candidate* for the developer
-   to re-confirm. After the cool-off it may be written fresh at the initial confidence.
-
-### Step 4 -- Promotion (propose only)
-
-A routine observed consistently **across multiple repos** is a candidate cross-project trait
-for user-global memory in `~/.claude/CLAUDE.md`. **Propose it -- do not auto-promote.** Present
-the candidate and the evidence; the developer decides. The exact promotion threshold is an
-open question in the standard and is provisional here.
-
-### Step 5 -- Act / surface
-
-Present the result to the developer:
-
-1. The distilled routines (newly written and pre-existing) for this repo.
-2. A short **"likely next steps"** list inferred from the current state and the routines.
-3. For routines whose inferred action is mechanically actionable, **PROPOSE** (never auto-add)
-   an `[auto]` tag so the auto-worker could pre-stage it -- subject to the developer confirming
-   the tag. The `[auto]` tag is the authorization boundary; eligibility rules in
-   `standards/tooling/auto-worker-eligibility.md` still apply, and this skill never tags
-   anything itself.
-
-After surfacing, append a completion usage record:
-```json
-{"component": "skill/procedural-memory", "action": "completed", "detail": "<N routines written, M candidates, K promotions proposed>", "ts": "<ISO timestamp>", "session_id": "<if known>"}
-```
-
----
-
-## HARD CONSTRAINTS
-
-From `standards/workflows/procedural-memory.md` -- these are not optional:
-
-- **A `procedural` entry is an inference, not an asserted fact.** It must remain visibly
-  distinguishable from `user`/`project` memory (which record things the developer stated), so
-  a wrong inference can be retired without eroding trust in asserted facts.
-- **Suggest, never act.** A distilled routine may *suggest* a next step or an `[auto]` tag, but
-  it must not drive an autonomous action without a human-in-the-loop confirmation. Any routine
-  that would trigger an irreversible or shared-system action is subject to
-  `standards/workflows/hitl-gates.md` -- inference grants no authority to act.
-- **Observe logging is opt-in, scrubbed, and machine-local (standard D2).** The Observe hook is
-  off by default; do not read the usage log to mine routines unless consent is set (see Consent
-  check). Capture only the documented allow-list -- command/tool names, file paths/types, event
-  types, durations -- and NEVER full arguments, file contents, diffs, or prompt/response text.
-  Run the scrub/redaction pass (regex for tokens/keys, emails, obvious PII; replace with typed
-  placeholders; drop a record that cannot be confidently scrubbed) BEFORE writing any record.
-  Never copy the log off the machine, into a versioned file, or into a `procedural`/promoted
-  entry -- entries store only the distilled Trigger/Inferred-action plus aggregate evidence.
-- **Decay and retirement are mandatory (standard D1).** Every `procedural` entry carries
-  **Confidence**, **First-observed**, and **Last-observed**. Each pass re-evaluates them, retires
-  entries below the floor or past the staleness window, honours `<!-- RETIRE: -->` /
-  `<!-- CONFIRM: -->` markers, and archives (never silently deletes) retired entries with a
-  cool-off tombstone so a retired routine does not silently reappear.
-- **Repo-relative paths only** in any versioned output. Use `~/.claude/...` solely as the
-  canonical memory location, never a developer's absolute filesystem path.
-
-### Privacy -- what the Observe log captures, redacts, and where it lives
-
-- **Captured:** command/tool names; file paths/types touched (repo-relative); event types and
-  `action` values; coarse durations and counts; timestamps, ISO-week, session id.
-- **Never captured:** full command arguments; file contents or diffs; prompt/response text; the
-  literal text of corrections/redirects (only that one occurred, and its coarse type); secrets,
-  tokens, credentials, env values.
-- **Redaction:** scrub-before-write -- regex detectors for tokens/keys (high-entropy strings,
-  `sk-`/`ghp_`/AWS-style prefixes), emails, obvious PII; matches replaced with `<REDACTED:...>`;
-  unscrubabble records dropped.
-- **Storage/consent:** lives only at `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
-  (machine-local, gitignored, never committed). Enable via `procedural_memory.observe: true` in
-  local settings; disable by removing it; the developer may delete the log at any time.
-
----
-
-## Example -- one mined pattern -> resulting `procedural` entry
-
-**Observed.** Over four ISO weeks the usage log shows that in 4 of 4 sessions ending with a
-merge to `main`, the same or next session regenerates code-specs and bumps the changelog
-before any new branch is opened. 4 sessions >= the threshold of 3, so it is written.
-
-Resulting file `~/.claude/projects/<project>/memory/procedural-merge-followup.md`:
-
-```markdown
-## Post-merge spec + changelog routine
-
-**Trigger:** a feature branch is merged to `main`.
-**Inferred action:** regenerate code-specs and bump the changelog before opening the next branch.
-**Confidence:** 0.6
-**First-observed:** 2026-06-28
-**Last-observed:** 2026-06-28
-
-Observed in 4 of 4 opportunities across 4 sessions (source: usage-2026-W22 ... usage-2026-W25).
-```
-
-On a later pass, if a merge to `main` is NOT followed by the spec+changelog action, Confidence
-drops by 0.2; sustained contradiction (or a `<!-- RETIRE: Post-merge spec + changelog routine -->`
-marker, or 90 days without observation) retires it to `memory/retired/`.
-
-Index line added to `MEMORY.md`:
-
-```markdown
-- [Procedural: Post-merge spec + changelog routine](procedural-merge-followup.md) — merge to main → regenerate code-specs + bump changelog
-```
-
-Surfaced at the next post-merge session as a likely next step, with a *proposal* (awaiting
-confirmation) to tag "regenerate code-specs `[auto]`".
-
----
-
-## What this skill does NOT do
-
-- Does not run the Observe stage -- it reads the usage log; it does not write session signals.
-- Does not execute any routine, autonomously or otherwise -- surfacing only.
-- Does not add an `[auto]` tag -- it proposes; the developer confirms.
-- Does not auto-promote a routine to `~/.claude/CLAUDE.md` -- it proposes; the developer decides.
-- Does not write a routine below the minimum-observation threshold.
-- Does not read the Observe log without consent set (Observe is opt-in, off by default).
-- Does not write any record to the usage log without first running the scrub/redaction pass.
-- Does not capture command arguments, file contents, diffs, or prompt/response text.
-- Does not copy machine-local log contents into any versioned or promoted file.
-- Does not silently delete a retired routine -- it archives to `memory/retired/` with a tombstone.
-- Does not re-write a routine retired within the cool-off window -- it surfaces it as a candidate.
-- Does not modify `user`/`project`/`feedback`/`reference` memory entries -- it only adds and
-  maintains `procedural` entries.
-
----
-
-## Version note
-
-v0.2.0 is aligned with `standards/workflows/procedural-memory.md` at v0.2.0 (`status: draft`,
-ready for consolidation review). It implements the now-decided decay/retirement lifecycle (D1)
-and Observe-stage privacy policy (D2). The distill cadence (weekly placeholder), the
-minimum-observation threshold (`>= 3 sessions`), the cross-repo promotion rule, and the lifecycle
-numbers (initial confidence 0.6, +0.1/-0.2 steps, 0.3 floor, 90-day staleness, 30-day cool-off)
-are all provisional. They will be revisited and firmed up when the standard reaches
-`status: reviewed`; this skill should be re-versioned to match.

data/.ai-assistance/skills/project-cycle/SKILL.md

@@ -1,177 +0,0 @@
-# SKILL: Project Preparation, Maintenance & Cycle
-
-**Purpose:** Capture, organise, and track a development project from intent through completion, including upstream dependency decisions and cycle-end review.
-
----
-
-## When to Use
-
-- A developer describes a new piece of work.
-- Picking up an existing project after a gap.
-- A cycle of changes is complete and needs a closing review.
-
----
-
-## Folder Structure
-
-```
-.ai-assistance/projects/<project-slug>/
-  INTENT.md          What we're trying to achieve and why
-  TODO.md            Ordered task list, ticked off as done
-  DECISIONS.md       Key decisions made and why
-  UPSTREAM.md        Upstream dependency changes needed (if any)
-```
-
-Project folders are **not git-ignored** — they should be committed so other developers can pick up context.
-
----
-
-## Starting a Project
-
-1. Ask the developer: "What are we trying to change and why?"
-2. Capture the answer in `INTENT.md` (see template below).
-3. Present it back: "Here's my understanding — does this capture it?" Iterate until confirmed.
-4. Break the intent into an ordered TODO list in `TODO.md`.
-5. If upstream deps are involved, create `UPSTREAM.md` and present options (patch, fork, new version).
-
-### INTENT.md template
-
-```markdown
-# Project: <Name>
-
-**Created:** YYYY-MM-DD
-**Status:** [active | paused | complete]
-**Branch:** feature/<slug>
-**Target branch:** main
-
-## Goal
-One paragraph: what we want to achieve.
-
-## Motivation
-Why now? What problem does this solve?
-
-## Scope
-What's in scope. What's explicitly out of scope.
-
-## Success Criteria
-How we'll know it's done.
-```
-
----
-
-## TODO.md format
-
-```markdown
-# TODOs — <Project Name>
-
-- [ ] Task description  <!-- add detail as needed -->
-- [x] Completed task
-```
-
-Tick items off as they're completed. Never delete items — the history matters.
-
----
-
-## DECISIONS.md format
-
-```markdown
-# Decisions — <Project Name>
-
-## [DATE] <Decision title>
-
-**Context:** What made this decision necessary.
-**Options considered:** Brief list.
-**Decision:** What was chosen.
-**Reason:** Why.
-**Consequences:** What this means going forward.
-```
-
----
-
-## Session Start — Git Orientation (Always Do This)
-
-Before any other work, run:
-
-```bash
-# 1. Confirm current branch
-git branch --show-current
-
-# 2. Check how far ahead of target branch
-git rev-list --count main..HEAD
-
-# 3. Get a cheap summary of what's changed
-git diff main...HEAD --stat
-```
-
-Cross-reference the diff stat against the active project's `TODO.md`:
-- Changed files should map to ticked TODO items.
-- Unticked TODOs with no corresponding changed files = work not yet started.
-- Changed files with no corresponding TODO = untracked work, worth noting.
-
-If **GitKraken MCP** is connected, use it instead — it returns the same information as structured data without a bash call.
-
-If the branch in `INTENT.md` doesn't match the current branch, flag it to the developer before proceeding.
-
----
-
-## Cycle-End Review
-
-When all TODOs are ticked:
-
-1. **Git summary:** Run `git diff main...HEAD --name-only` to get the exact file list.
-2. **Gemini review:** Pass changed files to `gemini-assist` using the `cycle_end_review.txt` prompt:
-   ```bash
-   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-     --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
-     --output .ai-assistance/projects/<slug>/gemini_review.txt \
-     --files $(git diff main...HEAD --name-only | tr '\n' ' ')
-   ```
-3. Review Gemini's output — verify each claim against actual code before acting.
-4. Propose fixes for genuine issues — confirm with developer.
-5. **If GitLab MCP is connected:** Check `get_merge_request_pipelines` to confirm CI is green.
-6. Update `INTENT.md` status to `complete`.
-7. Prompt: "Ready to open the MR / start the next project?"
-
----
-
-## Upstream Dependency Changes
-
-If changes require modifying an upstream gem:
-
-Options (present all three to developer):
-
-1. **Local patch** — monkey-patch from this gem. Fast, messy, temporary.
-2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
-3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
-
-Document the decision in `UPSTREAM.md` and `DECISIONS.md`.
-
----
-
-## Session / Collaborator Setup (First Time on a Machine)
-
-When starting a session and `.ai-assistance/local_paths.md` does not exist, run this setup flow **before** any project work:
-
-1. Tell the developer: "I don't see a `local_paths.md` for your machine yet. This helps me cross-reference upstream and downstream gem code without fetching from remotes every time."
-
-2. For each dependency in the table below, ask: "Do you have `<gem>` cloned locally?"
-
-   | Gem | Remote |
-   |-----|--------|
-   | `ecoportal-api` | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
-   | `ecoportal-api-v2` | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
-   | `graphlient` | https://github.com/rellampec/graphlient.git |
-   | `graphql-client` | https://github.com/rellampec/graphql-client.git |
-   | `eco-helpers` | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
-
-3. For each one they have locally:
-   - In **Cowork**: ask them to connect the folder (via the folder picker), then record the confirmed path.
-   - In **Claude Code**: ask them to provide the path, or run `find ~ -name "<gemspec>" -maxdepth 6 2>/dev/null` to locate it.
-
-4. Once all available paths are collected, create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md`, filling in only the repos they confirmed.
-
-5. Also ask: "Do you have GitKraken MCP or GitLab MCP set up?" — if not, point them to `.ai-assistance/integrations/`.
-
-6. Confirm: "Done — I've saved your local paths. You can update `.ai-assistance/local_paths.md` any time if your setup changes."
-
-If a developer doesn't have a repo locally and the task requires reading it, offer: "I can fetch the relevant files from the remote — just note it'll be slower. Want me to proceed that way?"

data/.ai-assistance/skills/project-self-docs/SKILL.md

@@ -1,181 +0,0 @@
----
-name: project-self-docs
-category: knowledge
-version: 0.2.0
-description: >
-  Generate and maintain a project's own committed self-documentation set (a stable-schema
-  OVERVIEW/ARCHITECTURE/CONVENTIONS/INTEGRATIONS/STATUS/COMPLIANCE/OPERATIONS) plus a machine-readable index and
-  changelog, so the project can later feed a central coordination hub. A thin orchestrator:
-  it reuses ai-discovery/code-specs/discovery-manifest findings and a deterministic scanner,
-  and never invents a documentation format. Invoke to create, refresh, or verify self-docs.
-triggers:
-  - self docs
-  - self-documenting
-  - project-self-docs
-  - generate project docs
-  - refresh self docs
-  - self document this project
-  - hub docs
-applicable_to:
-  - any
----
-
-# project-self-docs
-
-## Role
-
-You maintain a project's SELF-DOCUMENTATION set: a small, stable set of committed markdown docs
-that describe what the project is and how it is built, plus a machine-readable index and changelog
-that a central coordination hub can consume. You are a THIN ORCHESTRATOR -- you compose facts that
-`ai-discovery`, `code-specs`, and the deterministic scanner already produce; you do NOT re-analyse
-the codebase from scratch, and you do NOT invent a new documentation format. Everything you write
-is idempotent and re-runnable: running twice on an unchanged repo changes nothing.
-
-This capability is the per-project half of the synergy hub (ADR-015, Section 8; and ADR-014). It exists
-to detune the fleet by making reuse possible -- a project that documents itself against a shared
-schema is a project others can find and build on instead of duplicating.
-
----
-
-## On invocation
-
-Before any other output, do both of the following:
-
-1. Print to the user:
-   `[skill: project-self-docs] <one-line description of what you are about to do>`
-   For example:
-   - `[skill: project-self-docs] scanning repo and reporting self-doc status`
-   - `[skill: project-self-docs] refreshing STATUS.md and ARCHITECTURE.md from current state`
-   - `[skill: project-self-docs] creating the self-doc set for the first time`
-
-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/project-self-docs", "action": "invoked", "detail": "<same one-liner>", "ts": "<ISO timestamp>", "session_id": "<if known from token-budget session>"}
-   ```
-   Use `action` values: `invoked`, `completed`, `skipped`. If the file or directory does not
-   exist, create it. If writing fails, continue silently.
-
----
-
-## Before answering -- run the deterministic scan FIRST
-
-The deterministic scanner does the zero-LLM half. ALWAYS run it before writing any prose, so you
-spend interactive tokens only on the semantic gaps it cannot fill:
-
-```bash
-python .ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py --json
-```
-
-(From ep-ai-standards itself, the script lives at
-`skills-library/project-self-docs/scripts/self_docs_scan.py`.)
-
-The observation tells you deterministically: repo type, real repo name (from the remote), git
-head/branch, top-level structure, key config + CI files, activity clusters (hot paths), which
-existing inputs you can REUSE (`ai-discovery` `repo-context.md`/`conventions.md`, `code-specs`
-under `.ai-assistance/code/`), and which self-docs already exist with their current content hash.
-
-**Reuse before you write.** If `repo-context.md`, `conventions.md`, or code-specs exist, compose
-the self-docs from them -- do not re-derive the same facts. If they do NOT exist, propose running
-`ai-discovery` (first-time) or `code-specs` (per-area) first, rather than duplicating their work
-here.
-
----
-
-## The self-doc set (stable schema -- do not change filenames)
-
-Copy the templates from `templates/project-self-docs/` into the project's self-docs directory
-(default `docs/self-docs/`; configurable). The set is intentionally small and fixed:
-
-| File | Covers |
-|---|---|
-| `OVERVIEW.md` | What the project is, who it serves, current priority (one screen) |
-| `ARCHITECTURE.md` | Top-level structure, key components, how they fit, entry points |
-| `CONVENTIONS.md` | Coding style, branch naming, commit style, test conventions |
-| `INTEGRATIONS.md` | External services + data + permissions, upstream/downstream repos, dependencies |
-| `STATUS.md` | Active work, migration state, known risks, open questions |
-| `COMPLIANCE.md` | ISO-27001/audit, data classes + PII, third-party vendors, AI content, leak controls |
-| `OPERATIONS.md` | Infrastructure, public exposure + Cloudflare, DevOps audit runbook, usage KPIs/ROI |
-
-The set is the ROVO audit/compliance/discovery surface once mirrored into the EP Projects Register
-(`docs/strategy/self-docs-audit-schema.md`). Schema is `1.1`. Each file carries YAML frontmatter
-(`schema_version`, `repo`, `doc`, `last_generated`,
-`source_head`, `review_status`) so the hub can parse it and so a human review gate is explicit.
-Do NOT add, rename, or drop files without bumping the template `schema_version` and the scanner's
-`SELF_DOC_SET` together (they are checked as a pair).
-
-These docs are COMMITTED (not gitignored) -- they are the shareable artefact, unlike the
-gitignored `.ai-assistance/local/` context that `ai-discovery` writes.
-
----
-
-## Workflow
-
-1. **Scan.** Run `self_docs_scan.py --json`. Read the observation.
-2. **Reuse.** Pull facts from the existing inputs it lists. Only genuinely-missing semantic content
-   is yours to write.
-3. **Fill / refresh.** For each self-doc: if missing, copy the template and fill it; if present,
-   update only the sections whose underlying facts changed (structure, hot paths, status). Keep
-   `review_status: draft` on anything a human has not confirmed.
-4. **Batch heavy semantic work to Gemini.** For a large or unfamiliar repo, draft
-   ARCHITECTURE/OVERVIEW via the `gemini-assist` skill (no-training tier) rather than on
-   interactive Claude tokens -- per the token-frugality rule. Verify Gemini's output against the
-   scanner facts before writing.
-5. **Write the index + changelog (deterministic).** Run:
-   ```bash
-   python .ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py --write
-   ```
-   This rewrites `docs/self-docs/self-docs-index.json` (the machine surface the hub reads) and
-   APPENDS one line per changed doc to `docs/self-docs/CHANGES.jsonl`. A no-op re-run appends
-   nothing -- this is what makes the capability idempotent.
-6. **Human review before any egress.** Leave publishing to a human-reviewed step (see below).
-
----
-
-## Publish / egress -- CONFIGURABLE, default local-only (OPEN DECISION)
-
-The Confluence publish destination is an OPEN DECISION being made separately (existing EPAI space
-vs a new dedicated hub space vs the private EP-AI-MGMT space). Therefore:
-
-- **Default: write to the repo/local filesystem ONLY.** This skill does not push to Confluence.
-- The publish target is a PARAMETER, not a hardcoded value. When the decision is made, the egress
-  step becomes a call to the existing seed pipeline (`scripts/seed-epai-project-docs.py` pattern)
-  pointed at the chosen space, gated by human review.
-- <!-- TODO(hub-target): wire egress to the chosen Confluence space once the publish-target
-  decision lands. Until then, self-docs live in docs/self-docs/ and are consumed from git. -->
-
-Never emit `r` (a result) straight to a shared surface: a human review gate sits between the
-generated self-docs and any hub publish. This is a damping control -- keep it.
-
----
-
-## Actuation
-
-- **Actor:** a developer (or `ai-discovery`/`project-cycle` calling this skill) IN THE REPO THAT
-  DOCUMENTS ITSELF, never an unattended agent -- and NEVER an ep-ai-standards session reaching into
-  another repo to generate that repo's self-docs. ep-ai-standards AUTHORS + DEPLOYS this skill and
-  AGGREGATES/publishes results; each repo RUNS it in its own session. (Running it on ep-ai-standards
-  ITSELF is fine -- that is why `docs/self-docs/` exists here.)
-- **Trigger / clock:** on demand; recommended at project cycle-end (`project-cycle`) and after a
-  structural change. There is no autonomous fleet-wide trigger yet -- that depends on the unbuilt
-  ADR-014 upkeep loop; note this rather than inventing an actuator.
-- **Coverage on neglect:** if self-docs are never refreshed, the scanner's `content_hash` +
-  `source_head` in the index let the hub (and `project-review`) flag them as stale. The doc is
-  never silently trusted; staleness is detectable.
-- **Write authority:** writes ONLY under the self-docs directory (default `docs/self-docs/`), plus
-  the KPI usage line. It does not touch source code, `.ai-assistance/local/`, git remotes, or any
-  network target.
-
----
-
-## What you do not do
-
-- Do not invent a documentation format -- use the fixed self-doc set and templates.
-- Do not re-analyse the codebase from scratch -- reuse `ai-discovery`, `code-specs`, and the
-  scanner; propose running those skills if their inputs are missing.
-- Do not publish to Confluence or any network target -- egress is a separate, human-gated,
-  as-yet-undecided step.
-- Do not write outside `docs/self-docs/` (or the configured self-docs dir).
-- Do not run heavy semantic drafting on interactive Claude tokens for large repos -- batch to
-  Gemini (no-training tier).
-- Do not mark a doc `review_status: reviewed` -- only a human does that.