Skip to content

Commit 9915439

Browse files
Afgan0rcodex
Afgan0r
and
codex
authored
chore(agents): sync contract 1.1.0 (#40)
* 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 <noreply@openai.com> * 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 <noreply@openai.com> --------- Co-authored-by: GPT-5.6 Sol <noreply@openai.com>
1 parent 140ef4f commit 9915439

7 files changed

Lines changed: 548 additions & 183 deletions

File tree

‎.agent-instructions/solidstats/AGENTS.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
<!-- markdownlint-disable MD013 MD041 -->
2+
<!-- Managed by solid-stats/agent-instructions. Do not hand-edit in a consumer repo — changes
3+
are overwritten by the next contract rollout. Edit the source at
4+
https://github.com/solid-stats/agent-instructions/blob/master/shared/AGENTS.md instead. -->
5+
6+
## Contract Bundle Integrity
7+
8+
Before product work, confirm that every file in the committed contract bundle
9+
is present and readable:
10+
11+
- `.agent-instructions/solidstats/AGENTS.md`;
12+
- `.agent-instructions/solidstats/CONTRACT_VERSION`;
13+
- `.agent-instructions/solidstats/MEMORY.md`;
14+
- `.agent-instructions/solidstats/GSD.md`.
15+
16+
If any file is missing or unreadable, stop product work and restore the complete
17+
bundle with the canonical installer. Do not continue from partial instructions,
18+
infer missing routing, or substitute another memory store. Contract freshness
19+
is managed by the repository rollout; do not perform a remote update check at
20+
task start.
21+
22+
## Skills First
23+
24+
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.
25+
26+
When in doubt, prefer enabling the skill briefly and filtering it out over skipping it.
27+
28+
## Session Hygiene
29+
30+
Every completed work session must leave the repository in a clean, committed state:
31+
32+
- Run `git status --short` at the end of every session. If there are uncommitted changes from
33+
the work just done, commit them before stopping.
34+
- Do **not** delete or revert completed work to fake a clean status. If the intended work is
35+
incomplete, ask what to do rather than silently discarding it.
36+
- The rule is: *commit the intended results of the session, not a reset to the previous state.*
37+
38+
## Git Conventions
39+
40+
All commits in every SolidStats repo follow **Conventional Commits**:
41+
42+
```text
43+
<type>(<scope>): <short description>
44+
```
45+
46+
Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`.
47+
Scope: the phase number, feature area, or affected layer (e.g. `feat(17-03): …`,
48+
`fix(ingest): …`, `docs(planning): …`).
49+
50+
**Commit and push are standing, default behavior in every `solid-stats` repo** — no per-message
51+
authorization needed. Session Hygiene above already expects every completed session to end
52+
committed; treat commit + push as part of finishing the work, not a separate ask. This does
53+
**not** extend to anything destructive:
54+
55+
**Absolute rules:**
56+
57+
- `git reset --hard`, force push, `branch -D`, and `rebase` still require an explicit
58+
instruction from the user in the current message every time — authorization from a previous
59+
message does not carry forward, and the standing commit/push permission above does not imply
60+
it.
61+
- Never skip hooks with `--no-verify` or `--no-gpg-sign` unless explicitly asked to. If a
62+
pre-commit hook fails, fix the underlying issue — the hook is the signal, not the obstacle.
63+
- When a pre-commit hook fails, the commit did not happen. Create a new commit after fixing;
64+
do not amend the previous one (amending could silently modify work that already shipped).
65+
66+
**Push routing.** The default flow across every `solid-stats` repo is a **direct push to
67+
`master`** — no feature branch, no PR, unless the repo says otherwise below:
68+
69+
- **`server-2`** has a protected `master` — always go through a branch + pull request there,
70+
never a direct push.
71+
- Any repo that is mid-GSD-milestone follows that milestone's branch flow instead of a direct
72+
push (`git` config in `.planning/config.json` — `branching_strategy`, `phase_branch_template`,
73+
`milestone_branch_template`).
74+
- Every other repo and every non-milestone change: commit on `master`, push directly.
75+
76+
## Security Minimums
77+
78+
These rules apply to all code, commits, and logs across every SolidStats repo:
79+
80+
- **Never log, commit, or output:** secrets, API tokens, database connection strings, S3
81+
access keys, RabbitMQ credentials, raw replay bytes, or unpublished parser artifacts.
82+
- **Never hardcode environment-specific values.** Use environment variables validated at
83+
startup (e.g. `envalid` for Node, a validated config struct for Rust). Startup should fail
84+
fast if required env vars are missing or malformed.
85+
- **Before committing:** check that `.env`, `.env.local`, and any file containing credentials
86+
is either in `.gitignore` or explicitly excluded from the commit. Never commit secrets to
87+
git history — they are permanent even after deletion.
88+
89+
## Risk Management Protocol
90+
91+
When a request is risky, potentially harmful, or would expand scope beyond the current plan:
92+
93+
1. **Explain the concrete reason** — name the specific risk, the boundary it crosses, or the
94+
plan it contradicts.
95+
2. **Propose 1–3 safer alternatives** or a GSD plan that achieves the goal without the risk.
96+
3. **Ask for explicit confirmation** before proceeding with anything that falls into these
97+
categories:
98+
- Crosses a cross-app boundary (see the boundary map in `solidstats-shared-project-standards` §D)
99+
- Modifies a high-risk cross-repo contract (API shape, data model, message queue shape, S3
100+
layout, parser contract, auth/identity shape, moderation workflow)
101+
- Contradicts an accepted architecture decision in `.planning/PROJECT.md`
102+
- Deletes, overwrites, or discards completed work
103+
- Conflicts with current test quality, security rules, or repo structure standards
104+
105+
Do not blindly execute instructions that conflict with architecture, accepted decisions, or
106+
the quality gates in this repo. Challenge, explain, propose alternatives — then wait.
107+
108+
## Documentation Language
109+
110+
Language follows the reader. The test for any doc is: who reads it — a user, or an engineer?
111+
112+
- **Every repo README is bilingual.** A README is the repo's front door, read by users (the
113+
RU-speaking Solid Games community), not an internal engineering doc. So each repo carries a
114+
Russian `README.md` (primary) plus an English `README.en.md` mirror, edited together in one
115+
change so they never drift. This is the same pattern the `.github` org profile already uses
116+
(`profile/README.md` + `profile/README.en.md`) — the profile is just the org-level README.
117+
- **Everything internal is English only** — code, comments, planning docs, skill bodies and
118+
references, `AGENTS.md`, and all technical `docs/`. These are read by the people and agents
119+
building the platform, not by users.
120+
- **GSD workflow responses** (conversations within a GSD session) and replies to the user:
121+
Russian.
122+
- **Skill trigger phrases** (`description` field in `SKILL.md`): RU + EN mandatory. Every skill
123+
triggers on both languages — the team works in a RU context.
124+
125+
## MemPalace
126+
127+
SolidStats project memory is isolated behind the MCP server named exactly
128+
`solidstats_memory`. Before product work, read the complete managed contract:
129+
130+
- version: `.agent-instructions/solidstats/CONTRACT_VERSION`;
131+
- memory lifecycle: `.agent-instructions/solidstats/MEMORY.md`;
132+
- GSD adapter, only when `.planning/config.json` exists:
133+
`.agent-instructions/solidstats/GSD.md`.
134+
135+
This repository's primary active wing is `backend`.
136+
Its primary archive wing is `server-2-archive` (`none`
137+
means no repository-bound archive).
138+
139+
The main agent owns the contract-defined recall and closure capture for the
140+
top-level task. Specialists and subagents receive filtered context and must not
141+
independently query or mutate SolidStats memory. Never substitute a generic,
142+
personal, VocalClub, or flat-global memory store.
143+
144+
The native GSD MemPalace capability is deliberately disabled. `GSD.md` keeps
145+
SolidStats memory active through coordinator-owned recall and semantic closure;
146+
do not interpret `mempalace.enabled: false` as permission to skip the managed
147+
memory contract.
148+
149+
## MCP / Documentation Lookup
150+
151+
SolidStats development verifies library APIs against **current documentation, never training
152+
data** — training data has a cutoff and may reflect outdated or incorrect APIs. Look the docs
153+
up proactively; don't wait for a type error.
154+
155+
- **Free official sources only:** WebFetch/WebSearch against the library's official docs and
156+
its `llms.txt`; the repo's `README`/`docs/` via `gh`; GitHub issues/PRs for bug reports and
157+
migrations. **Do NOT use Context7 or any paid documentation MCP.**
158+
- **Common lookup triggers:** adding a dependency, upgrading a package, using a method you're
159+
not 100% sure about, hitting an unexpected type error, writing a new integration.
160+
- **When NOT to look it up:** SolidStats-specific code/business logic; a library already
161+
looked up this session with an unchanged answer; stable standard-library APIs.
162+
163+
Per-repo key libraries to verify against current docs live in each repo's own
164+
`solidstats-*-conventions` skill, not here.

‎.agent-instructions/solidstats/CONTRACT_VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.1.0

‎.agent-instructions/solidstats/GSD.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
<!-- markdownlint-disable MD013 -->
2+
3+
# SolidStats memory adapter for GSD
4+
5+
## Applicability
6+
7+
Read this file completely only when the current repository contains
8+
`.planning/config.json`. The sibling `MEMORY.md` contract remains authoritative
9+
for scope, ownership, recall, capture, safety, correction, and failure behavior.
10+
11+
## Native capability is deliberately disabled
12+
13+
Every synced SolidStats GSD config must retain this fail-closed native block:
14+
15+
```json
16+
{
17+
"mempalace": {
18+
"enabled": false,
19+
"memory_mode": "augment",
20+
"wing": "<primary role wing from the manifest>",
21+
"recall_on_discuss": false,
22+
"recall_on_plan": false,
23+
"capture_artifacts": false,
24+
"mirror_kg": false,
25+
"cross_project_tunnels": false,
26+
"diary_journal": false,
27+
"auto_capture_hooks": false
28+
}
29+
}
30+
```
31+
32+
`enabled: false` disables only GSD's incompatible generic MemPalace
33+
capability. It does not disable the `solidstats_memory` MCP or this adapter.
34+
35+
Do not run `gsd-mempalace-recall`, `gsd-mempalace-capture`, generic
36+
execute-wave problem capture, or `gsd-mempalace-curator`. Do not create a
37+
`MEMORY-RECALL.md` artifact. The generic handlers use the wrong server
38+
namespace, raw artifact capture, unsupported rooms, KG, diary, and tunnel
39+
semantics.
40+
41+
## Coordinator-owned recall
42+
43+
The main GSD coordinator runs the federated recall from `MEMORY.md` at most
44+
once per top-level GSD task:
45+
46+
- before discussion questions for discuss-oriented entry points;
47+
- before the first specialist for execute, verify, review, ship, quick, fast,
48+
debug, and any future entry point that has not already recalled;
49+
- before a directly invoked plan only when the current top-level task has no
50+
provenance-bearing recalled context. Inject the filtered results directly
51+
into the planner prompt; never create a separate plan-recall artifact.
52+
53+
When discussion already recalled and its verified context is carried into
54+
planning or execution, do not recall again. A resumed or compacted task keeps
55+
the same top-level ownership if the provenance-bearing context is still
56+
available.
57+
58+
Run the initial wing searches in the first tool batch after repository and
59+
contract routing is known. Fold relevant, verified facts into the discussion
60+
and owner-native `CONTEXT.md` when discussion owns that artifact. For other
61+
entry points, pass a compact memory context block directly to the relevant
62+
specialist. Include drawer IDs, owning wings, sources, and staleness caveats.
63+
64+
Subagents and GSD specialists must not recall or capture independently.
65+
66+
## Semantic closure
67+
68+
Wave completion must not write memory. Raw plans, summaries, problem lists,
69+
review reports, and verification files remain in `.planning` only.
70+
71+
Before the first final handoff that closes the top-level GSD task, the main
72+
coordinator runs the `MEMORY.md` durable capture gate. Capture only new verified
73+
semantic conclusions. A routine plan, execution, or passing verification with
74+
no durable conclusion produces no drawer.
75+
76+
A long workflow may safely defer capture until top-level closure because its
77+
verified intermediate state remains in committed GSD artifacts. Do not create
78+
partial memory merely to survive a wave boundary.
79+
80+
Corrections remain in the curator flow. A GSD ship operation must not dispatch
81+
the generic MemPalace curator.
82+
83+
## Failure behavior
84+
85+
If `solidstats_memory` is unavailable, follow the one-retry and primary-evidence
86+
fallback contract in `MEMORY.md`. GSD continues; it must not use a different
87+
palace, generic CLI, flat memory, or local outbox.

0 commit comments

Comments
 (0)