git:20261019.d6afbef to git:20261019.04f94f2

# 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.

- The invariant catalogue, `docs/invariants.md` (I1-I14), names each invariant with its code,

tests and proof status; specs and review packets cite invariant IDs.

## 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.

## Filing issues

Search open and closed issues and pull requests before filing. Use the bug form's

headings: What happened, What you expected, Steps to reproduce, Plugin version,

Hermes version, Where it happened, Operating system, Diagnostics, and Impact,

regression range, and data symptoms. Put short log excerpts, the relevant config,

and what you already ran under Diagnostics. Maintainers filing through the CLI pass

`--label bug,triage-pending` or `--label bug,triaged` after triage, plus

`--label agent-drafted` when an agent wrote the report. These labels do not grant

filing authority; show the draft and obtain the reporter's approval first.

## 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.

- Judge a fix against the previous GA and its sibling input shapes, per `docs/process/fix-scope.md`.

A change on the turn path (assembly, compaction, survival fit, ingest, the summary route,

the host `compress` contract) carries the probe packet in

`docs/process/turn-path-probe-packet.md`.

- Structural refactors follow `docs/process/refactor-window.md`: one move per `refactor-only`

PR, characterization first, no behaviour change mixed with moves.

- Schema changes follow `docs/process/schema-changes.md`: no new DDL owners, the migration's

format and oldest reader recorded, forward and rollback tests.

- 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`

and `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 only

for visual changes; video is never required.

- Do not name private repositories in this repo, PRs, issues or releases.

- 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)`, and `differential` on the PR head), 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: <lane> — <reason>` 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 `<sha>`, false with evidence, accepted tradeoff, or

follow-up `<issue>`.

- 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 <PR> --merge --match-head-commit <HEAD_SHA>

```

- 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

exceptions are a Phase B shape or a Phase C publication conflict that the previous GA also

shows, with the candidate no worse than the base; and a Phase B duplicate-only shape reachable

- Agents preparing a release produce the rc tag and receipts; the GA cut itself follows the

maintainers-own-releases rule above.