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

README.md

@@ -413,7 +413,8 @@ Your agent can then read plans/work items/tech debt and (with a write-scope key)
 - [x] **v0.4.3 — AI drafting (feature-flagged):** release notes & design notes drafted from delivered work, always landing in an editor
 - [x] **v0.4.4 — Asset Record (Phase A):** per-asset capabilities register with delivery lineage, graduation from resolved work items, derived known-issues/debt sections, tombstoned removals, `get_asset_record` + `graduate_work_item` MCP tools (41 total)
 - [x] **v0.4.5 — Asset Atlas** (see [`docs/specs/asset-atlas-spec.md`](docs/specs/asset-atlas-spec.md)): top-level Assets view — a live system map (products as columns, dependency edges, health/debt/activity lenses, blast-radius hover) plus grid and sortable table views
-- [ ] **v0.4.6+ — Reconciliation & round-trip engineering** (see [`docs/specs/asset-record-spec.md`](docs/specs/asset-record-spec.md)): agent reconciliation proposals, release publishing
+- [ ] **v0.4.6 — Layers & model boundaries** (see [`docs/specs/layers-and-boundaries-spec.md`](docs/specs/layers-and-boundaries-spec.md)): asset `layer` field, Atlas layer columns for single-product systems, `move_asset` model refactoring, boundary guidance in MCP
+- [ ] **v0.4.7+ — Reconciliation & round-trip engineering** (see [`docs/specs/asset-record-spec.md`](docs/specs/asset-record-spec.md)): agent reconciliation proposals, release publishing
 - [ ] AI-assisted effort estimation
 - [ ] Billing / subscription management (hosted tier, optional & feature-flagged)
 

docs/app-spec.md

@@ -4,7 +4,7 @@
 > design and rationale, see `docs/specs/design-spec-v3.md` (all phases shipped),
 > `docs/specs/releases-and-asset-history-spec.md` (Phases A–D shipped), and
 > `docs/specs/asset-record-spec.md` (Phase A shipped; Phases B–C are the next
-> tranche, v0.4.6+).
+> tranche, v0.4.7+).
 
 ### Overview
 

docs/guides/concepts.md

@@ -0,0 +1,141 @@
+# How CodePlans Thinks
+
+CodePlans has a small object model with strong opinions. Most questions about
+"where should this go?" answer themselves once you know what each object is
+*for* — not just what it's called. This guide is the conceptual map: the
+objects, the boundaries between them, and the design principles the whole tool
+keeps returning to.
+
+## The object model in one pass
+
+```
+Product ──▶ Asset ──▶ (targeted by) Code Plan ──▶ Task
+   │           │                        │
+   │           │◀── Work Item (demand, linked many-to-many to plans)
+   │           │
+   └─ Release ─┴─ stamps asset versions; groups the plans that ship together
+
+Per asset:  History (derived diary)  ·  Record (delivered reality)
+```
+
+| Object | What it is for | What it carries |
+|---|---|---|
+| **Product** | The unit you *ship, version, and grant access to* | Access control, code plans, releases, integrations targeting |
+| **Asset** | The unit you *change* — the work surface | Health, tech debt, dependencies, owners, history, record |
+| **Work item** | Demand — a feature, bug, UX issue, or debt someone wants addressed | Type, severity, status, target asset, links to plans |
+| **Code plan** | A coordinated change — the bridge from demand to execution | Tasks, target assets (with branch/PR per asset), linked work items, its release |
+| **Task** | The unit of execution | Status, assignee, effort, schedule |
+| **Release** | What ships *together* — always an explicit human act | Attached plans, per-asset version stamps, derived release notes |
+| **Record** | What an asset *is* today — delivered capabilities with receipts | Capabilities (with lineage), known issues, debt register |
+| **History** | How the asset *got here* — a derived diary | Version stamps, delivered plans, resolved items, design notes |
+
+Two of these are load-bearing in ways that are easy to miss, and they're where
+modeling questions concentrate: **products** and **assets**.
+
+## The boundary rule: products ship, assets change
+
+> **A product is something you ship, version, and grant access to as a unit.
+> An asset is something you change.**
+
+Products aren't folders. Three mechanisms hang off the product boundary:
+
+1. **Access** — visibility is scoped by product. Splitting one system into
+   many products fragments who can see what.
+2. **Plans** — every code plan belongs to one product, and can only target
+   that product's assets. Split a real system across products and a
+   cross-cutting change needs two plans where one is true.
+3. **Releases** — a release is per-product, and its whole purpose is
+   coordinating a revision *across* assets: "Platform v2.4.0 takes Auth to
+   v1.8.0 and Search to v1.2.0." Products drawn too small make coordinated
+   releases structurally impossible to express.
+
+So the test for "should this be a product?" is not "does it have a clear
+system boundary?" — most good *assets* have clear system boundaries. The test
+is: **does it ship on its own cadence, under its own version, to its own
+audience?**
+
+### Worked examples
+
+- **A single SaaS** (one app, one API, shared libraries, a datastore or
+  three): **one product**, many assets. Even at 30–40 assets, this is a
+  well-modeled instance, not an under-split one. Your releases coordinate
+  the whole surface; that's the point.
+- **A portfolio** (the demo dataset): a web platform, mobile apps with
+  app-store release trains, and a public API with its own versioning
+  contract — **three products**, because each genuinely ships on its own
+  cadence to its own audience.
+- **A monorepo** is orthogonal: one repo can host several products, and one
+  product can span several repos. Model the shipping boundary, not the
+  folder structure — assets carry `repoPath` for the folder mapping (see
+  [Modeling Monorepos](modeling-monorepos.md)).
+- **A shared internal platform** consumed by other teams *is* a product if
+  it versions and publishes on its own contract — that's an audience.
+
+When in doubt, prefer **fewer products with more assets**. Assets are cheap,
+carry all the operational texture (health, debt, dependencies, history,
+record), and — by design — can be moved and refined later. Products are
+commitments.
+
+### The second axis: layers
+
+Deep single-product systems still want internal structure — a backend API,
+a domain library, and a web app are different *kinds* of asset even though
+they ship together. That structure is a **layer**, not a product: an
+attribute of the asset (edge, frontend, backend, domain, data, infra,
+shared…) rather than a boundary around it. Layers give the
+[Asset Atlas](asset-atlas.md) its columns when the product axis degenerates
+(one product = one column), and give agents a vocabulary for structural
+modeling. The layer concept is specced in
+[`layers-and-boundaries-spec.md`](../specs/layers-and-boundaries-spec.md).
+
+## The design principles
+
+Five rules explain most of CodePlans' behavior. They're worth knowing because
+new features keep being judged against them.
+
+**1. Derived, not maintained.** Anything that must be manually kept in sync
+will rot — so wherever possible, views are *projections* of data the team
+already maintains to run its work. Asset history is projected from plans,
+work items, and releases. Release notes derive from the work items the
+attached plans delivered. The Atlas map is drawn from the asset inventory and
+dependency edges — there is deliberately no way to drag a node or pin a
+layout, because stored layout would make the map a document again, and
+documents rot.
+
+**2. Reality, not intent.** The asset Record only ever contains *delivered or
+verified* claims — a capability enters it by graduating from a resolved work
+item (with full lineage: work item → plan → release) or by being verified
+against code. Intent lives upstream in work items and PM tools and links out.
+This one rule is what keeps the record from becoming a second backlog.
+
+**3. Shipping is a human act.** Releases have an explicit lifecycle and an
+explicit "Mark Shipped" — nothing infers shipping from merges or deploy
+events. Shipped releases become read-only, because the record of what shipped
+must stay trustworthy. Corrections reopen deliberately.
+
+**4. Agents are first-class users.** Everything the UI can do to the model,
+the MCP server exposes — currently 41 tools, with the same access rules and
+guardrails enforced at the tool layer (shipped releases reject mutation,
+mirrored items reject writes to tracker-owned fields). Modeling guidance
+ships *inside* the tools (`get_modeling_guide`, and heuristics in tool
+descriptions), because for agent-driven modeling, the tool description *is*
+the UX. Agent-authored artifacts (design notes) are attributed and badged,
+never disguised as human.
+
+**5. Models are refinable.** Your first model of a system will be wrong
+somewhere, and an agent's first pass more so. The tool is built so
+refinement is cheap and history survives it: modeling operations are
+idempotent (re-running a capture or modeling pass reconciles rather than
+duplicates), records tombstone rather than delete, lineage text survives
+foreign-key changes, and structural refactoring (moving an asset to the
+right product, assigning layers) is a supported operation — not a data
+migration.
+
+## Where to go next
+
+- [The Asset Atlas](asset-atlas.md) — the system map these boundaries feed
+- [Releases & Versions](releases-and-versions.md) — the shipping boundary in practice
+- [Asset History & the Design Log](asset-history.md) — the derived diary
+- [Modeling Monorepos](modeling-monorepos.md) — repo structure vs model structure
+- [Working with AI Agents](ai-agents.md) — the MCP tool catalog and agent workflows
+- [`docs/app-spec.md`](../app-spec.md) — the authoritative current state

docs/index.html

@@ -558,6 +558,12 @@ <h3>App Spec</h3>
         <p>Complete spec of the current app: schemas, views, query/mutation API, access rules, and wiring gaps.</p>
         <div class="doc-arrow">Read → </div>
       </a>
+      <a class="doc-card" href="https://github.com/SylonZero/CodePlans/blob/master/docs/guides/concepts.md">
+        <div class="doc-tag">Guide</div>
+        <h3>How CodePlans Thinks</h3>
+        <p>The conceptual map: what products, assets, plans, and releases are each <em>for</em>, the boundary rule between them, and the five design principles behind the tool.</p>
+        <div class="doc-arrow">Read → </div>
+      </a>
       <a class="doc-card" href="https://github.com/SylonZero/CodePlans/blob/master/docs/guides/capturing-docs.md">
         <div class="doc-tag">Guide</div>
         <h3>Capturing a Docs Corpus</h3>
@@ -615,7 +621,7 @@ <h3>Releases & Asset History Spec</h3>
       <a class="doc-card" href="https://github.com/SylonZero/CodePlans/blob/master/docs/specs/asset-record-spec.md">
         <div class="doc-tag">Design</div>
         <h3>Asset Record Spec</h3>
-        <p>The capabilities register per asset shipped in v0.4.4. Next (v0.4.6+): agent-driven reconciliation against code and round-trip release publishing.</p>
+        <p>The capabilities register per asset shipped in v0.4.4. Next (v0.4.7+): agent-driven reconciliation against code and round-trip release publishing.</p>
         <div class="doc-arrow">Read → </div>
       </a>
       <a class="doc-card" href="https://github.com/SylonZero/CodePlans/blob/master/docs/specs/asset-atlas-spec.md">
@@ -624,6 +630,12 @@ <h3>Asset Atlas Spec</h3>
         <p>The map shipped in v0.4.5, and its path from picture to planning surface: lens thresholds, transitive blast radius, and plans started from the map.</p>
         <div class="doc-arrow">Read → </div>
       </a>
+      <a class="doc-card" href="https://github.com/SylonZero/CodePlans/blob/master/docs/specs/layers-and-boundaries-spec.md">
+        <div class="doc-tag">Design</div>
+        <h3>Layers &amp; Boundaries Spec</h3>
+        <p>Next (v0.4.6): the product-vs-asset rule made operational — asset layers, layer columns on the Atlas, and move_asset for refining a model.</p>
+        <div class="doc-arrow">Read → </div>
+      </a>
       <a class="doc-card" href="https://github.com/SylonZero/CodePlans/blob/master/docs/specs/mcp-server-spec.md">
         <div class="doc-tag">Design</div>
         <h3>MCP Server Spec</h3>
@@ -941,7 +953,7 @@ <h2>Current feature status</h2>
           <tr><td>AI drafting — release notes &amp; design notes (feature-flagged)</td><td><span class="status-pill done">Available</span></td></tr>
           <tr><td>Asset Record — per-asset capabilities register with delivery lineage (v0.4.4)</td><td><span class="status-pill done">Available</span></td></tr>
           <tr><td>Asset Atlas — live system map with health/debt/activity lenses (v0.4.5)</td><td><span class="status-pill done">Available</span></td></tr>
-          <tr><td>Asset Record — agent reconciliation &amp; round-trip publishing (v0.4.6+)</td><td><span class="status-pill plan">Planned</span></td></tr>
+          <tr><td>Asset Record — agent reconciliation &amp; round-trip publishing (v0.4.7+)</td><td><span class="status-pill plan">Planned</span></td></tr>
           <tr><td>AI-assisted effort estimation</td><td><span class="status-pill plan">Planned</span></td></tr>
         </tbody>
       </table>

docs/specs/asset-atlas-spec.md

@@ -178,6 +178,11 @@ shows humans. Write flows stay on the existing `create_code_plan` /
 
 Phases B–D are deliberately unversioned: they slot into the 4.x line as
 capacity allows, interleaved with the asset-record reconciliation work
-(`v0.4.6+`), which remains the strategic priority. B is small and can ride
+(`v0.4.7+`), which remains the strategic priority. B is small and can ride
 along with any release; C unlocks D and should precede it; D touches the
 plan-create flow and deserves its own release.
+
+The Atlas's second grouping axis — **layer columns** for single-product
+systems — is specced separately in `layers-and-boundaries-spec.md`
+(`v0.4.6`) together with the boundary guidance and `move_asset` it belongs
+with.

docs/specs/asset-record-spec.md

@@ -334,14 +334,14 @@ known issues/debt); resolve-time graduation prompt + backfill checklist;
 *Exit criteria: a team can build and browse a receipted capabilities register
 with zero agent involvement.*
 
-### Phase B — Reconciliation `v0.4.6`
+### Phase B — Reconciliation `v0.4.7`
 `record_proposals` + review queue UI; `propose_record_change`,
 `list_record_proposals`, `resolve_record_proposal` MCP tools; the reconcile
 guide; AI-drafted capability descriptions on graduation (flagged, Phase D
 plumbing). *Exit criteria: an agent-run reconcile pass on this repo files
 sensible proposals end-to-end.*
 
-### Phase C — Round-trip `v0.4.7`
+### Phase C — Round-trip `v0.4.8`
 Publish-to-GitHub-Releases action on shipped releases; spec-audit section in the
 reconcile guide; Record freshness surfaced on the asset header (oldest
 `verifiedAt` drives a "record last verified" hint). *Exit criteria: the litmus