ecoportal-api-graphql 1.3.11 → 1.3.13

data/.ai-assistance/scripts/bridge-inbox-check.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# bridge-inbox-check.sh -- session-start actuator for the bridge inbox.
+#
+# Closes an actuation-coverage gap: unread cross-project bridge messages used to be
+# visible only if someone manually ran a command. This is the trigger/clock that
+# surfaces them automatically at session start, mirroring the standards-inbox report
+# line (see CLAUDE.md and standards/governance/standards-request-protocol.md).
+#
+# DETERMINISTIC and zero-LLM: it just scans .ai-assistance/bridge/inbox/ for unread
+# messages (STATUS: PENDING) and prints one summary line plus one line per message:
+#
+#   [bridge] N unread message(s)
+#   - {title} from {FROM}
+#
+# Contract (mirrors the other hook scripts):
+#   - Silent (no output) and exit 0 when the inbox is empty or has no unread messages.
+#   - NEVER fails fatally -- always exits 0, even on a malformed file or missing dir.
+#   - No side effects: read-only, does not touch or move any message.
+#
+# Wired as a SessionStart hook in .claude/settings.json:
+#   bash scripts/bridge-inbox-check.sh 2>/dev/null || true
+#
+# Manual run (same output): bash scripts/bridge-inbox-check.sh
+set -u
+
+# Resolve the bridge inbox from this script's location so it works from any cwd.
+# This script is deployed at .ai-assistance/scripts/, so the inbox is a sibling
+# of the scripts dir: ../bridge/inbox (mirrors bridge-init.sh in this repo).
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)" || exit 0
+INBOX="$SCRIPT_DIR/../bridge/inbox"
+
+# No inbox -> nothing to report.
+[ -d "$INBOX" ] || exit 0
+
+# An "unread" message is a *.md file whose header carries STATUS: PENDING.
+# (PENDING = not yet picked up by the receiving agent; IN_PROGRESS/DONE/FAILED are read.)
+unread=""
+count=0
+
+for f in "$INBOX"/*.md; do
+  # Guard against the literal glob when the folder is empty.
+  [ -e "$f" ] || continue
+
+  # Only inspect the header block (first ~15 lines) -- cheap and format-stable.
+  header="$(head -n 15 "$f" 2>/dev/null || true)"
+
+  # Unread == STATUS: PENDING (case-insensitive, tolerant of surrounding whitespace).
+  printf '%s\n' "$header" | grep -Eiq '^[[:space:]]*STATUS:[[:space:]]*PENDING[[:space:]]*$' || continue
+
+  # Title: the text after "# TASK:" on line 1; fall back to the filename.
+  title="$(printf '%s\n' "$header" \
+    | grep -Ei '^#[[:space:]]*TASK:' \
+    | head -n 1 \
+    | sed -E 's/^#[[:space:]]*TASK:[[:space:]]*//' 2>/dev/null || true)"
+  [ -n "$title" ] || title="$(basename "$f" .md)"
+
+  # Sender: the text after "FROM:"; fall back to "unknown".
+  from="$(printf '%s\n' "$header" \
+    | grep -Ei '^[[:space:]]*FROM:' \
+    | head -n 1 \
+    | sed -E 's/^[[:space:]]*FROM:[[:space:]]*//I' 2>/dev/null || true)"
+  [ -n "$from" ] || from="unknown"
+
+  count=$((count + 1))
+  unread="${unread}- ${title} from ${from}
+"
+done
+
+# Silent when there is nothing unread.
+[ "$count" -gt 0 ] || exit 0
+
+printf '[bridge] %d unread message(s)\n' "$count"
+printf '%s' "$unread"
+
+exit 0

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

@@ -0,0 +1,319 @@
+---
+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-self-docs/SKILL.md

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