AGENTS.md git:20261016.ac9978dA

Immutable. This exact content never changes and is served at /api/v1/blob/22ebe77b51d1f79e.

# 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)`), 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
  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.