From 02d045757f7cd9b876cf1986b3ac8c672587d552 Mon Sep 17 00:00:00 2001 From: Pavlov Alexandr Date: Tue, 25 Aug 2026 02:39:39 +0700 Subject: [PATCH 1/2] chore(agents): sync contract 1.1.0 Replace embedded shared rules with the thin managed bridge. Add the committed SolidStats contract bundle with routed memory ownership and fail-closed loading. Co-Authored-By: GPT-5.6 Sol --- .agent-instructions/solidstats/AGENTS.md | 164 +++++++++++ .../solidstats/CONTRACT_VERSION | 1 + .agent-instructions/solidstats/GSD.md | 87 ++++++ .agent-instructions/solidstats/MEMORY.md | 274 ++++++++++++++++++ .planning/config.json | 11 +- AGENTS.md | 193 +----------- 6 files changed, 547 insertions(+), 183 deletions(-) create mode 100644 .agent-instructions/solidstats/AGENTS.md create mode 100644 .agent-instructions/solidstats/CONTRACT_VERSION create mode 100644 .agent-instructions/solidstats/GSD.md create mode 100644 .agent-instructions/solidstats/MEMORY.md diff --git a/.agent-instructions/solidstats/AGENTS.md b/.agent-instructions/solidstats/AGENTS.md new file mode 100644 index 0000000..bf15af9 --- /dev/null +++ b/.agent-instructions/solidstats/AGENTS.md @@ -0,0 +1,164 @@ + + + +## Contract Bundle Integrity + +Before product work, confirm that every file in the committed contract bundle +is present and readable: + +- `.agent-instructions/solidstats/AGENTS.md`; +- `.agent-instructions/solidstats/CONTRACT_VERSION`; +- `.agent-instructions/solidstats/MEMORY.md`; +- `.agent-instructions/solidstats/GSD.md`. + +If any file is missing or unreadable, stop product work and restore the complete +bundle with the canonical installer. Do not continue from partial instructions, +infer missing routing, or substitute another memory store. Contract freshness +is managed by the repository rollout; do not perform a remote update check at +task start. + +## Skills First + +Before acting on any user request in this repository, scan available skills by name and description. If any skill has even a small chance of helping any part of the task, use it and read only the relevant instructions before proceeding. + +When in doubt, prefer enabling the skill briefly and filtering it out over skipping it. + +## Session Hygiene + +Every completed work session must leave the repository in a clean, committed state: + +- Run `git status --short` at the end of every session. If there are uncommitted changes from + the work just done, commit them before stopping. +- Do **not** delete or revert completed work to fake a clean status. If the intended work is + incomplete, ask what to do rather than silently discarding it. +- The rule is: *commit the intended results of the session, not a reset to the previous state.* + +## Git Conventions + +All commits in every SolidStats repo follow **Conventional Commits**: + +```text +(): +``` + +Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`. +Scope: the phase number, feature area, or affected layer (e.g. `feat(17-03): …`, +`fix(ingest): …`, `docs(planning): …`). + +**Commit and push are standing, default behavior in every `solid-stats` repo** — no per-message +authorization needed. Session Hygiene above already expects every completed session to end +committed; treat commit + push as part of finishing the work, not a separate ask. This does +**not** extend to anything destructive: + +**Absolute rules:** + +- `git reset --hard`, force push, `branch -D`, and `rebase` still require an explicit + instruction from the user in the current message every time — authorization from a previous + message does not carry forward, and the standing commit/push permission above does not imply + it. +- Never skip hooks with `--no-verify` or `--no-gpg-sign` unless explicitly asked to. If a + pre-commit hook fails, fix the underlying issue — the hook is the signal, not the obstacle. +- When a pre-commit hook fails, the commit did not happen. Create a new commit after fixing; + do not amend the previous one (amending could silently modify work that already shipped). + +**Push routing.** The default flow across every `solid-stats` repo is a **direct push to +`master`** — no feature branch, no PR, unless the repo says otherwise below: + +- **`server-2`** has a protected `master` — always go through a branch + pull request there, + never a direct push. +- Any repo that is mid-GSD-milestone follows that milestone's branch flow instead of a direct + push (`git` config in `.planning/config.json` — `branching_strategy`, `phase_branch_template`, + `milestone_branch_template`). +- Every other repo and every non-milestone change: commit on `master`, push directly. + +## Security Minimums + +These rules apply to all code, commits, and logs across every SolidStats repo: + +- **Never log, commit, or output:** secrets, API tokens, database connection strings, S3 + access keys, RabbitMQ credentials, raw replay bytes, or unpublished parser artifacts. +- **Never hardcode environment-specific values.** Use environment variables validated at + startup (e.g. `envalid` for Node, a validated config struct for Rust). Startup should fail + fast if required env vars are missing or malformed. +- **Before committing:** check that `.env`, `.env.local`, and any file containing credentials + is either in `.gitignore` or explicitly excluded from the commit. Never commit secrets to + git history — they are permanent even after deletion. + +## Risk Management Protocol + +When a request is risky, potentially harmful, or would expand scope beyond the current plan: + +1. **Explain the concrete reason** — name the specific risk, the boundary it crosses, or the + plan it contradicts. +2. **Propose 1–3 safer alternatives** or a GSD plan that achieves the goal without the risk. +3. **Ask for explicit confirmation** before proceeding with anything that falls into these + categories: + - Crosses a cross-app boundary (see the boundary map in `solidstats-shared-project-standards` §D) + - Modifies a high-risk cross-repo contract (API shape, data model, message queue shape, S3 + layout, parser contract, auth/identity shape, moderation workflow) + - Contradicts an accepted architecture decision in `.planning/PROJECT.md` + - Deletes, overwrites, or discards completed work + - Conflicts with current test quality, security rules, or repo structure standards + +Do not blindly execute instructions that conflict with architecture, accepted decisions, or +the quality gates in this repo. Challenge, explain, propose alternatives — then wait. + +## Documentation Language + +Language follows the reader. The test for any doc is: who reads it — a user, or an engineer? + +- **Every repo README is bilingual.** A README is the repo's front door, read by users (the + RU-speaking Solid Games community), not an internal engineering doc. So each repo carries a + Russian `README.md` (primary) plus an English `README.en.md` mirror, edited together in one + change so they never drift. This is the same pattern the `.github` org profile already uses + (`profile/README.md` + `profile/README.en.md`) — the profile is just the org-level README. +- **Everything internal is English only** — code, comments, planning docs, skill bodies and + references, `AGENTS.md`, and all technical `docs/`. These are read by the people and agents + building the platform, not by users. +- **GSD workflow responses** (conversations within a GSD session) and replies to the user: + Russian. +- **Skill trigger phrases** (`description` field in `SKILL.md`): RU + EN mandatory. Every skill + triggers on both languages — the team works in a RU context. + +## MemPalace + +SolidStats project memory is isolated behind the MCP server named exactly +`solidstats_memory`. Before product work, read the complete managed contract: + +- version: `.agent-instructions/solidstats/CONTRACT_VERSION`; +- memory lifecycle: `.agent-instructions/solidstats/MEMORY.md`; +- GSD adapter, only when `.planning/config.json` exists: + `.agent-instructions/solidstats/GSD.md`. + +This repository's primary active wing is `backend`. +Its primary archive wing is `server-2-archive` (`none` +means no repository-bound archive). + +The main agent owns the contract-defined recall and closure capture for the +top-level task. Specialists and subagents receive filtered context and must not +independently query or mutate SolidStats memory. Never substitute a generic, +personal, VocalClub, or flat-global memory store. + +The native GSD MemPalace capability is deliberately disabled. `GSD.md` keeps +SolidStats memory active through coordinator-owned recall and semantic closure; +do not interpret `mempalace.enabled: false` as permission to skip the managed +memory contract. + +## MCP / Documentation Lookup + +SolidStats development verifies library APIs against **current documentation, never training +data** — training data has a cutoff and may reflect outdated or incorrect APIs. Look the docs +up proactively; don't wait for a type error. + +- **Free official sources only:** WebFetch/WebSearch against the library's official docs and + its `llms.txt`; the repo's `README`/`docs/` via `gh`; GitHub issues/PRs for bug reports and + migrations. **Do NOT use Context7 or any paid documentation MCP.** +- **Common lookup triggers:** adding a dependency, upgrading a package, using a method you're + not 100% sure about, hitting an unexpected type error, writing a new integration. +- **When NOT to look it up:** SolidStats-specific code/business logic; a library already + looked up this session with an unchanged answer; stable standard-library APIs. + +Per-repo key libraries to verify against current docs live in each repo's own +`solidstats-*-conventions` skill, not here. diff --git a/.agent-instructions/solidstats/CONTRACT_VERSION b/.agent-instructions/solidstats/CONTRACT_VERSION new file mode 100644 index 0000000..9084fa2 --- /dev/null +++ b/.agent-instructions/solidstats/CONTRACT_VERSION @@ -0,0 +1 @@ +1.1.0 diff --git a/.agent-instructions/solidstats/GSD.md b/.agent-instructions/solidstats/GSD.md new file mode 100644 index 0000000..8df86d7 --- /dev/null +++ b/.agent-instructions/solidstats/GSD.md @@ -0,0 +1,87 @@ + + +# SolidStats memory adapter for GSD + +## Applicability + +Read this file completely only when the current repository contains +`.planning/config.json`. The sibling `MEMORY.md` contract remains authoritative +for scope, ownership, recall, capture, safety, correction, and failure behavior. + +## Native capability is deliberately disabled + +Every synced SolidStats GSD config must retain this fail-closed native block: + +```json +{ + "mempalace": { + "enabled": false, + "memory_mode": "augment", + "wing": "", + "recall_on_discuss": false, + "recall_on_plan": false, + "capture_artifacts": false, + "mirror_kg": false, + "cross_project_tunnels": false, + "diary_journal": false, + "auto_capture_hooks": false + } +} +``` + +`enabled: false` disables only GSD's incompatible generic MemPalace +capability. It does not disable the `solidstats_memory` MCP or this adapter. + +Do not run `gsd-mempalace-recall`, `gsd-mempalace-capture`, generic +execute-wave problem capture, or `gsd-mempalace-curator`. Do not create a +`MEMORY-RECALL.md` artifact. The generic handlers use the wrong server +namespace, raw artifact capture, unsupported rooms, KG, diary, and tunnel +semantics. + +## Coordinator-owned recall + +The main GSD coordinator runs the federated recall from `MEMORY.md` at most +once per top-level GSD task: + +- before discussion questions for discuss-oriented entry points; +- before the first specialist for execute, verify, review, ship, quick, fast, + debug, and any future entry point that has not already recalled; +- before a directly invoked plan only when the current top-level task has no + provenance-bearing recalled context. Inject the filtered results directly + into the planner prompt; never create a separate plan-recall artifact. + +When discussion already recalled and its verified context is carried into +planning or execution, do not recall again. A resumed or compacted task keeps +the same top-level ownership if the provenance-bearing context is still +available. + +Run the initial wing searches in the first tool batch after repository and +contract routing is known. Fold relevant, verified facts into the discussion +and owner-native `CONTEXT.md` when discussion owns that artifact. For other +entry points, pass a compact memory context block directly to the relevant +specialist. Include drawer IDs, owning wings, sources, and staleness caveats. + +Subagents and GSD specialists must not recall or capture independently. + +## Semantic closure + +Wave completion must not write memory. Raw plans, summaries, problem lists, +review reports, and verification files remain in `.planning` only. + +Before the first final handoff that closes the top-level GSD task, the main +coordinator runs the `MEMORY.md` durable capture gate. Capture only new verified +semantic conclusions. A routine plan, execution, or passing verification with +no durable conclusion produces no drawer. + +A long workflow may safely defer capture until top-level closure because its +verified intermediate state remains in committed GSD artifacts. Do not create +partial memory merely to survive a wave boundary. + +Corrections remain in the curator flow. A GSD ship operation must not dispatch +the generic MemPalace curator. + +## Failure behavior + +If `solidstats_memory` is unavailable, follow the one-retry and primary-evidence +fallback contract in `MEMORY.md`. GSD continues; it must not use a different +palace, generic CLI, flat memory, or local outbox. diff --git a/.agent-instructions/solidstats/MEMORY.md b/.agent-instructions/solidstats/MEMORY.md new file mode 100644 index 0000000..aec093e --- /dev/null +++ b/.agent-instructions/solidstats/MEMORY.md @@ -0,0 +1,274 @@ + + +# SolidStats agent memory contract + +This contract governs project memory for every repository listed in the +canonical `config/repositories.tsv` manifest. The rendered companion +`AGENTS.md` in each repository declares that repository's primary active wing +and primary archive wing. + +## Instance and authority boundary + +- Use only the MCP server named `solidstats_memory` for SolidStats memory. +- Never use a generic `mempalace`, `mempalace_personal`, `vocalclub_memory`, + flat global memory, or a local outbox as a substitute. +- The shared bearer token does not provide personal attribution or per-tool + authorization. Treat every mutation as privileged. +- Current user instructions and applicable repository instructions have the + highest authority. Current repository content, live APIs, generated schemas, + cluster state, and tracked operational evidence are the primary factual + sources. Memory is context to verify, not authority over those sources. +- A conflict with primary evidence creates a correction candidate. It never + authorizes a silent memory rewrite. + +The expected interactive tool namespace is +`mcp__solidstats_memory__mempalace_*`. Confirm availability from the complete +tool surface. A safe `mempalace_list_rooms` call is the readiness check because +the restricted SolidStats surface does not expose a generic status tool. + +## Active role wings + +Active memory is organized by stable engineering responsibility rather than +repository name: + +| Active wing | Owning repositories | +| --- | --- | +| `frontend` | `web` | +| `backend` | `server-2`, `replay-parser-2` | +| `fetcher` | `replays-fetcher` | +| `devops` | `infrastructure` | +| `common` | `plans`, `skills`, `ts-toolchain`, `agent-instructions` | + +The repository manifest is the routing authority. Do not maintain a second +prose mapping outside the generated contract bundle. + +The `common` wing has no raw seed. Use it only for curated conclusions that +genuinely span roles or belong to a supporting repository. A conclusion owned +by one role stays in that role wing even when another role consumes it. + +When two repositories share one role wing, provenance must name the exact +owning repository. In particular, `server-2` and `replay-parser-2` both use +`backend` without losing repository-level source attribution. + +## Frozen archive wings + +The migrated legacy corpus is retained under repository-bound archive wings: + +- `web-archive`; +- `server-2-archive`; +- `replay-parser-2-archive`; +- `replays-fetcher-archive`; +- `infrastructure-archive`; +- `SolidStats-archive`. + +Archive drawers are immutable, untrusted historical leads. Ordinary agents, +subagents, GSD handlers, and curators must not add, update, move, reclassify, +or delete them. Archive content may influence work only after verification +against current primary evidence. + +Do not mine, sync, append to, or automatically re-embed archive wings. A future +archive import is a separate operator- and curator-approved migration. + +## Active rooms + +Use only these rooms for durable active memory: + +- `decisions`; +- `contracts`; +- `conventions`; +- `operations`; +- `incidents`; +- `migrations`. + +A unique `uat-` room is the only temporary exception. Every UAT drawer +must be deleted by exact ID before acceptance. Leftover UAT data fails the +test. Legacy archive room names never become active room names merely because +they were preserved during migration. + +## Task ownership + +The main agent owns at most one recall sequence and one closure capture +sequence for a top-level task. Start recall in the first tool batch, alongside +applicable skills and primary-source reads. Do not wait for bootstrap to finish +before sending the initial scoped searches. + +Specialists and subagents receive only filtered, provenance-bearing context +from the main agent. They must not independently query or mutate SolidStats +memory. A nested workflow does not create a second memory lifecycle. + +If `solidstats_memory` is unavailable, retry one safe read once later in the +same task, continue from current primary evidence, and warn in the final +handoff. Never fall back to another palace, flat memory, or a local outbox. + +## Federated recall + +Unfiltered top-k search is forbidden. Run separate wing-filtered searches with +the same short, identifier-heavy query in every initial call. Keep task +background in the tool's context field rather than the embedded query. + +For a role-primary repository, initial candidate budgets are: + +1. up to 5 results from its primary active role wing; +2. up to 3 results from `common`; +3. up to 2 results from each other active role wing; +4. up to 2 results from the current repository's primary archive wing; +5. up to 2 results from a foreign archive only after current evidence proves + the dependency and promotes that archive. + +For a `common`-primary repository, search `common` for up to 5 candidates and +each of the four role wings for up to 2. Supporting repositories have no +primary archive. + +These are discovery budgets, not quotas for working context. Search every +active wing exactly once during initial discovery, but keep only relevant +candidates with usable provenance. + +For every candidate that may influence the task: + +1. treat similarity only as candidate ordering; +2. fetch the complete drawer by exact ID; +3. inspect its sources and ownership; +4. verify it against current primary evidence when available; +5. label archive evidence as historical and weaker than active semantic + memory. + +Explicit tunnels, temporal KG facts, and diaries are not part of SolidStats +recall. Do not query or create them. + +## Evidence-seeded expansion + +Seed the first queries from identifiers already present in the request: issue +keys, branch or commit names, endpoints, entities, services, exact errors, or +symptoms. Use the same identifiers in every initial active-wing search. + +Promote an active wing or foreign archive only when a relevant drawer or a +verified current source proves the dependency. Follow-up query terms may come +only from: + +- the user request; +- a relevant fetched drawer; +- a verified current primary source. + +A promoted active wing has no fixed follow-up limit. Continue while new results +change the task model; stop when they repeat, become irrelevant, or add no new +verified identifiers. Promotion lasts only for the current top-level task. + +## Scoped miss fallback + +A semantic search miss is not proof that memory is absent. For the primary +wing, `common`, the primary archive, and every promoted scope: + +1. retry with an alternate query seeded from current evidence; +2. inspect that wing's rooms; +3. list a bounded set of drawers in the likely wing and room; +4. fetch plausible drawers by exact ID; +5. report no relevant memory only after these scoped checks fail. + +Do not widen an unpromoted foreign archive after a miss. + +## Durable capture gate + +Before the first final handoff that closes a completed top-level task, classify +its verified semantic conclusions. Capture only knowledge useful beyond the +task: + +- an accepted decision; +- an API, data, parser, queue, or integration contract; +- a stable engineering convention; +- an operational invariant or procedure; +- a proven incident root cause and prevention lesson; +- migration state that future work must preserve. + +If the task produced no independently durable conclusion, write nothing. + +Never store raw prompts, transcripts, reasoning, patches, source code, +generated code, logs, request dumps, credentials, personal information, +temporary status, passing-check narration, or raw GSD artifacts such as +`CONTEXT.md`, `PLAN.md`, and `SUMMARY.md`. + +Store one independent fact per drawer in this shape: + +```text +Task: +Outcome: +Decisions: +Validation: +Sources: +Supersedes: +``` + +`Supersedes` is omitted for an ordinary new fact. Sources must use exact +repository and ref plus repository-relative paths, issue or commit IDs, live +schema endpoints, or other durable evidence. Never cite an ephemeral worktree +or private machine-local artifact path. + +Route the drawer to the role that owns the conclusion. Use `common` only for +cross-role or supporting-repository conclusions. Do not mirror the same fact +across wings. + +Before writing: + +1. search the target wing for equivalent or conflicting content; +2. fetch relevant candidates; +3. no-op an equivalent fact; +4. route conflicts into the correction flow; +5. call `mempalace_check_duplicate` before `mempalace_add_drawer`; +6. after adding, fetch the new drawer and verify wing, room, complete content, + provenance, and absence of sensitive values. + +Do not call checkpoint, diary, KG, tunnel, mining, sync, or bulk-delete tools. + +## Correction and deletion + +Ordinary agents are read-only with respect to existing drawers. A suspected +error becomes a correction candidate containing: + +- the exact drawer ID; +- the current primary evidence; +- the exact proposed content, wing, or room change; +- the reason for the correction; +- the verification query and read-back checks. + +A curator presents a concrete batch preview. User approval authorizes only the +exact IDs and mutations shown in that batch. A changed batch requires new +approval. + +After approval, `mempalace_update_drawer` may correct an active drawer while +preserving its identity and valid provenance. Include correcting sources in the +drawer content. Re-fetch the exact ID after every mutation and compare it with +the approved batch. + +Use `mempalace_delete_drawer` only for an approved exact duplicate, confirmed +secret, specifically approved erroneous active drawer, or disposable +`uat-` record. Deletion is exact-ID only. Never update or delete an +archive drawer. + +## Archive distillation + +Archive distillation is a separate post-cutover phase. Low-cost extraction +agents may inspect bounded, repository-owned archive shards and produce +candidate records, but they remain read-only and must not capture directly. + +Each candidate must include the exact archive wing and drawer ID, proposed +active owner and room, durable conclusion, legacy provenance, current sources +needed for verification, and confidence. Record shard coverage so completed +shards are not rescanned. + +Deduplicate candidates against active memory and each other. A curator verifies +surviving candidates against current evidence. Promotion creates a new active +semantic drawer; it never moves or changes the archive drawer. Most archive +records may remain unpromoted. + +## Acceptance invariants + +- `solidstats_memory` is the only SolidStats MCP namespace. +- Personal and VocalClub memory remain isolated. +- Initial recall searches all five active wings with the accepted budgets. +- Archive lookup stays scoped, evidence-promoted, and read-only. +- Relevant drawers are fetched and source-checked before use. +- Semantic miss fallback is bounded and wing-scoped. +- Tunnels, KG, diary, raw GSD artifacts, and agent wings are absent. +- Durable capture writes one verified fact once; no conclusion means no write. +- Corrections require exact curator preview, approval, mutation, and read-back. +- UAT creates no permanent data. +- Every consumer repository carries the same accepted contract version. diff --git a/.planning/config.json b/.planning/config.json index fc051c5..dc9131a 100644 --- a/.planning/config.json +++ b/.planning/config.json @@ -211,7 +211,16 @@ "enabled": true }, "mempalace": { - "enabled": true + "enabled": false, + "memory_mode": "augment", + "recall_on_discuss": false, + "recall_on_plan": false, + "capture_artifacts": false, + "mirror_kg": false, + "cross_project_tunnels": false, + "diary_journal": false, + "auto_capture_hooks": false, + "wing": "backend" }, "code_quality": { "fallow": { diff --git a/AGENTS.md b/AGENTS.md index af22978..6369381 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,188 +1,17 @@ - - -## Skills First - -Before acting on any user request in this repository, scan available skills by name and description. If any skill has even a small chance of helping any part of the task, use it and read only the relevant instructions before proceeding. - -When in doubt, prefer enabling the skill briefly and filtering it out over skipping it. -## Session Hygiene - -Every completed work session must leave the repository in a clean, committed state: - -- Run `git status --short` at the end of every session. If there are uncommitted changes from - the work just done, commit them before stopping. -- Do **not** delete or revert completed work to fake a clean status. If the intended work is - incomplete, ask what to do rather than silently discarding it. -- The rule is: *commit the intended results of the session, not a reset to the previous state.* - -## Git Conventions - -All commits in every SolidStats repo follow **Conventional Commits**: - -```text -(): -``` - -Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`. -Scope: the phase number, feature area, or affected layer (e.g. `feat(17-03): …`, -`fix(ingest): …`, `docs(planning): …`). - -**Commit and push are standing, default behavior in every `solid-stats` repo** — no per-message -authorization needed. Session Hygiene above already expects every completed session to end -committed; treat commit + push as part of finishing the work, not a separate ask. This does -**not** extend to anything destructive: - -**Absolute rules:** - -- `git reset --hard`, force push, `branch -D`, and `rebase` still require an explicit - instruction from the user in the current message every time — authorization from a previous - message does not carry forward, and the standing commit/push permission above does not imply - it. -- Never skip hooks with `--no-verify` or `--no-gpg-sign` unless explicitly asked to. If a - pre-commit hook fails, fix the underlying issue — the hook is the signal, not the obstacle. -- When a pre-commit hook fails, the commit did not happen. Create a new commit after fixing; - do not amend the previous one (amending could silently modify work that already shipped). - -**Push routing.** The default flow across every `solid-stats` repo is a **direct push to -`master`** — no feature branch, no PR, unless the repo says otherwise below: - -- **`server-2`** has a protected `master` — always go through a branch + pull request there, - never a direct push. -- Any repo that is mid-GSD-milestone follows that milestone's branch flow instead of a direct - push (`git` config in `.planning/config.json` — `branching_strategy`, `phase_branch_template`, - `milestone_branch_template`). -- Every other repo and every non-milestone change: commit on `master`, push directly. - -## Security Minimums - -These rules apply to all code, commits, and logs across every SolidStats repo: - -- **Never log, commit, or output:** secrets, API tokens, database connection strings, S3 - access keys, RabbitMQ credentials, raw replay bytes, or unpublished parser artifacts. -- **Never hardcode environment-specific values.** Use environment variables validated at - startup (e.g. `envalid` for Node, a validated config struct for Rust). Startup should fail - fast if required env vars are missing or malformed. -- **Before committing:** check that `.env`, `.env.local`, and any file containing credentials - is either in `.gitignore` or explicitly excluded from the commit. Never commit secrets to - git history — they are permanent even after deletion. - -## Risk Management Protocol - -When a request is risky, potentially harmful, or would expand scope beyond the current plan: - -1. **Explain the concrete reason** — name the specific risk, the boundary it crosses, or the - plan it contradicts. -2. **Propose 1–3 safer alternatives** or a GSD plan that achieves the goal without the risk. -3. **Ask for explicit confirmation** before proceeding with anything that falls into these - categories: - - Crosses a cross-app boundary (see the boundary map in `solidstats-shared-project-standards` §D) - - Modifies a high-risk cross-repo contract (API shape, data model, message queue shape, S3 - layout, parser contract, auth/identity shape, moderation workflow) - - Contradicts an accepted architecture decision in `.planning/PROJECT.md` - - Deletes, overwrites, or discards completed work - - Conflicts with current test quality, security rules, or repo structure standards - -Do not blindly execute instructions that conflict with architecture, accepted decisions, or -the quality gates in this repo. Challenge, explain, propose alternatives — then wait. - -## Documentation Language - -Language follows the reader. The test for any doc is: who reads it — a user, or an engineer? - -- **Every repo README is bilingual.** A README is the repo's front door, read by users (the - RU-speaking Solid Games community), not an internal engineering doc. So each repo carries a - Russian `README.md` (primary) plus an English `README.en.md` mirror, edited together in one - change so they never drift. This is the same pattern the `.github` org profile already uses - (`profile/README.md` + `profile/README.en.md`) — the profile is just the org-level README. -- **Everything internal is English only** — code, comments, planning docs, skill bodies and - references, `AGENTS.md`, and all technical `docs/`. These are read by the people and agents - building the platform, not by users. -- **GSD workflow responses** (conversations within a GSD session) and replies to the user: - Russian. -- **Skill trigger phrases** (`description` field in `SKILL.md`): RU + EN mandatory. Every skill - triggers on both languages — the team works in a RU context. - -## MemPalace - -Every SolidStats repo has its own MemPalace **wing, named after the repo itself** -(`web`, `server-2`, `replays-fetcher`, `replay-parser-2`, `infrastructure`, `skills`) — use the -generic `mcp__mempalace__*` tools, scoped to that wing; there is no isolated per-project MCP -server here (unlike VocalClub's `vocalclub_memory`). Never file a durable fact into the wrong -repo's wing, and never invent a new wing name. - -**Inside a GSD workflow, most of this is already automatic.** The `mempalace` GSD capability -injects recall into `discuss:pre` (gated by `mempalace.recall_on_discuss`) and capture into -`execute:wave:post` (gated by `mempalace.capture_artifacts`), plus a ship-time curator -(`gsd-mempalace-curator`) — see `gsd/common-config.json` for the shared defaults and each -repo's `.planning/config.json` for the rest. Don't re-implement that cycle by hand inside a GSD -phase; the sections below are for everything GSD's own injection doesn't cover — ad-hoc -diagnosis, a non-GSD session, or manual recall/capture outside a phase boundary. - -- **Recall before diagnosing or building**, not just when a hook happens to inject a snippet. - Run an explicit `mempalace_search` seeded from the task's real identifiers (symptom, service - name, ticket) at the start of the session — a pattern-match to "we just touched this" is not - recall, and a miss is not proof of absence (follow up with `mempalace_list_drawers` / - `mempalace_kg_query` before concluding nothing is stored). -- **Capture only durable, verified conclusions** at closure — a decision, a root cause, a - resolved gotcha — not raw session transcripts, planning artifacts, or GSD's own - `CONTEXT.md`/`PLAN.md`/`SUMMARY.md` files. Dedup with `mempalace_check_duplicate` before - filing. -- **`memory_mode` stays `augment`** (GSD's own default): the palace is an additional layer, - never a replacement for `.planning/graphs/` or `STATE.md`. **Never enable - `mempalace.recall_on_plan`** — the planner doesn't automatically consume that separate - recall artifact, so it just produces an orphaned memory read; the top-level coordinator's one - scoped recall (at `discuss:pre`, or manually for entry points with no native recall hook — - `gsd-quick`, `gsd-fast`, `gsd-debug`) is the single recall point per task. Specialists and - subagents don't independently recall or capture — they get a filtered context handoff from - whichever level already recalled. - -### Cross-repo tunnels — use them, don't just avoid duplicating - -SolidStats is a genuinely multi-repo platform (§D/§E) — a decision at a cross-app boundary or -contract change routinely concerns two wings at once, unlike VC's setup, which leaves -`cross_project_tunnels` off. Here it should be **on and actually used**, not just a -de-duplication fallback: - -- **Create a tunnel** (`mempalace_create_tunnel`) whenever a captured fact genuinely concerns - two repos — an API/data-model/queue/S3-layout/parser-contract decision (§E's high-risk list) - almost always does. File the fact once, in the wing of the repo that owns the decision, then - tunnel it to the other wing(s) it affects instead of duplicating the drawer. -- **Query tunnels during recall, not just search.** A wing-scoped `mempalace_search` alone can - miss a relevant fact filed under an adjacent repo's wing. Before or alongside recall on a - cross-app task, run `mempalace_find_tunnels` (between the two wings in play) or - `mempalace_follow_tunnels` (from the current wing) to surface what's already linked. -- **`mempalace.mirror_kg`** (per-repo, stays local — see below) governs whether decision facts - also mirror into the temporal knowledge graph; tunnels connect *drawers*, `mempalace_kg_add` - connects *typed facts* — use whichever fits what's actually being captured, and both where a - cross-repo decision has both a narrative and a queryable shape (e.g. a validity window). -- **`mempalace.enabled` and `mempalace.cross_project_tunnels`** are common defaults in - `agent-instructions`' `gsd/common-config.json` — the latter is a deliberate override of - gsd-core's own default (`false`), because a single-service default doesn't fit a genuinely - multi-repo platform. The richer per-repo flags (`capture_artifacts`, `mirror_kg`, - `auto_capture_hooks`) are tuned per repo and stay local — a backend service and a frontend - repo do not need identical capture behavior. - -## MCP / Documentation Lookup - -SolidStats development verifies library APIs against **current documentation, never training -data** — training data has a cutoff and may reflect outdated or incorrect APIs. Look the docs -up proactively; don't wait for a type error. - -- **Free official sources only:** WebFetch/WebSearch against the library's official docs and - its `llms.txt`; the repo's `README`/`docs/` via `gh`; GitHub issues/PRs for bug reports and - migrations. **Do NOT use Context7 or any paid documentation MCP.** -- **Common lookup triggers:** adding a dependency, upgrading a package, using a method you're - not 100% sure about, hitting an unexpected type error, writing a new integration. -- **When NOT to look it up:** SolidStats-specific code/business logic; a library already - looked up this session with an unchanged answer; stable standard-library APIs. - -Per-repo key libraries to verify against current docs live in each repo's own -`solidstats-*-conventions` skill, not here. +## SolidStats shared agent contract + +Before any work in this repository, read +`.agent-instructions/solidstats/AGENTS.md` completely and follow it. + +The committed contract bundle is mandatory. If any of its files is missing or +unreadable, stop product work and restore the bundle with the canonical +installer. Do not continue from partial instructions or another memory store. + +This block is generated by `solid-stats/agent-instructions`. Do not edit it by +hand in a consumer repository. # server-2 — SolidStats backend (platform service) From 5a246f4dc8a649695e97a867f2468201ae99c426 Mon Sep 17 00:00:00 2001 From: Pavlov Alexandr Date: Tue, 25 Aug 2026 02:45:08 +0700 Subject: [PATCH 2/2] fix(format): exclude managed agent contract Keep consumer formatters from rewriting canonical Markdown. The generated contract remains owned and linted by solid-stats/agent-instructions. Co-Authored-By: GPT-5.6 Sol --- .prettierignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.prettierignore b/.prettierignore index 683e0fe..314b80e 100644 --- a/.prettierignore +++ b/.prettierignore @@ -6,6 +6,7 @@ node_modules gsd-briefs openapi AGENTS.md +.agent-instructions/ # Golden oracle file snapshots are machine-generated by `test:golden` # (vitest toMatchFileSnapshot, JSON.stringify(...,2)); prettier must not rewrite