Add CI gate for generated memory-kit drift

.agent/project.yaml

@@ -0,0 +1,41 @@
+project:
+  name: agent-memory-kit
+  description: a vendored, markdown-first project memory kit for coding agents
+architecture:
+  file: docs/planning/vision.md
+conventions:
+  - Keep agent-memory-kit repo-local and markdown-first; do not add daemons, databases, dashboards, MCP servers, or telemetry.
+  - Generated files must remain reproducible from generate.py, adapters, templates, and .agent/project.yaml.
+agents:
+  claude_code:
+    enabled: false
+  codex:
+    enabled: true
+  hermes:
+    enabled: true
+  openclaw:
+    enabled: false
+  cursor:
+    enabled: false
+  windsurf:
+    enabled: false
+  gemini_cli:
+    enabled: false
+  antigravity:
+    enabled: false
+memory:
+  semantic_max_lines: 500
+  working_max_lines: 300
+  capture_at:
+    - response
+    - merge
+  files:
+    semantic: memory/semantic.md
+    working: memory/working.md
+    decisions: DECISIONS.md
+    candidates: memory/candidates.md
+    candidates_rejected: memory/candidates.rejected.md
+  approval_mode:
+    default: auto
+    review: []
+  task_directory: dev/[task]/

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    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.12"
+
+      - name: Install test dependencies
+        run: python3 -m pip install pytest pyyaml
+
+      - name: Run tests
+        run: python3 -m pytest -q
+
+      - name: Check generated files
+        run: python3 generate.py all . --check

.gitignore

@@ -7,3 +7,4 @@ __pycache__/
 .agent/.generated_state.json
 .agent/eval/
 docs/planning/
+memory/working.md

AGENTS.md

@@ -0,0 +1,85 @@
+# Project Context — agent-memory-kit
+
+**agent-memory-kit** is a vendored, markdown-first project memory kit for coding agents
+
+<!-- amk:start -->
+<!-- GENERATED by agent-memory-kit. DO NOT EDIT MANAGED BLOCK DIRECTLY. -->
+## Memory System
+
+This project uses a file-based memory system to maintain context across sessions.
+
+### On Session Start
+
+Read `memory/semantic.md` ONCE to load project context before answering.
+
+### On Every Turn
+
+The preprompt hook handles reading `memory/working.md`.
+
+### Task Files
+
+Only load `/dev/[task]/*` files when actively working on that task.
+
+### MCP Efficiency
+
+Before calling any MCP tool to retrieve information, first check if that information might exist in `memory/semantic.md` or `dev/[task]/context.md` — local files are cheaper than remote MCP queries.
+
+### Keep Context Minimal
+
+Do not speculatively load files "just in case".
+
+### Mid-Session Drift
+
+If reasoning becomes uncertain or inconsistent with prior context, re-read `memory/semantic.md` before continuing.
+
+### Memory Discipline
+
+- `memory/semantic.md` — current build state; update directly after changes; summarize what you changed
+- `memory/working.md` — live task state; update freely after each response; no approval needed
+- `DECISIONS.md` — append-only log of architectural decisions; update directly after changes; summarize new entries
+- `dev/[task]/context.md` — log confirmed assumptions immediately; no approval needed
+- `memory/candidates.md` — staged lessons awaiting promotion; append-only, one heading per claim; append candidate claims with source pointers; never edit existing entries
+- `docs/planning/vision.md` — principles, load-bearing assumptions, planned capabilities; update only on merge when a capability ships or an assumption is invalidated; **never put current state here** (that's `semantic.md`), **never put planning details here** (tickets, checklists, phases)
+- `memory/candidates.rejected.md` — promoted-by-move from candidates.md; each entry includes a Why rejected: reason; move entries from candidates.md with Why rejected: appended
+
+**DECISIONS.md vs. Assumptions distinction:**
+- `DECISIONS.md` = immutable log — "we chose X on date Y because Z" — never edited, only superseded by appending
+- `docs/planning/vision.md` Assumptions = live load-bearing premises — mutable; when invalidated, append a supersession to `DECISIONS.md` first, then update the assumption
+
+**On PR merge:** check `docs/planning/vision.md` — move shipped capabilities to `memory/semantic.md` and remove them from the Vision section; append a supersession to `DECISIONS.md` then update or remove any invalidated Assumption.
+
+**Stage → Graduate promotion (#11):**
+- `memory/candidates.md` — append-only staging queue. Each entry is a `###` heading claim with a `- Staged: YYYY-MM-DD` date and a `- Sources:` bullet list (commit hashes, session refs, or file:line pointers). Before appending, grep candidates.md for matching claims — if found, append a source bullet to the existing heading instead of creating a duplicate. One heading per claim.
+- `memory/semantic.md` — on promotion, move the entire heading block from candidates.md into semantic.md with a one-line `**Why accepted:**` rationale appended. The candidate entry disappears from candidates.md.
+- `memory/candidates.rejected.md` — on rejection, move the heading block here with a one-line `**Why rejected:**` reason. Preserves the churn history to prevent re-litigation.
+- All promotions and rejections are committed separately with `promote:` or `reject:` commit message prefixes. The diff *is* the audit trail.
+
+---
+
+## Architecture
+
+Before implementing a feature, read `docs/planning/vision.md`. It is the canonical record of architectural principles, load-bearing assumptions, and planned capabilities — not current build state (that lives in `memory/semantic.md`).
+
+
+---
+
+## Key conventions
+
+- Keep agent-memory-kit repo-local and markdown-first; do not add daemons, databases, dashboards, MCP servers, or telemetry.
+- Generated files must remain reproducible from generate.py, adapters, templates, and .agent/project.yaml.
+
+---
+
+## Optional: Hermes Memory Mirroring
+
+Hermes has its own `MEMORY.md` / `USER.md` persistence layer. These are complementary,
+not replacements, for this project's `memory/` files. If you want high-signal lessons
+visible inside Hermes's built-in persistence, you can symlink:
+
+```bash
+ln -s memory/semantic.md MEMORY.md
+```
+
+The project's `memory/semantic.md` remains the single source of truth.
+<!-- amk:end -->
+

DECISIONS.md

@@ -0,0 +1,13 @@
+# Decisions — agent-memory-kit
+
+## 2026-05-12 — CI Gate For Generated-File Drift
+
+**Decision:** Add CI that runs the test suite and `python3 generate.py all . --check` against the kit repo's own generated `AGENTS.md`.
+
+**Reasoning:** The applycling audit found a real failure mode: generated entrypoints can be manually corrected while the generator source remains stale. A prose closeout rule helps, but CI is the enforcement mechanism that prevents stale generated output from merging unnoticed.
+
+**Trade-offs:** The kit repo now carries a minimal `.agent/project.yaml`, `AGENTS.md`, and tracked memory files for itself. That is a small amount of self-dogfood state, but it gives CI a real generated artifact to compare against without introducing any daemon, database, or non-markdown state.
+
+**When to revisit:** If the generated surface grows too large for the kit repo itself, move the self-check target to a tracked fixture project and run `generate.py all <fixture> --check` instead.
+
+**Affects:** `.github/workflows/ci.yml`, `.agent/project.yaml`, `AGENTS.md`, `memory/semantic.md`, `DECISIONS.md`

README.md

@@ -142,6 +142,20 @@ python .agent/memory-kit/generate.py all
 
 For 1–5 repos, copy-paste is faster than any automation.
 
+## CI
+
+This repository runs a small CI gate on pull requests and pushes to `main`:
+
+```bash
+python3 -m pytest -q
+python3 generate.py all . --check
+```
+
+The second command checks that the kit repo's generated `AGENTS.md` is still
+reproducible from `generate.py`, `adapters/`, `templates/`, and
+`.agent/project.yaml`. If generated output drifts, update the source config or
+template first, then regenerate.
+
 ---
 
 ## What we explicitly don't build

memory/candidates.md

@@ -0,0 +1,17 @@
+# Candidate Lessons
+
+Claims that have recurred across sessions but have not yet been promoted to
+semantic.md with a `**Why accepted:**` rationale.
+
+Format:
+
+```md
+### claim heading
+- Staged: YYYY-MM-DD
+- Sources:
+  - <commit-hash>, <file:line>, or <session-ref>
+```
+
+Before appending a new claim, search this file for a near-duplicate heading.
+On promotion, move the full heading block to `memory/semantic.md`.
+On rejection, move the full heading block to `memory/candidates.rejected.md`.

memory/candidates.rejected.md

@@ -0,0 +1,4 @@
+# Rejected Candidates
+
+Claims that were staged in `memory/candidates.md` but rejected with a
+`**Why rejected:**` rationale. Preserve entries here to prevent re-litigation.

memory/semantic.md

@@ -0,0 +1,24 @@
+# Semantic Memory — agent-memory-kit
+
+## Core Systems
+
+- **Purpose:** agent-memory-kit is a vendored, markdown-first project memory kit for coding agents. It stores durable project context in repo-local markdown under git, with no daemon, database, MCP server, dashboard, or telemetry.
+- **Generator:** `generate.py` reads `.agent/project.yaml` and renders agent entrypoints/configs through adapters in `adapters/`. It supports `init`, per-agent generation, `all`, `all --force`, and `all --check`.
+- **Adapters:** Claude Code, Codex, Hermes, Cursor, Gemini CLI, Windsurf, OpenClaw, and Antigravity share the same memory files. Adapters expose `generate()`, `check()`, and `referenced_memory_files()`.
+- **Managed sections:** Generated markdown entrypoints use `<!-- amk:start -->` / `<!-- amk:end -->` sentinels. Regeneration replaces only the managed block and preserves user content outside it.
+- **Approval mode:** `memory.approval_mode` in `.agent/project.yaml` controls whether semantic/decision memory is direct-write (`auto`) or propose-first (`review`). `memory/working.md`, `dev/[task]/context.md`, and candidate files are always auto.
+- **Stage/graduate memory:** `memory/candidates.md` stages recurring lessons; promotion to `memory/semantic.md` requires a `**Why accepted:**` rationale. Rejections move to `memory/candidates.rejected.md` with `**Why rejected:**`.
+- **Self-check target:** The kit repo has its own `.agent/project.yaml` and generated `AGENTS.md` so CI can run `python3 generate.py all . --check` against real checked-in generated output.
+
+## Key Patterns
+
+- Keep the kit vendored and repo-local; do not introduce global installs or load-bearing state outside markdown.
+- Prefer deterministic generated output plus `--check` drift detection over runtime services.
+- Generated files must be reproducible from `generate.py`, `adapters/`, `templates/`, and `.agent/project.yaml`.
+- If a generated file is manually corrected, update the source config/template/adapter so regeneration preserves the correction.
+
+## Active Areas
+
+- Add CI enforcement so generated-file drift blocks PR merge.
+- Add a merge-closeout consistency protocol so memory, docs, generated files, hooks, and manuals are reconciled after merges.
+- Later: add `generate.py doctor` as advisory automation for broader closeout checks.