Proposal

Proposal — Reasoned architectural argument with codebase grounding + prior art

A proposal is the layer between research (paper distillation) and plan (task execution). It argues for an architectural change, a new primitive, or a design decision — grounded in (a) what the codebase already ships, (b) what sibling repos have already proposed, and (c) what the literature says. It is not a paper summary, not a task list, and not an audit.

The deliverable is a .proposals/NNN_*.md file in the repo that owns the affected surface, written in the established proposal format (see §Output format). It MUST ship with honest caveats and a fusion lineage — these are non-negotiable per the canonical proposals in katgpt-rs/.proposals/.

When to use

• The user asks "should we do X?" / "what if we Y?" / "propose a design for Z".
• A design question spans multiple primitives, repos, or feature flags and needs a reasoned argument before any plan is opened.
• A new feature wants GOAT-gate discipline but the design is still open — the proposal settles the design, the plan executes it.
• A cross-repo change touches the sync boundary, freeze/thaw, or raw↔latent bridge and needs the boundary rule reasoned through explicitly.

DO NOT use for

• Paper distillation → use the research skill. Proposal may cite a paper as prior art but does not distill it.
• Task execution → write a .plans/NNN_*.md. Proposals sketch a phased rollout; plans own the - [ ] task list.
• POC / refactor / optimization tracking → file .issues/NNN_*.md per the global rule ("Create issue at .issues for poc, proof, optimization or refactor task, do not create plan").
• Cross-repo GOAT cherry-pick audit → use the goat-audit skill.
• Bug fixes with no architectural angle.

Repos in scope (the product/distillation set — 7)

Same layout as the research and goat-audit skills. Canonical home for this list: katgpt-rs/AGENTS.md §"Repo count" (and Research 003) — it is copied here for reading convenience, so when the two disagree, AGENTS.md wins. This copy said "7-repo stack" and omitted riir-dapps from 2026-08-20 until 2026-09-01, then read "8" — correct for the one day before riir-armageddon's retirement (2026-09-02) took the set back to 7, and stale from that day until 2026-09-11. That is what a duplicated count does:

katgpt-rs          ← public engine (default target for generic primitives)
riir-ai            ← private runtime/game (cognitive, freeze/thaw, HLA, ...)
riir-chain         ← private chain (LatCal, quorum, sync-boundary bridge)
riir-neuron-db     ← private neuron-shard leaf (Pod, freeze, consolidation, AnyRAG)
riir-train         ← private training vault (training-only methods — research-only routing)
riir-game-sdk      ← private game-vocabulary facade + dev-tool workspace
                      (consumers: riir-mmorpg-examples, mmorpg-remake; vocabulary source is
                      riir-games-shared in riir-ai workspace, re-exported via facade)
riir-dapps         ← private dApp layer (game outcome → generic chain settlement;
                      added 2026-08-20 — route settlement COMPOSITION here, not
                      riir-chain, which owns only value/authority primitives)

The 7 above are the product/distillation set, not the workspace. The workspace is 18 repos with a root BOUNDARY.md — see the substrate-first skill's Step 2 for the derived enumeration. Routing targets a product repo; searching must cover all 18.

Target-repo routing rule: pick the repo that owns the surface being changed. A primitive that ships in katgpt-core → proposal in katgpt-rs/.proposals/. A runtime composition change → riir-ai/.proposals/. A sync-boundary / LatCal / commitment bridge → riir-chain/.proposals/. A shard / freeze / consolidation / AnyRAG mechanism → riir-neuron-db/.proposals/. A game-vocabulary / SDK facade / backend abstraction change → riir-game-sdk/.proposals/. If the proposal spans repos, file it in the repo that owns the primary surface and cross-reference from the others.

Pre-flight (MANDATORY before any grep)

Run all of these in parallel:

1. read_file <target_repo>/.proposals/.highwater — get the next number. If the file does not exist, list_directory <target_repo>/.proposals/ and use max(existing NNN) + 1. Always write the new highwater back after creating the proposal (per global AGENTS.md numbering discipline — numbers are monotonic and never reused).
2. list_directory .proposals/ in ALL SEVEN repos. These are the existing proposals you must not duplicate and must reason about.
3. read_file the 1–2 closest existing proposals (by filename match to the topic) — these set the bar for prose style, caveats, and rigor. Match their format.
4. If the proposal touches the sync boundary, freeze/thaw, or raw↔latent bridge — read_file the relevant section of katgpt-rs/AGENTS.md (the "Latent vs Raw Space Rules" and "Sync Boundary Rule" blocks) so the proposal reasons about domain classification correctly.

Workflow

Step 1 — Topic decomposition (one paragraph)

Write (in your own working, not into the file yet):

• The core question in one sentence. "Should we ship X to achieve Y?" not "Implement X." If you can't phrase it as a should-question, it's a plan, not a proposal.
• 3–5 key mechanism terms from the topic.
• Vocabulary translation — for each key term, brainstorm ≥2 codebase- equivalent names by asking "if we already shipped this, what would we call it?" (see §Vocabulary translation tips below). This is the same discipline as the research skill §Workflow 1.2, but scoped to the proposal topic — do NOT pull the whole standing list.

Step 2 — Focused codebase grep (the "more focus" step)

This is where the proposal skill differs from research: the grep is scoped to the proposal topic, not the full corpus. Run these in parallel, every contract repo (derived below), all four document layers + code:

DERIVE the repo set; never type it. The four-repo list this replaced (katgpt-rs riir-ai riir-chain riir-neuron-db) could not see 784 of the 2,509 documents in these layers — 31%, and .issues was the worst at 21 of 145 (85% invisible). A prior-art grep exists to stop a duplicate proposal, so a layer it cannot read is a layer it cannot clear. Measured 2026-09-01; canonical repo set lives in AGENTS.md §"Repo count", derived, never copied here.

cd /Users/katopz/git

# Layers A-D — one derived set per document layer. Substitute the layer name.
# (.proposals = strongest precedent and MUST be reasoned about per hit;
#  .research = prior art already distilled; .plans = in flight; .issues = tracked)
for layer in proposals research plans issues; do
  echo "=== .$layer ==="
  grep -rnE "<topic terms>|<codebase-equivalent terms>" \
    $(ls -d */ | while read -r d; do
        [ -f "$d/BOUNDARY.md" ] && [ -d "$d/.git" ] && [ -d "$d.$layer" ] \
          && printf '%s.%s ' "$d" "$layer"
      done)
done

# Layer E — shipped code (what actually exists today)
grep -rnE "<CamelCaseStruct>|<snake_case_fn>" \
  --include='*.rs' --exclude-dir=target --exclude-dir=.git \
  $(ls -d */ | while read -r d; do
      [ -f "$d/BOUNDARY.md" ] && [ -d "$d/.git" ] && printf '%s ' "$d"
    done)

-d "$d/.git", not -e: a git worktree has a .git file, and including one reports a single document twice. --exclude-dir=target is not cosmetic — without it Layer E spends nearly all its time inside build directories.

MANDATORY reasoning per hit (this is the user's explicit ask: "more focus and reasoning on related proposal topic when grep"). For every hit, classify it in one line:

If Layer A returns a hit that is a precedent or duplicate, the proposal is likely redundant — say so to the user before writing. Do not silently re-propose.

If Layers A–D all return zero hits, re-run with at least one more semantic angle (grep for the output behavior — "swap when X" — instead of the mechanism name — "tightness monitor"). Zero hits across all five layers is rare; the prior cause is usually vocabulary mismatch, not novelty.

Step 3 — Prior-art paper search (online)

The user's explicit second ask: "also find paper online for it too."

1. arxiv keyword search using the standing URL from global AGENTS.md: Use web search mcp to run 2–3 keyword variants (paper vocabulary AND codebase vocabulary from Step 1). One search is rarely enough — the right keyword often lives in the codebase-equivalent term set, not the user's phrasing.

2. web_search_prime for non-arxiv prior art when the topic is engineering (lock-free, deterministic replay, anti-cheat, commitment schemes) rather than ML — the relevant prior art may be in engineering blogs, RFCs, or database literature, not arxiv.

3. Fetch the 2–3 most promising hits via the jina PDF reader (https://r.jina.ai/https://arxiv.org/pdf/{ID}) or fetch for blog/RFC content. Do not fetch more than 3 — the point is grounding, not survey.

4. Distill in one paragraph each: what is the transferable insight? What does the paper do that we should NOT copy (because it's training-only, softmax-based, or violates the latent/raw boundary)? Cite these in the proposal's References section.

Honesty rule: if the prior-art search finds a paper that already proposes the exact mechanism, the proposal MUST say so in §Honest caveats. Do not re-attribute a paper's idea as our invention. The canonical example of doing this right is katgpt-rs/.proposals/004_adaptive_causal_calibration.md caveat 1: "The adaptive scheme is our invention. HydraHead supplies the causal scorer; the escalate-on-suspects mode is our design."