@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/references/agent-orchestration.md

@@ -0,0 +1,221 @@
+# Agent Orchestration
+
+Use this reference when a workflow benefits from isolated context, parallel work, or independent verification.
+
+Load `references/context-firewall.md` first when the delegated work may involve verbose logs, snapshots, generated reports, external research, or broad source inspection.
+
+Load `references/subagent-design.md` only when designing or revising reusable subagent roles, adding a new role to this file, or turning repeated delegated work into a stable role charter. Do not load it for ordinary one-off delegation.
+
+## Principle
+
+The main agent is the orchestrator. It owns:
+
+- workflow routing
+- memory recall and persistence
+- user questions and trade-off synthesis
+- conversation feedback status updates
+- final Evidence Gate
+- final user-facing report
+
+Subagents do bounded work only. Do not delegate everything.
+
+## Delegation Gates
+
+Delegate only when all base requirements are true and at least one dispatch trigger is true.
+
+Base requirements:
+
+- The task is isolated, concrete, and has a clear output contract.
+- The subagent can make progress without full conversation history.
+- The work is parallelizable, context-heavy, or useful as independent verification.
+- The task has deterministic sensors or concrete artifact checks.
+- The write set is disjoint from other active agents when edits are allowed.
+
+Dispatch triggers:
+
+- User explicitly asks for subagents, delegation, parallel agent work, or independent review.
+- The scope has >=2 independent slices with disjoint write sets.
+- The scope touches >10 files, >500 LOC, or >2 modules.
+- A high/critical audit finding needs independent verification.
+- Verbose context would exceed the context-firewall thresholds and can be summarized independently.
+
+Keep local when any are true:
+
+- The next main-agent step is blocked on the result.
+- The task needs unresolved user intent.
+- The work is tightly coupled across many files without a clear owner.
+- The subagent would only duplicate main-agent thinking.
+- Platform policy does not permit spawning an agent for this request.
+
+## Plan Challenge Exception
+
+Plan Challenge `plan-critic` is a standing policy exception to the normal dispatch triggers after a concrete plan exists. Always attempt a read-only `massa-ai-plan-critic` for both `depth: lite` and `depth: full` when subagent tooling is available and platform policy permits spawning. Normal base requirements still matter for packet quality: the critique must be bounded, read-only, and concrete, but it does not need to satisfy the ordinary dispatch triggers such as file count, module count, or explicit user delegation.
+
+For all other roles, preserve the normal delegation gates above.
+
+## Name Resolution
+
+Charters live at `skills/agents/<role>/SKILL.md`. Hosts register every charter
+under the prefixed name `massa-ai-<role>` (Claude, Codex, Cursor, OpenCode all
+use that prefix; `scripts/generate-subagent-artifacts.ts` emits it).
+
+- **Dispatch under the prefixed host name**, never the bare role name. A bare
+  `subagent_type` does not resolve on any supported host.
+- The bare role name is the registry key: use it in memory tags, capability
+  packets, and prose.
+- Every dispatch block in a workflow carries the prefixed name inline so
+  dispatch never depends on this file being loaded.
+
+If the named agent is unavailable for any reason — not registered, plugin not
+installed, spawning forbidden by platform policy, or the host returns an unknown
+`subagent_type` — do not retry under another name and do not invent one. Run the
+delegated scope locally against the same output contract, and report the skipped
+delegation with its reason in the Evidence Gate.
+
+## Roles
+
+Use the role names in prompts and memory tags; use the host agent names to
+dispatch.
+
+Before adding a new reusable role, load `references/subagent-design.md` and write a bounded role charter. For one-off tasks, use an existing role plus the prompt contract below instead of inventing a new role.
+
+| Role | Host agent name | Use For | Read/Write | Charter |
+|---|---|---|---|---|
+| `investigator` | `massa-ai-investigator` | Trace code paths, find entry points, summarize current behavior | read-only | `skills/agents/investigator/SKILL.md` |
+| `navigator` | `massa-ai-navigator` | Answer "where is X / who calls Y" from the massa-ai index before reading files | read-only | `skills/agents/navigator/SKILL.md` |
+| `implementer` → `builder` | `massa-ai-builder` | Execute one atomic task with a disjoint write set | write | `skills/agents/builder/SKILL.md` |
+| `verifier` → `verification-agent` | `massa-ai-verification-agent` | Independently run sensors and inspect whether claims hold | read-only | `skills/agents/verification-agent/SKILL.md` |
+| `domain-mapper` → `architecture-specialist` | `massa-ai-architecture-specialist` | Identify subdomains, bounded contexts, language conflicts, cohesion | read-only | `skills/agents/architecture-specialist/SKILL.md` (lens: `domain`) |
+| `coupling-auditor` → `architecture-specialist` | `massa-ai-architecture-specialist` | Analyze strength, distance, volatility, and risky dependencies | read-only | `skills/agents/architecture-specialist/SKILL.md` (lens: `coupling`) |
+| `deepening-architect` → `architecture-specialist` | `massa-ai-architecture-specialist` | Find shallow modules and deepening opportunities | read-only | `skills/agents/architecture-specialist/SKILL.md` (lens: `deepening`) |
+| `audit-specialist` | `massa-ai-audit-specialist` | Findings-only audit through one selected `lens` | read-only | `skills/agents/audit-specialist/SKILL.md` |
+| `plan-critic` | `massa-ai-plan-critic` | Stress-test a constructed plan using The Fool mode and return bounded critique | read-only | `skills/agents/plan-critic/SKILL.md` |
+| `furps-analyst` | `massa-ai-furps-analyst` | Analyze one FURPS+ dimension of a PRD/ADR against the checklist and return structured findings | read-only | `skills/agents/furps-analyst/SKILL.md` |
+
+The remaining charters — `planner`, `reviewer`, `context-curator`,
+`requirements-analyst`, `test-engineer`, `documentation-agent`,
+`mobile-specialist` — follow the same `massa-ai-<role>` convention and are
+listed in the Agent Table of `skills/AGENTS.md`.
+
+**Role mapping:** `investigator`→`investigator` (identical); `implementer`→`builder` (renamed); `verifier`→`verification-agent` (renamed, centralizes Verification Ladder); `domain-mapper`+`coupling-auditor`+`deepening-architect`→`architecture-specialist` (three roles folded into one specialist; the `lens` input field selects the sub-mode). Workflows dispatch the new agent names via named dispatch blocks; the old role names above are kept for traceability only.
+
+## Capability Packet
+
+When dispatching a subagent, send a compact capability packet rather than a loose instruction. Include:
+
+- role and purpose for this workflow
+- trigger: why delegation is justified now
+- exact scope: files, modules, diff, report finding, task IDs, or artifact
+- permissions: read-only or write with disjoint ownership
+- inputs: recalled facts, source pointers, constraints, and exclusions
+- sensors: expected commands or concrete checks
+- output: the exact output contract
+- firewall: raw logs, diffs, snapshots, reports, or research that must be summarized
+- memory boundary: whether the subagent may suggest memories and who persists them
+- exact next step: what the main agent should do with the result
+
+## Prompt Contract
+
+Every delegated task must include:
+
+- exact `projectId`
+- exact parent `workflowSessionId` or child session tag
+- workflow name
+- role name
+- scope and file/module ownership
+- facts already known
+- what to avoid redoing
+- allowed tools or mutation level
+- deterministic validation expected
+- context-firewall limit: what raw output must not be returned
+- skipped-check policy and how to report unavailable sensors
+- memory boundary: whether to suggest memories only or write none
+- exact output format
+
+## Output Contract
+
+Every subagent returns:
+
+- Status: `Complete`, `Blocked`, or `Partial`
+- Scope checked or files changed
+- Evidence: command result, static finding, source location, or artifact inspected
+- Findings or implementation summary
+- Risks and skipped checks
+- Exact next step
+
+Subagents must summarize verbose research, logs, snapshots, diffs, search output,
+and transcripts. The main agent should receive only evidence, findings, risk,
+skipped checks, memory suggestions when allowed, and the next step, not raw dumps.
+
+## Conversation Feedback
+
+Use `references/conversation-feedback.md` when subagent lifecycle visibility would help the user understand what is running. Keep status updates to 1-2 human-readable lines.
+
+Use these labels for delegated work:
+
+- `Agent Started` when a role is launched with scope and permission mode.
+- `Agent Running` when waiting on a long-running role or reporting its current bounded task.
+- `Agent Done` when the role returns usable evidence, findings, implementation, or verification.
+- `Agent Blocked` when the role cannot complete its assigned scope.
+
+Do not expose raw subagent prompts, raw logs, private reasoning, or full output dumps in feedback lines.
+
+Example:
+
+```md
+🤖 [Agent Started] Verifier is checking the docs-only change set. Scope: massa-ai references and README.
+🤖 [Agent Done] Verifier found no stale references. Skipped checks: none.
+```
+
+## Plan-Critic Contract
+
+Dispatch `massa-ai-plan-critic` only after a concrete plan exists. Dispatch it with the capability packet above and the standard output contract. The subagent receives the plan, scope, constraints, compact recalled facts/evidence, selected depth, selected The Fool mode only for full gates, known risks, verification recipe, parent identifiers, and context-firewall limits. It never receives full conversation context.
+
+For `depth: lite`, the packet uses the low-risk checklist and does not include The Fool mode references. It returns:
+
+- strongest low-risk challenges
+- assumption most likely to fail
+- deterministic check that would falsify success
+- high-risk or broad-scope trigger found, if any
+- `escalate_to_full: true|false`
+- escalation reason
+
+For `depth: full`, or after lite escalation, the main agent selects the mode, loads the relevant The Fool references, and dispatches a full packet. It returns:
+
+- selected mode
+- steelmanned thesis
+- 3-5 strongest challenges
+- severity: `critical`, `high`, `medium`, or `low`
+- affected plan section
+- evidence gap or assumption at risk
+- required revision or accepted-risk framing
+- confidence impact
+- exact next step
+
+The main agent owns final synthesis and applies the canonical Plan Challenge
+Policy: the `<!-- massa-ai:bootstrap -->` block installed as `<host>/AGENTS.md`,
+whose single source is `skills/AGENTS.md` in the product repo.
+
+## Memory Rules
+
+- Main agent persists durable conclusions after synthesis.
+- Subagents may suggest memory content but should not create broad project memories unless explicitly assigned.
+- Use tags such as `agent:verifier` or `agent:domain-mapper` only when they improve retrieval.
+- Do not persist one-off subagent chatter.
+
+## Synapse Isolation
+
+For delegated tasks that expect repeated searches:
+
+- create one ephemeral Synapse session per subagent
+- pass only that agent's `synapseSessionId` to its `search` calls
+- keep parent/child `workflowSessionId` values in memory tags and output packets
+- never share one Synapse session across concurrent agents
+- allow stateless fallback when session creation or adapter translation fails
+
+## Guardrails
+
+- No self-evaluation: claims need deterministic sensors or concrete source evidence.
+- No hidden scope expansion: subagents must not improve adjacent code.
+- No context dragging: send only task-specific source pointers and constraints, and receive compact summaries only.
+- No conflicting writes: parallel implementers need disjoint files or worktrees.

package/skills/massa-ai/references/architecture-coupling-lens.md

@@ -0,0 +1,239 @@
+# Architecture Coupling Lens
+
+Use this detail reference when an architecture audit or execution task needs dependency health, dependency direction, integration cost, or coupling reduction.
+
+## Contents
+
+- Core Model
+- Dependency Graph
+- Strength Levels
+- Symmetric Coupling
+- Connascence Ladder
+- Distance Levels
+- Volatility Signals
+- Balance Table
+- Quantitative Anchors
+- Pattern Strength Action Lookup
+- Static Leads
+- Positive Patterns
+- Fix Direction
+
+## Core Model
+
+Analyze coupling through three dimensions:
+
+- Strength: what knowledge or behavior is shared
+- Distance: how far apart the coupled modules are
+- Volatility: how likely either side is to change
+
+High strength is not automatically bad. Strong coupling can be cohesive when modules are close and change together. Risk rises when strong coupling crosses distance and volatile business behavior.
+
+## Dependency Graph
+
+Map directed dependencies:
+
+```text
+A -> B means A depends on B.
+B is upstream and exposes knowledge to A.
+A is downstream and absorbs upstream changes.
+```
+
+For each relevant edge, record:
+
+- caller/downstream module
+- callee/upstream module
+- dependency kind: import, DI, HTTP/gRPC, queue/event, shared DB, generated client, shared schema, test fixture
+- exported surface or contract used
+- whether the dependency crosses package, bounded context, service, team, or external-system distance
+
+## Strength Levels
+
+Classify by strongest evidence:
+
+- Intrusive: downstream reads internals not designed for integration, such as private fields, another service DB, internal config/file shape, reflection, monkey patching, or undocumented generated artifacts.
+- Functional: modules must coordinate behavior, order, transaction, duplicated business rule, deployment, or state transitions.
+- Model: upstream exposes internal domain model, enum meanings, field names, value semantics, tuple positions, or persistence schema as integration surface.
+- Contract: upstream exposes integration-specific DTO, event, schema, facade, published language, or versioned protocol that hides internals.
+
+### Symmetric Coupling
+
+A sub-degree of Functional coupling with no import edge: two modules
+independently encode the same business rule, so changing the rule requires
+editing both. It is the defect static import analysis most often misses.
+
+Detection signals:
+
+- the same predicate, threshold, mapping, or validation duplicated across modules
+- comments like "update X when changing Y" or "keep in sync with"
+- two validators, formatters, or mappers that must agree but share no type
+- a bug fixed in one place that later recurs in the other
+
+Treat as Functional strength regardless of distance. The fix is to extract the
+shared rule to one owned location and reference it, not to add an import edge.
+
+## Connascence Ladder
+
+Map the shared knowledge to a rung, weakest (most tolerable) to strongest.
+Lower rungs are cheaper to change; higher rungs amplify distance and volatility.
+
+| Rung | Connascence | Meaning |
+|---|---|---|
+| 1 | Name | depends only on an identifier; a rename propagates |
+| 2 | Type | depends on a type or shape |
+| 3 | Meaning | depends on an agreed value, convention, or format (magic numbers, date formats) |
+| 4 | Position | depends on argument, field, or tuple order |
+| 5 | Algorithm | depends on call order, timing, transaction, or duplicated logic |
+
+Rungs 4-5 map to Functional/Intrusive strength; rungs 1-2 map to Contract
+strength. Use the rung to justify the Fix Direction: collapse higher rungs into
+named contracts or shared owned logic before widening distance.
+
+## Distance Levels
+
+Use the closest common ownership point:
+
+- same function or class
+- same package or vertical slice
+- same module/library
+- different app/service
+- external system or different team
+
+Increase distance when deployment, ownership, or team coordination is separate.
+
+### Distance Scorecard
+
+| Layer pair | Distance |
+|---|---|
+| same function or class | 0 |
+| same package or vertical slice | 1 |
+| same module or library | 2 |
+| different app or service | 3 |
+| external system or different team | 4 |
+
+Conway's-Law bump: when the two sides are owned by different teams (even inside
+one service), add 1 to the distance — coordination cost makes the coupling
+behave like the next distance tier.
+
+## Volatility Signals
+
+Prefer real evidence:
+
+- Core or evolving business subdomain
+- recent commits or co-change patterns
+- TODO/FIXME clusters around behavior
+- multiple API versions or migration code
+- fragile tests, recurring regressions, or repeated audit findings
+- user-provided roadmap pressure
+
+If history is unavailable, mark volatility as inferred and lower confidence.
+
+Turn "recent commits" into measured co-change (volatility by file):
+
+```bash
+git log --since='3 months ago' --name-only --pretty=format: \
+  | grep -v '^$' | sort | uniq -c | sort -rn | head -30
+```
+
+Co-change is evidence: files that move together repeatedly are coupled even
+with no import edge. Two files in the top co-change set with no declared
+dependency are an undeclared functional-coupling finding.
+
+Override edge case: a Generic subdomain (auth, logging, storage plumbing) is
+normally Low volatility. If that generic component is mid-migration or has
+multiple in-repo versions, override it to High volatility for the duration —
+generic-by-default never overrides measured churn.
+
+## Balance Table
+
+Use this diagnosis table. The Severity column is the reproducible priority:
+critical edges first, watch edges only if unstable, the rest are healthy or
+low-cost.
+
+| Strength | Distance | Volatility | Severity | Diagnosis |
+|---|---|---|---|---|
+| High | High | High | 🔴 Critical | Costly global change pressure; prioritize |
+| High | High | Low | 🟡 Watch | Often acceptable if stable and documented |
+| High | Low | High | 🟢 Cohesive | Usually cohesive: keep close or merge |
+| High | Low | Low | 🟢 Fine | Usually fine |
+| Low | High | High | 🟢 Healthy | Healthy loose coupling |
+| Low | High | Low | 🟢 Healthy | Healthy or low-cost |
+| Low | Low | High | 🟠 Inspect | Local complexity; inspect cohesion |
+| Low | Low | Low | 🟢 Low | Low priority unless noisy |
+
+## Quantitative Anchors
+
+Binary each dimension before reading the Balance Table so two auditors reach the
+same cell.
+
+| Dimension | 1 (High) | 0 (Low) |
+|---|---|---|
+| Strength (S) | Intrusive, Functional, or Model coupling | Contract coupling |
+| Distance (D) | crosses service, team, or external boundary | same module or package |
+| Volatility (V) | core/evolving subdomain or recent co-change | stable or generic |
+
+Then:
+
+```text
+BALANCE = (S XOR D) OR (NOT V)
+MAINTENANCE_EFFORT = S * D * V
+```
+
+- `BALANCE = 1` (balanced): the edge is acceptable — strength is local (S=0),
+  distance is local (D=0), or the edge is stable (V=0).
+- `BALANCE = 0` (unbalanced): strong, distant, AND volatile — the highest-cost
+  edge; prioritize it.
+- `MAINTENANCE_EFFORT` ranks unbalanced edges: it is 1 only in the single
+  strong+distant+volatile cell. Use it to order fixes when several edges tie.
+
+These are scoring aids, not proof. A `BALANCE = 1` edge still warrants a finding
+when concrete evidence shows real change friction.
+
+## Pattern Strength Action Lookup
+
+Classify a concrete pattern, then act.
+
+| # | Pattern | Strength | Action |
+|---|---|---|---|
+| 1 | downstream reads another module's private fields or internals | Intrusive | seal behind a contract; remove direct access |
+| 2 | downstream queries another context's database | Intrusive | expose an owned API or anti-corruption layer |
+| 3 | duplicated business predicate or rule in two modules | Functional (symmetric) | extract to one owned location |
+| 4 | mandatory call ordering spread across callers | Functional | hide ordering behind one interface |
+| 5 | shared transaction or state transitions across modules | Functional | co-locate or publish an explicit contract |
+| 6 | upstream exposes persistence schema or enum as integration surface | Model | publish a versioned DTO or language |
+| 7 | DTO mirrors a full domain object | Model | project to a use-case-specific DTO |
+| 8 | dependency on field name, value, or tuple position | Model | wrap in a typed contract |
+| 9 | versioned DTO, event, or schema hides internals | Contract | accept; document as stable |
+| 10 | stable facade or anti-corruption layer translating vocabulary | Contract | accept; record as intentional |
+
+## Static Leads
+
+Look for:
+
+- direct reads of another module's database, config, or internal files
+- imports from `internal`, `private`, generated, or persistence model paths across contexts
+- duplicate business predicates, thresholds, mappings, or validation
+- comments like "update X when changing Y"
+- DTOs that mirror full domain or persistence objects
+- mandatory call ordering spread across callers
+- cycles, bidirectional imports, or dependency inversion breaks
+- tests that require constructing far-away internals to exercise local behavior
+
+## Positive Patterns
+
+Call out positive evidence when useful:
+
+- use-case-specific DTOs or events
+- versioned public contracts
+- anti-corruption layers translating vocabulary
+- stable facade that hides internal model churn
+- dependency direction from volatile policy toward stable abstraction, not from stable core toward volatile detail
+
+## Fix Direction
+
+Reduce strength before increasing distance:
+
+- replace intrusive/model coupling with explicit contracts
+- move tightly coupled volatile modules closer when they change together
+- extract shared duplicated rule only when it is a real domain rule, not trivial repetition
+- document accepted strong-stable integration instead of refactoring it
+- avoid introducing ports/adapters unless there is real variation, test substitution, external dependency, or direction pressure

package/skills/massa-ai/references/architecture-deepening-lens.md

@@ -0,0 +1,136 @@
+# Architecture Deepening Lens
+
+Use this detail reference when an architecture audit or execution task needs module depth, seams, adapters, testability, locality, or AI-navigability analysis.
+
+## Contents
+
+- Vocabulary
+- Deepening Signals
+- Deletion Test
+- Dependency Categories
+- Recommendation Template
+- Interface Design Method
+- Rejected Framings
+- Seam Discipline
+- Test Surface
+- Fix Direction
+
+## Vocabulary
+
+Use these terms exactly:
+
+- Module: anything with an interface and an implementation.
+- Interface: everything a caller must know, including types, invariants, ordering, errors, configuration, and performance.
+- Implementation: code inside the module.
+- Seam: where an interface lives and behavior can be varied without editing callers.
+- Adapter: concrete thing satisfying an interface at a seam.
+- Depth: leverage at the interface.
+- Leverage: capability callers get per unit of interface learned.
+- Locality: change, bugs, knowledge, and verification concentrated in one place.
+
+Avoid using `boundary` for module seams; reserve bounded context language for the domain lens.
+
+## Deepening Signals
+
+Flag candidates when evidence shows:
+
+- module interface is nearly as complex as its implementation
+- pass-through wrappers or one-use helpers add navigation cost
+- one concept is split across many files without leverage
+- callers must know ordering, invariants, config, or error modes that should be hidden
+- tests reach past the interface into internals because the interface is the wrong shape
+- extracted pure functions improve unit-test access but lose locality for real bugs
+- seams exist only for hypothetical future adapters
+
+## Deletion Test
+
+Ask what happens if the module is deleted:
+
+- If complexity disappears, the module was likely shallow.
+- If complexity spreads across callers, the module was probably earning its keep.
+- If behavior becomes harder to verify through one surface, the module likely has useful depth.
+
+Use this as evidence, not as a mechanical rule.
+
+## Dependency Categories
+
+Classify dependencies before recommending seams:
+
+- In-process: pure computation or in-memory state. Usually deepen by merging and testing through the new interface.
+- Local-substitutable: dependency has a local test stand-in. Keep seam internal when possible and test the deep module with the stand-in.
+- Remote but owned: own service across network. Define a port only when it keeps domain logic local and production/test adapters are both real.
+- True external: third-party dependency. Inject a port and use mock/fake adapters for tests when behavior cannot be run locally.
+
+### Recommendation Template
+
+For each dependency, state: Category → recommended seam → stand-in used in tests.
+
+| Category | Recommended seam | Stand-in example |
+|---|---|---|
+| In-process | deepen by merging | none — test through the new interface |
+| Local-substitutable | keep seam internal | in-memory fake |
+| Remote but owned | port only if domain stays local | owned-service test adapter |
+| True external | inject a port | PGLite (database), Stripe test mode (payment) |
+
+A stand-in is required evidence before introducing a port: "inject a port for
+Stripe, with the Stripe test-mode adapter as the production-shape stand-in" —
+not "add a port because it is cleaner."
+
+## Interface Design Method
+
+When a deepening candidate has two or more viable interface shapes, do not pick
+one by instinct. Design it twice: draft two parallel implementations (two
+sub-agents, or two sides authored yourself), each behind a different interface
+against the same caller need, then choose by leverage and locality.
+
+Four canned design constraints force distinct shapes:
+
+1. Minimal surface: hide every field and ordering the caller does not name.
+2. Batchable: one call serves many items, not one call per item.
+3. Policy-free: the interface states what, not how; no strategy leaks out.
+4. Substitutable: a second adapter can satisfy it without caller edits.
+
+Load this method from `architecture-fix.md` or `refactor.md` only when a
+candidate has >= 2 viable interface shapes; otherwise deepen directly.
+
+## Rejected Framings
+
+Avoid these misreadings of depth; record the rejection so it is not re-litigated:
+
+- Depth is NOT a lines-of-code ratio. A deep module can be tiny; a shallow
+  wrapper can be long. Padding an implementation to raise a "depth" metric is
+  exactly the anti-pattern this lens exists to find.
+- Interface is NOT a language keyword (`interface`, `protocol`, `trait`). It is
+  everything a caller must know — types, invariants, ordering, errors.
+- Seam is NOT a class boundary. Reserve `seam` for where behavior can vary
+  without editing callers; reserve bounded-context language for the domain lens.
+
+## Seam Discipline
+
+- One adapter means a hypothetical seam. Two adapters means a real seam.
+- Production plus test adapter can justify a seam when the dependency is remote or external.
+- Internal seams can exist inside the implementation without becoming part of the module interface.
+- Do not expose internal seams just because tests use them.
+- Do not introduce ports/adapters to decorate one local concrete call.
+
+## Test Surface
+
+The interface is the test surface:
+
+- prefer behavior tests through the module interface
+- delete or replace shallow-module tests once deep-module tests cover observable behavior
+- tests should survive implementation refactors
+- if tests must change for implementation-only movement, they are probably testing past the interface
+
+## Fix Direction
+
+Prefer:
+
+- delete shallow pass-through modules
+- inline one-use abstractions
+- merge split concepts when locality improves
+- deepen a useful module by hiding invariants and ordering
+- move validation and transformation behind the interface when callers should not know it
+- add a seam only where variation, dependency direction, external I/O, or test substitution is real
+
+Avoid broad rewrites, VSA migrations, or new service boundaries unless audit evidence shows current module shape blocks change or verification.