laymos 0.0.9 → 0.0.11

package/skills/laymos/references/config.md

@@ -0,0 +1,96 @@
+# laymos.config.json
+
+Read this when writing or amending a config.
+
+## What does a config look like?
+
+```json
+{
+  "$schema": "https://unpkg.com/laymos/schema.json",
+  "sourceRoots": ["src"],
+  "ignoredPaths": ["src/generated"],
+  "storiesPath": "stories",
+  "layers": {
+    "cli": {
+      "paths": ["src/cli"],
+      "description": "Command surface",
+      "modules": { "src/cli": {} }
+    },
+    "domain": {
+      "paths": ["src/domain"],
+      "modules": {
+        "src/domain/orders": { "exposed": true },
+        "src/domain/catalog": { "shared": true, "exposed": true }
+      }
+    },
+    "services": {
+      "paths": ["src/services"],
+      "moduleGraphs": {
+        "store": {
+          "path": "src/services/store",
+          "modules": {
+            "index.ts": { "exposed": true },
+            "engine": {},
+            "model": {}
+          },
+          "rules": { "index.ts": ["engine"], "engine": ["model"] }
+        }
+      }
+    }
+  },
+  "layerGraphs": {
+    "architecture": {
+      "rules": {
+        "cli": ["domain"],
+        "domain": ["services"],
+        "services": []
+      }
+    }
+  }
+}
+```
+
+The `$schema` key gives editors autocomplete and validation. Trust it over prose.
+
+## What do the top-level keys do?
+
+- `sourceRoots` — the files and folders Laymos analyzes.
+- `ignoredPaths` — files and folders removed from analysis.
+- `storiesPath` — an optional folder containing the executable Story tree; it
+  is implicitly ignored by architecture analysis.
+- `layers` — each id maps to literal project-relative `paths`, plus an optional
+  `description`, and owns the modules declared within it. Layers partition every
+  supported file under `sourceRoots` and may not overlap.
+- `layers.<id>.modules` — free-form modules, keyed by project-relative path.
+  `{}` means a module nobody may import. Add `shared` and `exposed` as needed.
+- `layers.<id>.moduleGraphs` — bounded sets of modules with their own rules.
+  Read `graphs.md`.
+- `layerGraphs` — named sets of `rules`. Each rule maps a layer id to the ids
+  it may _directly_ depend on.
+
+A module is declared exactly once, either free-form in its layer or as a member
+of one module graph.
+
+## What is a layer graph?
+
+A named group of rules for one responsibility — core architecture, test
+boundaries, and so on. It is organizational, not an enforcement boundary.
+
+All graphs combine into one effective graph. That combined graph is default-deny,
+transitive, and must be acyclic. A project with no permitted cross-layer imports
+declares `"layerGraphs": {}`.
+
+Declare direct edges only. Transitive reach follows.
+
+A layer graph _hosts_ the layers it declares rules from and _reaches_ the layers
+it names as targets. Rules point to the real target layer. Each referenced layer
+has one configured host; declaration order breaks ties. The view groups all
+unreferenced layers under `other-layers`.
+
+## Where are paths resolved from?
+
+The config file's own directory. `--config` defaults to `./laymos.config.json`.
+
+## Does consuming the config need a dependency?
+
+No. It is plain JSON. Any tool can read it.

package/skills/laymos/references/design.md

@@ -0,0 +1,166 @@
+# Module design
+
+Read this when choosing boundaries, splitting or combining modules, declaring a
+module graph, or designing orchestration. Concepts stay short; scenarios decide.
+
+## Module boundary
+
+A module owns one coherent capability and the design decisions most likely to
+change behind it. Its door reveals the promise, not representation or sequence.
+
+**Where do I split?**
+Split where a part has its own promise, change reason, and independently testable door.
+
+**Should processing steps become modules?**
+Only when they hide independent decisions; runtime order alone is not a boundary.
+
+**Where do data and its operations live?**
+Together, behind the module that hides the representation.
+
+**What if history shows two parts always change together?**
+Treat co-change as evidence to combine them, never as the decision by itself.
+
+## Deep module
+
+A deep module absorbs substantially more complexity than its door exposes while
+keeping its interior navigable. A narrow door does not excuse a tangled interior.
+
+**How should a reader enter a directory module?**
+Through its door, then its execution story; use the `deep-module` skill for shape.
+
+**May a small capability be a module?**
+Yes, when it hides a real policy behind a stable concept.
+
+**Do several functions need a namespace object?**
+Use one for a coherent caller concept; grouping alone does not create depth.
+
+**The door is tiny but the orchestrator is huge. Is it deep?**
+No. Group its independent concerns behind named internal capabilities.
+
+## Readable execution story
+
+An exposed module's `<name>.ts` fulfils its promise through named collaborators.
+A reader follows one branch at a time while holding two or three concepts.
+
+**The orchestrator handles more than three concepts at once. What now?**
+Group related steps behind a named internal capability.
+
+**The module has more than five direct collaborators. What now?**
+Review the story and group its concerns; above ten, presume the boundary is wrong.
+
+**Do those counts decide the boundary?**
+No. They trigger review; capability, change, and cognitive load decide.
+
+**Is file length the test?**
+No. Test the number of responsibilities, state owners, and policy boundaries.
+
+**Must the story be chronological?**
+No. Event-driven code names each interaction and delegates its behavior.
+
+## Split and combine
+
+Split independently changing promises; combine coordination callers should not
+manage. Private children may remain when they make the parent story clearer.
+
+**Two modules require callers to know their order or shared state. What now?**
+Combine them behind one useful operation.
+
+**Two modules depend on each other. What now?**
+Re-cut the responsibilities or split one into lower and higher parts.
+
+**A folder is large. Should I split it?**
+Only when the new parts pass the promise, change, and independent-door tests.
+
+**Several files serve one private responsibility. What now?**
+Make a nested deep module; configure a graph only when its dependencies matter.
+
+## Module Graph
+
+A Module Graph makes the responsibility and dependency story of one large
+capability explicit. It normally has one exposed facade and private members.
+
+**When does a module become a Module Graph?**
+When two or more internal capabilities stand alone and their dependency direction matters.
+
+**What must connect to the facade?**
+Every private member must lie on a path from at least one exposed member.
+
+**May a graph expose several members?**
+Only for independently consumed doors hiding the same decision, such as providers.
+
+**A member is disconnected. What now?**
+Make it a separate module or graph, unless its independent door explains the exception.
+
+**Does a private member need `index.ts`?**
+Yes. Graph peers use its door; `exposed` only controls access from other layers.
+
+**Should graph rules mirror runtime calls?**
+No. Rules express correctness dependencies, not execution chronology.
+
+**When should A depend on B?**
+When B simplifies A, B stands without A, and A needs B to fulfil its promise.
+
+## Orchestrator
+
+An orchestrator is a module that adds workflow policy while coordinating lower
+capabilities. It is a relative role, not a configured kind or mandatory layer.
+
+**What belongs in an orchestrator?**
+Workflow sequencing, interaction transitions, failure policy, lifetime, and composition.
+
+**What stays below it?**
+The domain decisions and detailed work owned by lower capabilities.
+
+**May it import every transitively reachable module?**
+Prefer the nearest capability that owns the behavior; permission is not encouragement.
+
+**It only re-exports lower modules. Is it an orchestrator?**
+No. It adds no broader capability and should usually disappear.
+
+**Wiring obscures the workflow. What now?**
+Separate the composition root that constructs dependencies from the orchestrator.
+
+**Where do concrete implementations meet?**
+At the entry or composition root; the orchestrator receives capability doors.
+
+## Interactive module
+
+An interactive module owns one path from user intent through transition and
+derived state to rendering. Views emit intent and render results.
+
+**Two views implement the same focus or visibility policy. What now?**
+Move the policy to one pure owner and let both views consume it.
+
+**One state value means different things in different modes. What now?**
+Split it or model the alternatives as an explicit union.
+
+**One action resets several unrelated state values. What now?**
+Create a named transition in one interaction model.
+
+**A primary action crosses several policy owners. What now?**
+Reduce it to door, coordinator, and one focused capability path.
+
+## Layer composition
+
+A layer groups modules with the same dependency rights, not necessarily one
+capability. Responsibility broadens upward as modules compose lower promises.
+
+**Must a layer expose one facade?**
+No. It may expose several independent capabilities; a Module Graph defaults to one.
+
+**What should the outermost module expose?**
+The smallest useful interface for the system's external consumer.
+
+**What must a higher module add?**
+A broader capability through workflow policy, never a pass-through re-export.
+
+**What is at the bottom?**
+Leaf capabilities depend on nothing; Laymos reports this observed shape as Terminal.
+
+## Foundations
+
+[Parnas 1972](https://doi.org/10.1145/361598.361623): information hiding.
+[Parnas 1978](https://ocw.mit.edu/courses/16-355j-software-engineering-concepts-fall-2005/1c68d0f98909a126ec5eb6a0ff358ec7_parnas_ease.pdf):
+uses hierarchies. [Parnas, Clements, and Weiss](https://doi.org/10.1109/TSE.1985.232209):
+module versus runtime structure. [Ousterhout](https://web.stanford.edu/~ouster/CS349W/lectures/abstraction.html):
+deep modules.

package/skills/laymos/references/graphs.md

@@ -0,0 +1,85 @@
+# Module graphs
+
+Read this when one capability outgrows a single module.
+Read `design.md` first when deciding whether the graph is the right boundary.
+
+## What is a module graph?
+
+A named, bounded set of modules inside one layer, rooted at a directory,
+whose connections are declared as rules. It describes one capability whose
+parts need their own dependency direction — an interior the layer should not see.
+
+A module graph is not a module. It owns no files directly, has no `index.ts`
+of its own, and cannot contain another module graph.
+
+Default to one exposed facade and a dependency path from it to every private
+member. Several exposed doors are a design exception, not a config violation.
+
+## What does it look like?
+
+```json
+"orchestrator": {
+  "paths": ["src/orchestrator"],
+  "moduleGraphs": {
+    "project-orchestration": {
+      "description": "Loads a project once and derives every view of it.",
+      "path": "src/orchestrator",
+      "modules": {
+        "load-project": {},
+        "analyze-project": { "exposed": true },
+        "inspect": { "exposed": true }
+      },
+      "rules": {
+        "analyze-project": ["load-project"],
+        "inspect": ["analyze-project", "load-project"]
+      }
+    }
+  }
+}
+```
+
+Member keys are relative to `path`. Rules use those keys.
+
+## What are the invariants?
+
+- At least two members. A one-member graph is a module.
+- At least one exposed member. A graph nobody can reach means nothing.
+- Graph ids are unique across the whole project, not merely within one layer.
+- Every file under `path` belongs to a member — module graph coverage.
+  A file beside member directories must itself be a declared root File Module.
+- No member may be `shared`. Sharing is layer-wide and would let a peer bypass
+  the rules; declare anything that must be shared outside the graph.
+- Rules must be acyclic, and reference only this graph's members.
+
+## What may a member import?
+
+Its own graph's members where a rule permits, free-form shared modules in its
+layer, and exposed modules in layers it may reach. It may never import another
+graph's member in the same layer.
+
+Rules are the only way members connect, and a member no rule reaches and nothing
+exposes is dead.
+
+## How is this different from a layer graph?
+
+Both are DAGs of nodes with declared rights, but they invert in three ways:
+
+|              | layer graph                      | module graph                             |
+| ------------ | -------------------------------- | ---------------------------------------- |
+| overlap      | graphs share layers; rules union | disjoint units; never unioned            |
+| transitivity | transitive                       | **not** transitive — only declared edges |
+| cycles       | checked over the union           | checked per graph                        |
+
+Non-transitivity is deliberate. A graph is small enough that stating each edge is
+cheap, and transitivity would silently permit imports across the very interior
+the graph exists to describe.
+
+## When is a module graph wrong?
+
+- The members have no edges between them → they are independent peers.
+  Leave them flat.
+- A member wants an interior graph of its own → it should have been a layer.
+- Two graphs want to reach into each other → extract the common part up to the
+  layer as a free-form shared module.
+- Members mirror runtime steps but hide no independent decisions → keep the
+  execution story inside one module.

package/skills/laymos/references/visibility.md

@@ -0,0 +1,60 @@
+# Module visibility
+
+Read this when deciding who may import a module.
+
+## What are the two flags?
+
+Every module declares two booleans, both defaulting to `false`.
+They open layer-wide and cross-layer access; module graph rules separately grant
+member-to-member access.
+
+- `shared` — peers in the same layer may import it.
+- `exposed` — other layers may import it, subject to layer rules.
+
+That is the whole vocabulary. There is no `kind`, and no `subpaths`.
+
+| you want                                       | declare                                |
+| ---------------------------------------------- | -------------------------------------- |
+| a layer's public capability                    | `exposed`                              |
+| a layer-internal helper its peers share        | `shared`                               |
+| both                                           | `shared` and `exposed`                 |
+| a graph-private capability                     | neither; grant graph rules to its door |
+| a host-started root — a CLI, a route, a worker | neither                                |
+
+## What follows from the flags?
+
+A directory module needs an `index.ts` when `shared || exposed`, and every
+directory module graph member needs one so permitted peers use its door. A
+free-form module nobody may import needs no door and follows its host convention.
+
+An unimported free-form private module is an intentional root when its layer has
+no inbound rules — that is where hosts enter. In a module graph, a private member
+with no incoming graph rule is dead. Laymos reports either invalid case.
+
+## When is shared wrong?
+
+Shared exists for a genuine layer-wide capability. Match the symptom, take the verdict.
+
+- No same-layer user → it is not shared. Drop the flag.
+  Laymos reports this as an `unused-shared` violation.
+- Exactly one same-layer user → either that user owns the code, or the two
+  modules should merge. Check before keeping shared.
+- Several peers forming a chain → they are one capability with an interior.
+  Make them a module graph, where each edge is declared.
+- A shared module importing another shared module → merge them, or move the
+  lower one into a layer with the right dependency policy.
+
+Each verdict demands a stated reason. None of them decides the design alone.
+
+## What if peers need common code?
+
+Test three options before adding shared.
+
+1. One peer already owns the capability. Let it own it.
+2. The peers are one capability split in two. Merge them, or make them a graph.
+3. The capability is stable and lower. Move it to a layer the peers may reach.
+
+## When do I reach for a module graph?
+
+When one capability is too large for one module and its parts need declared
+connections. Read `graphs.md`.

package/skills/to-laymos/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: to-laymos
+description: Turn a requirement into a high-level Laymos architecture proposal.
+disable-model-invocation: true
+---
+
+# to-laymos
+
+Describe how the requirement should fit the project's architecture. Stop after
+the proposal; implementation is a separate task.
+
+Read the `/laymos` skill and
+[`../laymos/references/design.md`](../laymos/references/design.md) completely. Inspect
+`laymos.config.json` and the doors of the modules the requirement changes or
+depends on. Read the applicable `CONTEXT.md`; use `CONTEXT-MAP.md` to find it
+when the project has multiple contexts. Ask only when two answers would produce
+different boundaries.
+
+For each part of the requirement, decide whether to extend a module, add a
+module, or form a Module Graph. Prefer the smallest change whose boundaries
+follow the module, graph, and orchestration guidance in `design.md`.
+
+Describe only the modules and Module Graphs that the requirement adds or
+changes. For each one, explain what it is, what useful behavior it exposes, and
+how it helps the requirement. Mention its layer only when that helps explain
+its place in the architecture.
+
+Write the proposal in ASD-STE100 Simplified Technical English. Treat the
+`CONTEXT.md` Language entries as the approved project vocabulary. If no context
+file applies, use the terms already established in the project.
+
+## Proposal
+
+```markdown
+## The change
+
+<What becomes possible and the high-level architectural approach.>
+
+## Modules
+
+### `<full module or graph path>`
+
+<In one short, conversational paragraph, explain what this module is, what it
+lets callers do, and how it helps complete the requirement. Describe a Module
+Graph as one capability. Name its facade and private modules only when they make
+that capability easier to understand.>
+
+## How the modules connect
+
+<Explain the dependency direction and the end-to-end flow in simple terms.
+Mention an unchanged module only when the flow cannot be understood without it.>
+
+## Open questions
+
+<Only unresolved choices that would change the architecture. Omit when empty.>
+```
+
+Keep it high-level and conversational. Explain the module promises and the
+connections between them. Do not list files, implementation steps, tests, call
+signatures, status labels, or unrelated architecture.