feat: make Epi Log ambient and traceable

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Validate skill and README
+        run: python scripts/check-docs.py
+      - name: Check whitespace
+        run: git diff --check

README.md

@@ -14,15 +14,26 @@
 
 </div>
 
-**Evidence-first visibility for engineering work.**
+**Evidence-first engineering execution and traceability.**
 
-Epi Log is one portable Markdown skill for a daily and trailing-seven-day review of PRs, reviews, tickets, design decisions, meetings, and explicit follow-ups. It helps make outcomes, quality, collaboration, risk reduction, decisions, and follow-through easy to see. It works with whatever read access a harness already has; it does not require a runtime, database, vendor API, or scoring service.
+Epi Log is a tiny [Agent Skills](https://agentskills.io)-format core that helps an agent leave useful visibility behind while doing ordinary engineering work. It makes intent, decisions, changes, evidence, outcomes, assumptions, blockers, and follow-up easier to find in the work’s existing artifacts.
 
-Some activity metrics are useful signals but can misrepresent some work when viewed alone. Epi Log adds context and evidence rather than reducing engineering to a scorecard: it reports what can be proved, marks missing evidence as `unknown`, and suggests at most three concrete next actions.
+It is designed to be ambient after installation: no separate daily command, diary, database, connector, or reporting ritual is required. Some activity metrics are useful signals but can misrepresent some work when viewed alone; Epi Log adds context and evidence rather than reducing engineering to a scorecard.
+
+## What it does
+
+- Drives toward the real outcome and the highest-leverage next step.
+- Keeps `intent → decision → change → evidence → outcome` traceable in tickets, PRs, docs, reviews, tests, and handoffs.
+- Makes meaningful research, debugging, review, design, coordination, decisions, and blocked work visible when they produce a conclusion, risk reduction, unblock, or reusable artifact.
+- Checks one level above for material work: validation, maintainability, reliability, security, rollout, rollback, monitoring, and reuse.
+- Repairs genuine visibility gaps at the point of work when authorized, or supplies the smallest precise draft when it cannot act.
+- Verifies before handoff and states facts, assumptions, uncertainty, blockers, and follow-up.
+
+It does not create ceremony for trivial changes, duplicate a diary, invent evidence, or optimize for PR count, lines, hours, streaks, rankings, or other shallow proxies.
 
 ## Compatibility
 
-The skill uses the portable [Agent Skills](https://agentskills.io) format. It works with any harness that discovers `SKILL.md`; these are common locations:
+The core is plain Markdown with lightweight YAML front matter. It works with any harness that discovers `SKILL.md`; these are common locations:
 
 | Harness | Skill location |
 |---|---|
@@ -32,69 +43,38 @@ The skill uses the portable [Agent Skills](https://agentskills.io) format. It wo
 | **OpenCode** | `~/.config/opencode/skills/epi-log/SKILL.md` or the project skill directory |
 | **Other harnesses** | Their configured `skills/epi-log/SKILL.md`, or attach the file as instructions |
 
-## Install anywhere
-
-1. Copy [`SKILL.md`](./SKILL.md) into the harness's skill directory as `epi-log/SKILL.md`.
-2. Enable or invoke the skill using the harness's normal mechanism.
-3. If the harness has no skill system, tell the agent: `Read /path/to/epi-log/SKILL.md and follow it.`
-
-Examples of common project/user locations (use the equivalent supported by your harness):
-
-- Pi: `~/.pi/agent/skills/epi-log/SKILL.md`
-- Claude Code: `~/.claude/skills/epi-log/SKILL.md` or `.claude/skills/epi-log/SKILL.md`
-- Codex: `~/.codex/skills/epi-log/SKILL.md` or `.codex/skills/epi-log/SKILL.md`
-- OpenCode/other harnesses: their configured `skills/epi-log/SKILL.md`, or attach the file as instructions.
-
-The skill is intentionally plain Markdown with optional YAML front matter. No harness-specific command, SDK, or script is required.
-
-## Use it
-
-Ask the agent:
-
-```text
-Run Epi Log for today.
-```
-
-or:
+Skill activation is harness-dependent. For the strongest always-on behavior, load `SKILL.md` from the harness’s baseline/project instructions when that mechanism exists; a skill directory alone may mean “available when relevant,” not literally active on every turn.
 
-```text
-Run Epi Log for the trailing 7 days. Use the configured team expectations and save the report.
-```
+## Install
 
-If persistence is useful, configure a writable log directory. The default convention is:
+Copy [`SKILL.md`](./SKILL.md) into the target harness’s skill directory as `epi-log/SKILL.md`, then enable it using that harness’s normal mechanism. If the harness has no skill system, tell the agent:
 
 ```text
-.epi-log/
-  daily/YYYY-MM-DD.md
-  weekly/YYYY-Www.md
+Read /path/to/epi-log/SKILL.md and follow it as an ambient engineering quality and traceability layer.
 ```
 
-An optional `.epi-log/config.md` can state only facts the user/team chooses to provide:
+There is no runtime, SDK, vendor API, database, or mandatory connector list.
 
-```yaml
-timezone: America/Los_Angeles
-sources: [github, jira, slack, gmail, gdrive, meetings]
-ticket_system: Jira
-adr_convention: docs/adr/ with the organization's template
-review_expectation: "team-owned; do not invent a quota"
-```
-
-## What it makes visible
+## Optional audit mode
 
-- PRs are coherent and reviewable, without a fake line-count optimum.
-- Merges have observable non-bot human approval before merge and after the relevant revision.
-- PRs connect changes to a real outcome and validation, or clearly show the missing evidence.
-- The user's weekly reviews and discussions are substantive, without optimizing for comment volume.
-- Code, meetings, and commitments map back to epics/tasks in the user's ticket system.
-- Material design and architecture decisions have the organization's accepted record.
-- Blockers, stale work, contradictions, and forgotten follow-ups have an owner and next action when known.
+The core is the normal operating loop. For an explicit retrospective or visibility report, read [`references/audit-mode.md`](references/audit-mode.md) and ask for a daily or trailing-seven-day audit. This mode retains the detailed PR, review, ticket, decision, evidence-gap, and report guidance without making it part of every task.
 
 ## Constructive guardrails
 
-- Read-only by default; ask before merging, approving, commenting, messaging, editing tickets/docs, or creating reminders.
-- Use bounded, authorized source searches and least privilege.
-- Redact secrets, customer data, and unnecessary personal details.
-- Missing access is `unknown`, never evidence of inactivity or poor performance.
-- Keep visibility focused on outcomes, context, and collaboration—not hours, streaks, commit/line counts, rankings, leaderboards, or behavioral judgments about coworkers.
+- Use only authorized sources and existing team conventions.
+- Read and write within the user’s permissions; do not merge, approve, comment, message, publish, or edit external artifacts without authorization.
+- Separate observed facts, inferences, and `unknown`; missing access is never evidence of “no work.”
+- Never claim completion, value, or human review without support.
+- Never pad diffs, fragment work artificially, spam comments, fake or rubber-stamp reviews, or manufacture activity.
+- Keep visibility focused on outcomes, context, and collaboration—not rankings or behavioral judgments about coworkers.
+
+## Files
 
-See [`SKILL.md`](./SKILL.md) for the complete, harness-neutral operating instructions and output format.
+```text
+epi-log/
+├── SKILL.md                    # tiny ambient core
+├── references/audit-mode.md    # optional explicit retrospective/report mode
+├── assets/                     # README banner
+├── README.md
+└── LICENSE
+```