ecoportal-api 0.10.16 → 0.10.17

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

@@ -0,0 +1,259 @@
+---
+name: project-self-docs
+category: knowledge
+version: 0.4.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).
+
+### ARCHITECTURE.md diagrams (mermaid) -- the "something visual that really adds up"
+
+`ARCHITECTURE.md` carries a `## Diagrams` section (see
+`templates/project-self-docs/ARCHITECTURE.md.template`) instructing the in-repo session to render
+**2-4 mermaid diagrams**, chosen from:
+
+1. **Component / layer diagram with trust boundaries** -- e.g. a PII-scrubber layer, a public/
+   private network split, an authenticated/unauthenticated boundary.
+2. **CI/CD pipeline graph** -- derived from the repo's real CI config (e.g. `.gitlab-ci.yml`,
+   `.github/workflows/*.yml`): one node per real job/stage, edges from real `needs`/stage order.
+3. **Data-flow diagram for privacy-relevant paths** -- source -> scrub/transform -> egress, naming
+   the real modules/scripts at each hop (only when the repo has such a path; see COMPLIANCE.md).
+4. **Deployment topology (optional)** -- only when infra-as-code or deployment config exists
+   (CDK/Terraform/Dockerfile/docker-compose).
+
+Hard rules for whoever fills this section (the in-repo session, never an ep-ai-standards session
+reaching into another repo -- same actuation boundary as the rest of this skill):
+
+- **Derive from real files only, and name them.** Every diagram's caption must cite the concrete
+  file(s)/dir(s) it was drawn from (e.g. "sources: `.gitlab-ci.yml`, `lib/scrub/`"). A diagram with
+  no citable source is not written.
+- **Never invent a component, job, or hop.** If a category does not apply (no CI config, no
+  privacy-relevant data path, no deployment manifest), omit that diagram rather than fabricate one
+  to hit the 2-4 count. 2 real diagrams beat 4 where two are invented.
+- **Conservative mermaid syntax** -- `flowchart TD` or `graph LR` only (no advanced/experimental
+  mermaid features), for the widest renderer compatibility (local preview, GitLab, and the
+  Confluence path below).
+- This is additive content within the existing `ARCHITECTURE.md` file -- it does not add a new
+  self-doc, so it does not touch `schema_version` or the scanner's `SELF_DOC_SET`.
+
+**Confluence rendering: PLANNED, not live.** Mermaid can render in Confluence via a Forge ADF
+extension (a converter emits the ADF node from the mermaid source; this needs a round-trip
+render test before anyone relies on it). No such converter script exists yet under `scripts/` in
+this repo -- until one lands and is referenced here by name, treat Confluence rendering of these
+diagrams as **PLANNED**, not verified. In the interim the diagrams render wherever the committed
+markdown is viewed directly (GitLab file view, local preview, editors with mermaid support).
+
+### Committed-by-design (the DEFAULT) + declared-signal opt-out
+
+> Policy per OD-008 (PROVISIONAL owner-ruling 2026-07-10, option C -- pending Oscar's
+> confirmation at merge; see `docs/governance/open-decisions.md` OD-008). Not live until the
+> ruling MR is merged.
+
+These docs are **COMMITTED (not gitignored) by design** -- they are the shareable artefact
+(unlike the gitignored `.ai-assistance/local/` context that `ai-discovery` writes) and the
+substrate the EP Projects Register / coordination hub aggregates. Consumer maintainers:
+committing generated output is intentional here, because the docs are only discoverable
+across the fleet if they are IN git. ep-ai-standards tracks its own `docs/self-docs/` for the
+same reason.
+
+**Committed is the DEFAULT.** A maintainer who prefers gitignored + regenerate-on-demand may
+do so, but ONLY **explicitly, via a declared signal** -- never silently. Silent divergence is
+the one thing the policy forbids, because the hub then cannot tell whether to expect committed
+docs or a regen step. To opt out of committing:
+
+1. Record a declared marker in the repo's self-docs `STATUS.md` frontmatter:
+   `self_docs_mode: gitignored-regenerate` (default when absent is `committed`), AND
+2. Document the regen path (how/when the set is regenerated for the Register -- e.g. a CI
+   publish step), AND
+3. Gitignore `docs/self-docs/` in that repo.
+
+With the marker present, the divergence is DECLARED and discoverable; without it, committed is
+assumed and a gitignored set is treated as drift.
+
+---
+
+## 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. For `ARCHITECTURE.md`, also fill
+   or refresh the `## Diagrams` section per "ARCHITECTURE.md diagrams (mermaid)" above -- only
+   when the underlying real files (CI config, scrub modules, deployment manifests) changed enough
+   to make an existing diagram stale.
+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. **Leave a consumer-repo breadcrumb (OD-007).** When this run generated or committed any
+   self-doc into the repo, write a minimal in-repo trail so a developer (or a second agent) on
+   the same tree can tell where the change came from. Add ONE line to the repo's
+   `docs/worklog.md` (create it if absent) AND, if generating the set for the first time, a
+   short note in the self-docs `STATUS.md`. Format:
+   ```
+   generated by project-self-docs v<skill-version> per migration <NNNN-or-none>, review_status: draft, run <YYYY-MM-DD>
+   ```
+   This is the consumer-side analogue of the ecoportal working-tree watermark. A pure no-op
+   re-run (nothing changed) writes no breadcrumb -- keep it idempotent. See
+   `docs/governance/open-decisions.md` OD-007 (PROVISIONAL ruling 2026-07-10, pending merge).
+7. **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 under the self-docs directory (default `docs/self-docs/`), the KPI
+  usage line, and -- per OD-007 -- a single breadcrumb line in the repo's `docs/worklog.md` (the
+  one deliberate write outside the self-docs dir, and only when a doc was generated/committed on
+  this run). 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), EXCEPT the single
+  OD-007 breadcrumb line in the repo's `docs/worklog.md` and the KPI usage line.
+- 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.

data/.ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""
+self_docs_scan.py -- Project self-docs OBSERVE stage (deterministic, zero-LLM core).
+
+Skill (semantic refresh + Act): skills-library/project-self-docs/SKILL.md.
+
+Runs FROM A TARGET REPO (the repo documenting itself), not from ep-ai-standards. It does the
+DETERMINISTIC half of self-documentation so no interactive Claude tokens are spent on facts the
+filesystem already knows:
+  - detect the repo type using the same signals as skills-library/discovery-manifest.yaml
+  - collect a structural fingerprint (top-level dirs, key config files, git head/branch/remote,
+    commit-activity clusters, existing .ai-assistance/code specs, CI files, doc files)
+  - compute a stable content hash per self-doc so refreshes are idempotent and the changelog
+    only records REAL changes
+  - emit a structured JSON "observation" the skill consumes to fill the self-doc set
+
+It does NOT write project prose, summarise purpose, or judge architecture -- that semantic work is
+the LLM skill's job (batched to Gemini per the token-frugality rule), gated by human review before
+any egress. This scanner is the thermometer; the skill is the (human-gated) actuator.
+
+HARD CONSTRAINTS:
+  - READ-ONLY by default. It never writes into the target repo except the self-doc index/changelog
+    under --write, and even then only to the self-docs directory (default docs/self-docs/).
+  - NO absolute paths are emitted into any committed artefact: paths are repo-relative.
+  - NO Confluence / network egress. Publish target is UNDECIDED (see SKILL.md); this script only
+    ever touches the local filesystem.
+
+Usage:
+  python self_docs_scan.py                       # human summary of the observation (target = cwd)
+  python self_docs_scan.py --json                # structured observation to stdout
+  python self_docs_scan.py --target <path>       # observe a different LOCAL repo root (convenience
+                                                 # only -- NEVER to generate another repo's self-docs
+                                                 # from here; run the skill in that repo's own session)
+  python self_docs_scan.py --out docs/self-docs  # self-docs dir (default docs/self-docs)
+  python self_docs_scan.py --write               # (re)write the machine index + changelog only
+"""
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+SCHEMA_VERSION = "1.1"
+
+# Self-doc set: stable filenames the skill fills in. Keeping this list here (not only in the
+# template) lets the deterministic scanner report which docs already exist and which are missing,
+# and lets the index/changelog be generated without the LLM.
+SELF_DOC_SET = [
+    ("OVERVIEW.md", "What the project is, who it serves, current priority, discovery & access"),
+    ("ARCHITECTURE.md", "Top-level structure, key components, how they fit"),
+    ("CONVENTIONS.md", "Coding style, branch naming, commit style, test conventions"),
+    ("INTEGRATIONS.md", "External services + data + permissions, upstream/downstream repos"),
+    ("STATUS.md", "Active work, migration state, known risks, open questions"),
+    ("COMPLIANCE.md", "ISO-27001/audit, data classes + PII, vendors, AI content, leak controls"),
+    ("OPERATIONS.md", "Infrastructure, public exposure + Cloudflare, DevOps audit, usage KPIs"),
+]
+
+# Detection signals mirror skills-library/discovery-manifest.yaml. Order matters: first match wins.
+# (file, ...) => all must exist; file_any => any of the globs; not_file => must be absent.
+REPO_TYPE_RULES = [
+    ("aws-cdk", {"file": ["cdk.json"]}),
+    ("browser-extension", {"file": ["manifest.json"], "file_any": ["package.json", "Gruntfile.js", "webpack.config.js"]}),
+    ("ruby-gem", {"file_any": ["*.gemspec"]}),
+    ("rails-app", {"file": ["config/application.rb"]}),
+    ("ruby-scripts", {"file": ["Gemfile"], "not_file": ["*.gemspec", "config/application.rb"]}),
+    ("typescript-lib", {"file": ["package.json"], "not_file": ["cdk.json", "manifest.json"]}),
+]
+
+KEY_CONFIG_FILES = [
+    "package.json", "Gemfile", "cdk.json", "manifest.json", "go.mod", "Cargo.toml",
+    "pyproject.toml", "requirements.txt", "tsconfig.json", ".eslintrc", ".eslintrc.json",
+    ".eslintrc.js", ".prettierrc", ".rubocop.yml", ".editorconfig",
+]
+CI_FILES = [".gitlab-ci.yml", "Jenkinsfile", "Makefile"]
+
+
+def _iso_now():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _exists(root, rel):
+    return os.path.exists(os.path.join(root, rel))
+
+
+def _glob_any(root, patterns):
+    import fnmatch
+    try:
+        top = os.listdir(root)
+    except OSError:
+        return False
+    for pat in patterns:
+        if any(fnmatch.fnmatch(name, pat) for name in top):
+            return True
+    return False
+
+
+def detect_repo_type(root):
+    for type_name, rule in REPO_TYPE_RULES:
+        ok = True
+        for f in rule.get("file", []):
+            if not _exists(root, f):
+                ok = False
+                break
+        if ok and rule.get("file_any"):
+            ok = _glob_any(root, rule["file_any"])
+        if ok and rule.get("not_file"):
+            for f in rule["not_file"]:
+                if "*" in f:
+                    if _glob_any(root, [f]):
+                        ok = False
+                        break
+                elif _exists(root, f):
+                    ok = False
+                    break
+        if ok:
+            return type_name
+    return "unknown"
+
+
+def _git(root, args):
+    try:
+        out = subprocess.run(
+            ["git", "-C", root] + args,
+            capture_output=True, text=True, timeout=15,
+        )
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def git_facts(root):
+    branch = _git(root, ["rev-parse", "--abbrev-ref", "HEAD"])
+    head = _git(root, ["rev-parse", "--short", "HEAD"])
+    remote = _git(root, ["config", "--get", "remote.origin.url"])
+    # Real repo name from the remote, never a local folder name that may be renamed.
+    repo_name = ""
+    if remote and "/" in remote:
+        repo_name = re.sub(r"\.git$", "", remote.rstrip("/").split("/")[-1])
+    # Activity clusters: which top-level dirs churn most in the last 50 commits.
+    log = _git(root, ["log", "-50", "--name-only", "--pretty=format:"])
+    clusters = {}
+    for line in log.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        top = line.split("/")[0] if "/" in line else line
+        clusters[top] = clusters.get(top, 0) + 1
+    top_clusters = sorted(clusters.items(), key=lambda kv: kv[1], reverse=True)[:6]
+    return {
+        "branch": branch,
+        "head": head,
+        "repo_name": repo_name,
+        "has_remote": bool(remote),
+        "activity_clusters": [{"path": k, "touches": v} for k, v in top_clusters],
+    }
+
+
+def structure(root):
+    dirs, files = [], []
+    try:
+        for name in sorted(os.listdir(root)):
+            if name.startswith(".git"):
+                continue
+            full = os.path.join(root, name)
+            if os.path.isdir(full):
+                dirs.append(name)
+            else:
+                files.append(name)
+    except OSError:
+        pass
+    return {
+        "top_level_dirs": dirs,
+        "key_config_files": [f for f in KEY_CONFIG_FILES if _exists(root, f)],
+        "ci_files": [f for f in CI_FILES if _exists(root, f)],
+        "has_readme": _exists(root, "README.md") or _exists(root, "README"),
+        "has_changelog": _exists(root, "CHANGELOG.md"),
+    }
+
+
+def existing_context(root):
+    """Reusable inputs that already exist -- the skill composes from these, not from scratch."""
+    ctx = {"code_specs": [], "repo_context": None, "conventions": None}
+    code_dir = os.path.join(root, ".ai-assistance", "code")
+    if os.path.isdir(code_dir):
+        for dirpath, _, filenames in os.walk(code_dir):
+            for fn in filenames:
+                if fn.endswith(".md"):
+                    rel = os.path.relpath(os.path.join(dirpath, fn), root).replace("\\", "/")
+                    ctx["code_specs"].append(rel)
+    ctx["code_specs"].sort()
+    local = os.path.join(root, ".ai-assistance", "local")
+    if os.path.isfile(os.path.join(local, "repo-context.md")):
+        ctx["repo_context"] = ".ai-assistance/local/repo-context.md"
+    if os.path.isfile(os.path.join(local, "conventions.md")):
+        ctx["conventions"] = ".ai-assistance/local/conventions.md"
+    return ctx
+
+
+def _content_hash(path):
+    """Hash the self-doc BODY (below the frontmatter) so index/changelog record real changes,
+    not just a re-run timestamp. Missing file -> None."""
+    if not os.path.isfile(path):
+        return None
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        text = fh.read()
+    body = text
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            body = text[end + 4:]
+    # Normalise line endings + trailing whitespace so cross-platform re-runs are stable.
+    norm = "\n".join(line.rstrip() for line in body.replace("\r\n", "\n").split("\n")).strip()
+    return hashlib.sha256(norm.encode("utf-8")).hexdigest()[:16]
+
+
+def self_doc_status(root, out_rel):
+    out_dir = os.path.join(root, out_rel)
+    docs = []
+    for fname, purpose in SELF_DOC_SET:
+        path = os.path.join(out_dir, fname)
+        docs.append({
+            "file": f"{out_rel}/{fname}".replace("\\", "/"),
+            "purpose": purpose,
+            "exists": os.path.isfile(path),
+            "content_hash": _content_hash(path),
+        })
+    return docs
+
+
+def observe(root, out_rel):
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "observed_at": _iso_now(),
+        "repo_type": detect_repo_type(root),
+        "git": git_facts(root),
+        "structure": structure(root),
+        "existing_context": existing_context(root),
+        "self_doc_set": self_doc_status(root, out_rel),
+        "out_dir": out_rel.replace("\\", "/"),
+    }
+
+
+# == index + changelog (deterministic writers) ======================================
+
+def _read_json(path, default):
+    if not os.path.isfile(path):
+        return default
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return default
+
+
+def write_index_and_changelog(root, out_rel, obs):
+    """Rewrite the machine-readable index and append changelog deltas -- deterministically.
+
+    The index (self-docs-index.json) is the machine surface a central hub consumes: schema
+    version, repo identity, and a hash per doc. The changelog (CHANGES.jsonl) appends one line
+    per doc whose content hash CHANGED since the previous index -- so the hub sees real deltas,
+    and a no-op re-run appends nothing (idempotent)."""
+    out_dir = os.path.join(root, out_rel)
+    os.makedirs(out_dir, exist_ok=True)
+    index_path = os.path.join(out_dir, "self-docs-index.json")
+    changes_path = os.path.join(out_dir, "CHANGES.jsonl")
+
+    prev = _read_json(index_path, {})
+    prev_hashes = {d["file"]: d.get("content_hash") for d in prev.get("docs", [])}
+
+    docs = obs["self_doc_set"]
+    now = obs["observed_at"]
+    deltas = []
+    for d in docs:
+        new_h = d["content_hash"]
+        old_h = prev_hashes.get(d["file"])
+        if new_h != old_h:
+            deltas.append({
+                "ts": now,
+                "file": d["file"],
+                "change": ("created" if old_h is None and new_h is not None
+                           else "removed" if new_h is None
+                           else "updated"),
+                "from_hash": old_h,
+                "to_hash": new_h,
+            })
+
+    index = {
+        "schema_version": SCHEMA_VERSION,
+        "generated_at": now,
+        "repo_name": obs["git"].get("repo_name") or "",
+        "repo_type": obs["repo_type"],
+        "head": obs["git"].get("head", ""),
+        "docs": [
+            {"file": d["file"], "purpose": d["purpose"],
+             "exists": d["exists"], "content_hash": d["content_hash"]}
+            for d in docs
+        ],
+    }
+    with open(index_path, "w", encoding="utf-8") as fh:
+        json.dump(index, fh, indent=2)
+        fh.write("\n")
+
+    if deltas:
+        with open(changes_path, "a", encoding="utf-8") as fh:
+            for delta in deltas:
+                fh.write(json.dumps(delta) + "\n")
+
+    return {"index": f"{out_rel}/self-docs-index.json".replace("\\", "/"),
+            "changelog": f"{out_rel}/CHANGES.jsonl".replace("\\", "/"),
+            "deltas_appended": len(deltas)}
+
+
+def _human(obs):
+    g = obs["git"]
+    print(f"self-docs observation  (schema {obs['schema_version']})")
+    print(f"  repo_type : {obs['repo_type']}")
+    print(f"  repo_name : {g.get('repo_name') or '(no remote)'}  @ {g.get('head') or '?'} "
+          f"on {g.get('branch') or '?'}")
+    print(f"  out_dir   : {obs['out_dir']}")
+    print("  top-level dirs:", ", ".join(obs["structure"]["top_level_dirs"]) or "(none)")
+    if obs["structure"]["key_config_files"]:
+        print("  config    :", ", ".join(obs["structure"]["key_config_files"]))
+    if g.get("activity_clusters"):
+        hot = ", ".join(f"{c['path']}({c['touches']})" for c in g["activity_clusters"])
+        print("  hot paths :", hot)
+    ec = obs["existing_context"]
+    reuse = []
+    if ec["repo_context"]:
+        reuse.append("ai-discovery repo-context.md")
+    if ec["conventions"]:
+        reuse.append("ai-discovery conventions.md")
+    if ec["code_specs"]:
+        reuse.append(f"{len(ec['code_specs'])} code-specs")
+    print("  reuse from:", ", ".join(reuse) or "(none -- run ai-discovery/code-specs first)")
+    print("  self-doc set:")
+    for d in obs["self_doc_set"]:
+        state = "present" if d["exists"] else "MISSING"
+        print(f"    [{state:7}] {d['file']}  ({d['content_hash'] or '-'})")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Deterministic project self-docs observation")
+    ap.add_argument("--target", default=".",
+                    help="LOCAL repo root to observe (default: cwd). Convenience only -- do NOT use to "
+                         "generate ANOTHER repo's self-docs from here; run the skill in that repo's own "
+                         "session (self-docs are owned + generated by the repo that documents itself).")
+    ap.add_argument("--out", default="docs/self-docs", help="self-docs dir (default: docs/self-docs)")
+    ap.add_argument("--json", action="store_true", help="emit the structured observation")
+    ap.add_argument("--write", action="store_true",
+                    help="(re)write the machine index + changelog deltas only")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.target)
+    if not os.path.isdir(root):
+        print(f"[self-docs] target not a directory: {root}", file=sys.stderr)
+        return 2
+
+    obs = observe(root, args.out)
+
+    if args.write:
+        result = write_index_and_changelog(root, args.out, obs)
+        obs["_write_result"] = result
+
+    if args.json:
+        print(json.dumps(obs, indent=2))
+    else:
+        _human(obs)
+        if args.write:
+            r = obs["_write_result"]
+            print(f"  wrote index -> {r['index']}; changelog deltas appended: {r['deltas_appended']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,12 @@
+{
+  "ep-ai-standards-version": "1.14.0",
+  "applied-at": "2026-07-30",
+  "project-type": [
+    "ruby"
+  ],
+  "deferred": [],
+  "installed-components": {
+    "skills/ep-ai-manager": "2.5.0",
+    "skills/project-self-docs": "0.4.0"
+  }
+}

data/.ai-assistance/version.json

@@ -0,0 +1,8 @@
+{
+  "schema": "1.0",
+  "note": "Tracks which features are installed in THIS .ai-assistance/ directory. Updated by install.sh on each deployment. Do NOT confuse with standards-version.json (ep-ai-standards compliance) -- this is .ai-assistance/ infrastructure versioning.",
+  "installed_at": "2026-07-14",
+  "installed_from": "ep-ai-standards",
+  "features": {},
+  "deploy_posture": "committed"
+}

data/.claude/.gitignore

@@ -0,0 +1,2 @@
+# Per-developer Claude Code local override -- never commit (machine-specific).
+settings.local.json