@massa-ai/claude-plugin 1.6.0

package/skills/massa-ai/references/adr-authoring.md

@@ -0,0 +1,189 @@
+# ADR Authoring
+
+Use this reference from `workflows/adr.md`. It defines how massa-ai creates Architecture Decision Records without delegating orchestration to another ADR skill.
+
+## Core Rule
+
+An ADR records a significant architecture decision that is already made or being finalized. If the user is still choosing among options, route to `workflows/rfc.md`. If the user needs implementation design after the decision, route to `workflows/tdd.md`.
+
+Route matrix:
+
+| User state | Route |
+|---|---|
+| One architecture decision is selected and needs durable consequences recorded | ADR |
+| Two or more options remain open, or stakeholders must review before choosing | RFC |
+| Direction is selected and implementation architecture/contracts/rollout need a blueprint | TDD |
+| Requirements, design, tasks, and execution all need staged approval | Spec-driven |
+
+Source relevance requires the source to name at least one target, constraint, risk, dependency, public contract, rejected option, decision owner, or rollout/rollback consequence for this ADR. Sources that provide only style or adjacent context are examples, not facts.
+
+Do not guess. Missing source facts become questions, source gaps, or a workflow route change.
+
+## Source Order
+
+Prefer sources in this order:
+
+1. User prompt and explicitly provided Markdown files.
+2. ADR template from Markdown or Atlassian MCP. If absent, ask fallback ADR format/status/supersession questions.
+3. PRD from Markdown or Atlassian MCP when provided. If needed but absent, ask for missing context instead of inventing.
+4. RFC from Markdown or Atlassian MCP when provided. If needed but absent, ask for missing context instead of inventing. If the user does not know, assume the decision is not made and route to `workflows/rfc.md`.
+5. Complementary ADR from Markdown or Atlassian MCP when provided. Use it as factual context only for cross-stack constraints, contracts, dependencies, risks, and links.
+6. Same-Stack Example ADR from Markdown or Atlassian MCP when provided. Use it only for format, structure, tone, naming, metadata, and placement conventions; do not use its decision context, rationale, constraints, consequences, or claims as facts for the new ADR.
+7. UI/UX context from Figma MCP when provided and relevant. If Figma is absent, use PRD, RFC, or NotebookLM context. If none exists, ignore UI/UX.
+8. NotebookLM when the user provides one or more notebook IDs. Query each relevant notebook separately, preserve source attribution by notebook ID, dedupe overlapping facts, and never assume or hard-code a default notebook ID.
+9. `recall`, `search`, current repo docs, existing ADRs, and source code for corroboration.
+
+Load `references/context-firewall.md` before bringing large Markdown, Atlassian, NotebookLM, Figma, broad research, or verbose source output into the main context. Bring back source pointers and compact facts, not raw dumps.
+
+Load `references/mobile-context.md` only when the ADR context touches KMP, iOS, Android, native bridges, mobile lifecycle, offline sync, permissions, push/background behavior, local persistence, or backend-mobile contracts. Mobile is context-only here; do not add runtime mobile lazy-loading policy unless the user separately asks for that decision.
+
+## Stack ADR Inputs
+
+Classify optional ADR inputs before using them:
+
+- `target-stack`: the stack of the ADR being created, such as mobile, backend, frontend, data, infrastructure, or platform.
+- `complementary-stack`: another stack that integrates with the target stack, such as backend for a mobile ADR or mobile for a backend ADR.
+- `same-stack example`: an ADR from the same stack as the target, provided as an example/base.
+
+Use explicit user labels first. Infer stack role from source names, page titles, paths, or content only when obvious. Ask when ambiguity affects whether the ADR is complementary context or same-stack example.
+
+Complementary ADR rules:
+
+- Accept from Markdown files or Atlassian MCP.
+- Use as real context only for cross-stack API contracts, schemas, auth flows, data ownership, compatibility constraints, rollout dependencies, operational risks, security boundaries, and links.
+- Do not copy unrelated rationale or consequences from the complementary ADR into the new ADR.
+
+Same-Stack Example ADR rules:
+
+- Accept from Markdown files or Atlassian MCP.
+- Use as style and structure guidance only: headings, metadata shape, status wording, numbering pattern, title style, tone, level of detail, and link formatting.
+- The same-stack example context is not factual context for the new ADR.
+- The example ADR facts must not be copied into context, rationale, constraints, consequences, links, or source confidence for the new ADR unless separately confirmed by another valid source.
+
+## NotebookLM Inputs
+
+Accept multiple NotebookLM notebook IDs when the user provides them. For each relevant notebook ID:
+
+- Query the notebook separately for ADR-relevant facts.
+- Preserve attribution by notebook ID in the source notes.
+- Dedupe overlapping facts across notebooks without losing source coverage.
+- Treat NotebookLM summaries as source-backed context only when the answer ties facts to notebook sources.
+- Never hard-code a notebook ID or assume a default notebook.
+
+If a notebook cannot be queried, state the failure and continue with available sources instead of inventing notebook facts.
+
+## Source Confidence
+
+Label each material claim before finalizing:
+
+- `confirmed`: verified against current source, docs, ADRs, or MCP-backed context.
+- `user-provided`: supplied directly by the user.
+- `recalled`: recovered from massa-ai memory and not contradicted by current evidence.
+- `inferred`: derived from evidence; state the inference and why it follows.
+- `unresolved`: not sufficiently supported; ask or omit.
+
+Do not include unresolved claims as ADR facts.
+
+## Readiness Gate
+
+Proceed only when all mandatory fields are source-backed or user-confirmed:
+
+- Decision title: noun phrase, not a question.
+- Decision date: use the user's date or current date when no other date is provided.
+- Status: Accepted, Proposed, Deprecated, or Superseded.
+- Context: forces, constraints, and situation that made the decision necessary.
+- Decision: what was chosen and why this option wins.
+- Consequences: positive and negative trade-offs.
+- Supersession: whether this supersedes or is superseded by another ADR.
+- Links: related ADRs, RFCs, PRDs, tickets, docs, Figma files, NotebookLM notes, or code references when available.
+
+Recommended fields:
+
+- Decision drivers.
+- Options considered.
+- Pros and cons per option.
+- Outcome rationale tied to the drivers.
+- Rollback, migration, or reversibility notes when decision risk warrants them.
+
+Ask before drafting when a mandatory field is missing. If the user cannot confirm that a decision has been made, route to RFC.
+
+## Fallback Questions
+
+When no project template or sufficient context is provided, ask only for missing high-impact details. Use these ADR-authoring questions as the fallback set:
+
+- What decision should this ADR record?
+- Which format should be used: MADR, Nygard, or Y-Statement? Default to MADR for structured trade-offs.
+- What is the status: Accepted, Proposed, Deprecated, or Superseded?
+- Does this ADR supersede a previous decision? If yes, which ADR?
+- What context, constraints, or product forces made the decision necessary?
+- Which alternatives were seriously considered, and why were they rejected?
+- What positive and negative consequences should future engineers know?
+
+If the user provides a project ADR template, follow it instead of these fallback questions.
+
+## Format Guidance
+
+Use the project's existing ADR style first. If no template or prior convention exists:
+
+- MADR: default for most decisions, especially when alternatives were compared.
+- Nygard: use for small, obvious decisions that only need Context, Decision, and Consequences.
+- Y-Statement: use for very compact inline records.
+
+Preserve the user's language for section headers and content. Keep technical terms in English when that is the local convention.
+
+## Numbering And Placement
+
+Find the ADR directory before assigning a number. Check common locations in order:
+
+1. `docs/adr/`
+2. `docs/decisions/`
+3. `adr/`
+4. `.adr/`
+
+Scan existing ADR filenames for the highest zero-padded number and assign the next number. Use `NNN-kebab-case-title.md`. If no directory exists, propose `docs/adr/001-kebab-case-title.md` unless the user or project docs specify a different location.
+
+In Default mode, save the ADR when the user asked for execution. In Plan Mode, propose the path and content without writing.
+
+## Output Targets
+
+Default output is local Markdown in the project's standard ADR directory.
+
+Confluence output:
+
+- Use only when the user requests Confluence output.
+- If the user provides a parent Confluence page link, write the generated ADR as a child page through Atlassian MCP.
+- Include the resulting Confluence page link in completion evidence and ADR links when available.
+- If the parent page link is missing, ask for the parent link or ask whether to write the ADR Markdown under `.adr/` instead.
+- If Atlassian MCP is unavailable, state that Confluence writing is unavailable and ask whether to write a local `.adr/` Markdown file.
+
+Local `.adr/` fallback:
+
+- Use `.adr/` when the user chooses local fallback after missing Confluence parent context or unavailable Atlassian MCP, even if another standard ADR directory exists.
+- Preserve the same ADR numbering and filename rules unless the project has a stronger convention.
+- Do not silently switch from requested Confluence output to local files without user confirmation.
+
+## Quality Checklist
+
+Before finalizing:
+
+- Title records the decision, not the question.
+- Date and status are present.
+- Context explains forces and constraints, not just the implementation outcome.
+- Decision is direct and tied to source-backed rationale.
+- Consequences include honest downsides.
+- Alternatives include at least two real options when using MADR.
+- Links and supersession relationships are included when applicable.
+- File path and number match project convention.
+- Every non-obvious claim has source confidence.
+
+## Anti-Patterns
+
+- Creating an ADR for an undecided proposal instead of routing to RFC.
+- Writing implementation details that belong in a TDD.
+- Editing the meaning of old ADRs instead of superseding them.
+- Omitting "why not" rationale for rejected alternatives.
+- Treating massa-ai memory as current truth without corroboration when accuracy matters.
+- Fabricating PRD, RFC, UI/UX, Atlassian, Figma, or NotebookLM facts because a source was unavailable.
+- Treating same-stack example ADR facts as context for the new ADR.
+- Copying complementary ADR rationale outside cross-stack contracts, constraints, dependencies, risks, or links.
+- Silently writing local `.adr/` Markdown when the user requested Confluence output.

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