RFC-009 — Separating Stack Documentation from Agent Configuration in meta/

1. Summary

Split the context/ Area inside meta/ along a clean criterion line:

• *metadocs`*— normative documentation of the Stack: RFCs, vocabulary,

  Area catalog, deep-dives per module, *pecs*(testable rules), and *olicies*(behavioral guidance). Read by humans and AI assistants as reference. Independent of any specific agent or tooling.

• *metacontext`*— operational configuration of the agent

  infrastructure: Claude Code settings, slash commands, hooks, MCP, local credentials, infrastructure catalog, registries, the CLAUDE.md entry point, reminders.

The relocation moves context/specs/ to meta/docs/stack/specs/ and context/policies/ to meta/docs/stack/policies/. CLAUDE.md path references update accordingly.

2. Problem

The context/ directory accumulated two genuinely distinct kinds of artifact:

Type A — Agent infrastructure configuration

Files read by the Claude Code harness or by tooling subsystems to operate. They are tied to a specific agent and tooling stack; replacing the harness would replace these.

Type B — Stack normative documentation

Files read by humans and AI assistants as the Stack's own normative reference. They describe how to build things in the Koder Stack and would still be valid in a world without Claude Code.

Mixing the two violates the singlecriterion rule (RFC004). The criteria that govern Type A and Type B are fundamentally different:

• Type A criterion: operational artifact for agent infra.
• Type B criterion: normative artifact about the Stack itself.

The Linnaean rule says one criterion per level. context/ was treating two criteria as one.

3. Proposed structure

meta/                              L1 Domain — consumed by reading
├── brand/                         L2 — visual identity
├── docs/                          L2 — Stack normative documentation
│   ├── stack/
│   │   ├── rfcs/                  ← design decisions (this RFC and siblings)
│   │   ├── vocabulary.md          ← canonical concept reference
│   │   ├── areas.md               ← Area catalog
│   │   ├── module-catalog.md      ← module index
│   │   ├── modules/               ← per-module deep-dives
│   │   ├── engine-product-pattern.md
│   │   ├── specs/                 ← L5 NORMATIVE rules (moved from context/)
│   │   └── policies/              ← L5 BEHAVIORAL guidance (moved from context/)
│   └── (room for future doc collections: legal/, research/, …)
├── sites/                         L2 — web presence (RFC-006 §5)
└── context/                       L2 — agent infrastructure configuration
    ├── claude/                    ← settings.json, .mcp.json, hooks/
    ├── commands/                  ← slash commands
    ├── credentials/               ← local secrets
    ├── infrastructure/            ← server/service/account catalog
    ├── registries/                ← accumulating state
    ├── CLAUDE.md                  ← entry point (symlinked to ~/.claude/)
    └── reminders.md

Why specs and policies belong under docs/stack/

docs/stack/ already houses the conceptual reference of the Stack — RFCs that decide what the Stack is, vocabulary that names *what things are called, deep-dives that explain *what each module does. Specs encode the *estable rules*that those decisions imply. Policies encode the *ehavioral guidance*that those decisions imply. They are the same kind of artifact at different levels of formality:

All three are documentation of the Stack, read by humans and AIs as reference. They belong together.

Why CLAUDE.md stays in context/

CLAUDE.md is the harness entry point — Claude Code loads it from a fixed location (~/.claude/CLAUDE.md, currently a symlink into the monorepo). It is a configuration interface between the agent and the Stack docs:

• It references specs and policies (now at meta/docs/stack/specs/...).
• It does not contain normative content beyond the references and a few

  global rules.

• Its presence is dictated by the agent harness, not by the Stack

  taxonomy.

Treating CLAUDE.md as agent configuration (Type A) keeps the boundary clean: CLAUDE.md is the bridge, not the documentation itself.

4. Migration

4.1 Path moves

These can be executed as git mv operations.

4.2 Reference updates

The CLAUDE.md and any docs/specs that cross-reference each other need their paths updated. Examples:

• CLAUDE.md "Specs (normativas, testáveis — context/specs/)" → "Specs

  (normativas, testáveis — meta/docs/stack/specs/)".

• CLAUDE.md trigger table entries that point to specs/landing-pages/...

  resolve relative to the harness root; the on-disk location changes but the relative path used in CLAUDE.md may stay the same if symlinks are preserved.

4.3 Symlinks unchanged

The ~/.claude/ symlinks remain pointing into the monorepo:

The harness sees the same files; only the canonical-store location moves.

4.4 Tooling updates

• /k-context (the slash command that scans the context dir) needs to

  scan meta/context/ and meta/docs/stack/ separately, with appropriate semantics for each.

• /k-housekeep audits — any path-keyed audit that walks context/specs/

  must walk meta/docs/stack/specs/ after migration.

• /k-evolve, /k-parity, /k-test are unaffected because they operate

  on Sectors, not on the meta tree.

5. Implications for L5 (RFC-008)

RFC-008 §5 already indexes specs and policies at their new locations:

• §5.1 references specs/binaries-and-cli/naming.kmd,

  `specs/landing-pages