# LCM-X Repository Instructions These instructions govern maintainers, contributor agents, and review bots working in `electricsheephq/lcm-x`. LCM-X is the independent Lossless Context Memory eXtension for Hermes. Upstream `stephenschoettler/hermes-lcm` is an evidence and attribution source, not an authority for writes or automatic merges. ## Non-Negotiable Invariants - Lossless means lossless. Do not delete, truncate, overwrite, or make durable user context unreachable during automatic maintenance, migration, reconciliation, compaction, cleanup, or recovery. - Prefer degraded coverage, a safe no-op, explicit warnings, or a tracked repair over destructive recovery when continuity is uncertain. - Preserve message identity, chronology, conversation/session ownership, summary provenance, source coverage, tool-call/result grouping, real user turns, and the active fresh tail. - Preserve contributor authorship, upstream links, license attribution, and original commits. - Never commit credentials, tokens, cookies, customer data, live Hermes configuration, or local authentication state. - Do not change customer runtimes, publish a release, write upstream, or announce LCM-X as canonical unless the user explicitly authorizes that separate gate. ## Canonical Work Graph - Use a GitHub issue for accepted bugs, features, design changes, and concrete follow-ups. - Keep one observable acceptance gate per issue and one issue per PR unless the issue explicitly approves a combined change. - Link upstream reports and PRs as evidence while retaining contributor credit. - Treat labels, CI, reviewer severity, and unmerged PR claims as evidence inputs—not proof by themselves. - Give every verified review finding one terminal disposition: fixed now, accepted follow-up linked to an issue, accepted tradeoff/won't-fix, false/not-applicable, or escalated. ## Bugs And Regressions - Reproduce a bug on the exact current `main` SHA or identify the mandatory invariant it violates before implementation. - Record the supported path, impact, failing proof, expected behavior, and affected SHA. - Add the smallest regression that fails on the base and passes on the candidate. - Do not implement a `needs-repro` report merely because an upstream PR or issue claims a fix. - Prioritize verified supported-path impact: - `P0`: active catastrophic data loss, disclosure, or unusable core path. - `P1`: severe integrity, security, crash, lockout, or release-blocking failure. - `P2`: significant bounded correctness or resource failure. - `P3`: limited bug, feature gap, or moderate maintainability/performance issue. - `P4`: documentation, tooling, portability, testing, or cosmetic work. ## Features And Design Changes - Require an accepted feature/design issue before its PR becomes ready for review or can merge. - The issue must state the problem, user/operator impact, proposed behavior, alternatives, acceptance criteria, non-goals, backward-compatible defaults, and documentation/config consequences. - Identify the Hermes host contract involved: plugin API, `ContextEngine` behavior, lifecycle, profile/session identity, tool schema, config, model routing, or no host-contract change. - Keep existing behavior as the default unless the accepted issue explicitly approves a breaking change and its migration path. - Treat best-practice work as `P3`/`P4` unless current evidence proves a violated invariant. - Do not add a dependency, schema, background service, persistence surface, or public contract when the existing path can satisfy the accepted behavior. ## Hermes Compatibility - Test against the repository's supported Python versions and the Hermes `ContextEngine` import/contract exercised by CI. - Keep profile and session state isolated; never infer one Hermes profile from another. - When changing configuration, update the runtime loader, user documentation, bundled `skills/hermes-lcm/references/configuration.md`, examples, and regression tests together. - When changing plugin tools or lifecycle behavior, update the bundled Hermes skill/reference material and test host-facing failure and fallback paths. - State any minimum Hermes capability explicitly. Do not silently depend on an unreleased or unverified Hermes host behavior. ## Validation Before publication, run the narrowest focused regression and the checks relevant to the changed surface. GitHub Actions is authoritative for the full supported matrix. Default repository checks: ```bash pytest tests/test_lcm_core.py tests/test_lcm_engine.py tests/test_packaging_install.py -q pytest -q bash -lc 'ulimit -n 1024 && python -m pytest tests/ -q' ruff check . python -m compileall -q . python -m py_compile scripts/import_lossless_claw.py bash -n scripts/install.sh git diff --check ``` Run `actionlint` when workflows change. Record exact commands and results in the PR. ## Results and PR evidence - A run that yields a citable number ends with a result card (`RESULT-MANIFEST.json` + `RESULT.md`), published to a durable store (a release asset or a private evidence store) before raw data is packed. - Never cite machine-local paths (home directories, mounted volumes or session-note folders) in this repo, PRs, issues or releases. - Every PR body has an `## Evidence` block sized to its class; screenshots are only required for visual changes. - Closeouts state a claim class and what the result does not prove. ## Automation Boundary - Treat AI and bot output as proposal and evidence by default. - Deterministic tooling must re-fetch the live issue, PR head, checks, reviews, threads, and authorization immediately before an authorized write. - Model output alone cannot close, label, assign, push, approve, or merge. - Automated repair is opt-in and limited to the exact accepted issue and current gate. - AI review is recorded evidence, not enforcement. The `land-pr` review obligation is a maintainer discipline, not a protected check: it does not authenticate review artifacts, and a maintainer who records a false pointer can pass it (#474, #369). Public disclosure still requires an explicit maintainer decision. Classification alone does not elevate routine reversible issue metadata. - Use `.agents/skills/triage-backlog/SKILL.md` read-only unless a maintainer explicitly authorizes one exact mutation; never use it for an automatic backlog sweep. - Invoking a skill never creates write authority. Routine reversible issue metadata needs one exact maintainer authorization and live read-back; public sensitive disclosure and terminal lifecycle actions retain the stronger owner and lifecycle gates in `triage-backlog`. - Preserve open executable upstream work as an active continuation. Do not silently turn it into an archive-only record, supersede it, or close it while its continuation state is ambiguous. ## Review And Merge - Use `.agents/skills/land-pr/SKILL.md` when deciding readiness or landing a PR. - Pin the PR base SHA and `headRefOid`; CI and review must cover that exact head or an explicitly bounded delta. - Enforcement is strict exact-head CI (`workflow-lint`, `lint`, `test (3.11)` through `test (3.14)`), required review-thread resolution, and merge commits only. Keep strict required-status enforcement enabled so a protected-base change blocks merging until CI passes on an up-to-date head. - Review obligation (`land-pr`): every PR needs at least one independent review of the exact head. When the `scripts/maintainer_gate.py` risk hint reports review-provenance-policy or LCM memory-preservation risk, it needs an acceptance review and a distinct adversarial review from a different model than the author. At landing, after merge authority is established, post a merge receipt comment that lists only pointers and names the author and reviewer models; if a lane is unavailable, record `REVIEW_SKIPPED: — ` and let the owner decide. - Every review thread is resolved before merge. A bot thread is resolved only after a reply that records its disposition: fixed in ``, false with evidence, accepted tradeoff, or follow-up ``. - Do not merge with failing/pending required checks, unresolved review threads, a changed head, missing issue acceptance, or unowned product/security decisions. - Never push directly to `main`, bypass the ruleset, use auto-merge, or force-push/delete `main`. The ruleset transitions for #218, #462, #466, #469, and #470 are closed history. The owner's `pull_request` bypass is for a recorded emergency only, noted on the PR. - Use merge commits for PRs so contributor and upstream commits remain intact. Do not squash or rebase-merge into `main`. - Merge deterministically with the pinned head: ```bash gh pr merge --merge --match-head-commit ``` - After merging, verify the merge commit, linked issue state, final `main` SHA, and required post-merge checks. Thank external contributors and preserve uncertain issue reports rather than closing them speculatively. ## Maintainer And Bot Roles - `@100yenadmin` is the code owner. CODEOWNERS does not satisfy review readiness by itself; protected exact-head CI and thread gates do, with the `land-pr` review obligation. - Bots and agents may triage, reproduce, implement, test, review, and prepare merge evidence. - Bots and agents may not bypass checks, review-thread resolution, the `land-pr` review obligation, issue acceptance, or a product/security owner decision. - Maintainers own feature acceptance, priority, compatibility decisions, terminal dispositions, and releases. ## Releases are rc-first (RELEASE-READINESS-V1) - Any release containing product code (outside `bench/`, docs, tests, and `.github/release-notes/`) MUST ship as a `vX.Y.Z-rcN` prerelease first and pass the live gauntlet in `bench/specs/RELEASE-READINESS-V1.md` — Phase A (all-tools matrix on a fresh isolated clone, both privacy postures, planted-secret battery), Phase B (multi-agent P0/P1 adversarial sweep of the full release diff, upgrade/migration dimension mandatory), Phase C (30+ turn live `hermes acp` soak), Phase D (release-over-release scorecard against the previous GA: recall flips, Track S facts kept, QA rows, latency) — before the GA tag. - The GA commit may differ from the passing rc tree by EXACTLY the release-notes addition (mechanically verified: `git diff rcN..GA --name-only` ⊆ `.github/release-notes/`); GA notes link the four phase receipts (A-D). A P0/P1 gauntlet finding means fix → new rc → re-run; the only exception is a Phase B shape or a Phase C publication conflict that the previous GA also shows, with the candidate no worse than the base (the spec's differential rule). - Agents preparing a release produce the rc tag and receipts; the GA cut itself follows the maintainers-own-releases rule above.