Concepts guide ("How CodePlans Thinks") + layers-and-boundaries spec

[SylonZero]

Docs-only PR ahead of the v0.4.6 implementation.

New guide — docs/guides/concepts.md

"How CodePlans Thinks": the conceptual map for developers —

• what each object is for (not just what it's called), with the object model in one pass;
• the load-bearing product boundary (access, plans, and releases all hang off it — which is why "each subsystem = a product" breaks coordinated releases);
• the normative rule: products ship, assets change — with worked examples (single SaaS = one product with many assets; portfolio = several products; monorepos are orthogonal; internal platforms with their own contract are products);
• the layer axis as the second dimension inside a product;
• the five design principles: derived not maintained, reality not intent, shipping is a human act, agents are first-class users, models are refinable.

New spec — docs/specs/layers-and-boundaries-spec.md (proposed, v0.4.6)

• assets.layer: free text with a conventional taxonomy (edge · frontend · backend · domain · data · infra · shared) and display-time defaults from asset type — existing instances get a layered map with zero migration; defaults are never written to rows.
• Atlas layer columns: a "Columns: Product | Layer" toggle, auto-switching to layers when a single product is in scope (fixing the single-column degenerate case); taxonomy-ordered columns so edges mostly point one way.
• move_asset with defined semantics: blocked by draft/active plans (listed for retargeting), work items follow the asset, history is history (stamps, completed-plan links, capabilities, lineage all preserved).
• MCP: layer on create/update_asset, new move_asset tool (→42), a Boundaries section in get_modeling_guide, and one-line boundary heuristics in create_product/create_asset descriptions.
• Explicit non-goals: layers never carry permissions (that would make them products with extra steps); no heuristic auto-writes of layers.

Also

• Reconciliation phases renumbered to v0.4.7/v0.4.8 across the record spec, README roadmap, app-spec, and docs site.
• Doc cards for both new documents; the Atlas spec cross-references the layer axis.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y7FhGxYjnJHJ7m9MpH2dgJ

---

Generated by Claude Code