git:20260813.f9de8c5 to git:20260905.75b9432
5 added, 49 removed. Audit A to A.
- # AGENTS.md (domain-dag)
-
- ## Knowledge & Conventions
-
- ### Meta-Protocol Principles
-
- - 'Domain Ownership': Every durable responsibility should have a single owning source module or package.
- - 'Acyclic Direction': Local source imports should form a directed acyclic graph.
- - 'Composition Boundary': Entrypoints compose ports and runtimes; domain modules do not import entrypoints.
- - 'Transportability': The skill and validator must avoid project-specific names, absolute local paths, stack-only assumptions, and external dependencies.
- - 'Explicit Non-Ownership': Durable module contracts should state what they own and what they reject.
- - 'Interface Surface Pressure': Wide callback/parameter/export surfaces are architectural pressure to group related concepts into named contracts, not automatic failures.
- - 'Shape Before Rules': First identify whether the project is flat, layered, package-based, hexagonal, or hybrid; then choose validation rules.
-
- ### Operating Principles
-
- - Use `scripts/validate-domain-dag.sh` for graph audits.
- - Prefer config-driven project rules over hard-coded repository assumptions.
- - Keep validator defaults portable; make stack-specific checks opt-in via config.
- - Use import aliases from config when a project routes local imports through bundler/tsconfig/package aliases.
- - Treat cycles and reverse entrypoint imports as hard failures.
- - Treat generic shared-bucket names as warnings unless a project config upgrades them.
- - Add custom alias, layer, forbidden-edge, header-clause, and surface-width rules only for discovered project constraints.
-
- ### Discovered Constraints
+ # Domain DAG Maintenance
- - Shared-bucket names are heuristic, not proof of bad architecture.
- - Trigger: `utils`, `types`, `shared`, or similar names appear.
- - Action: Audit ownership and either move content to an owner or allow the exception.
- - Header labels are a navigation aid, not the graph itself.
- - Trigger: A project lacks module headers but has clean boundaries.
- - Action: Warn by default; use strict/config only when headers are adopted standard.
- - Layer checks must be opt-in.
- - Trigger: Generic validation across unknown projects.
- - Action: Validate universal graph invariants by default; enforce local direction only from config.
- - Header clauses are earned standards.
- - Trigger: A project adopts explicit ownership headers such as owner/exclusion clauses.
- - Action: Configure `headerRequiredClauses`; do not bake local wording into the skill default.
- - Wide interfaces are pressure, not proof.
- - Trigger: A child boundary accumulates many callbacks, methods, exports, or parameters.
- - Action: Prefer grouped contracts/ports when stable; use `surfaceRules` as warnings unless noise-free.
- - Decomposition has a stop rule.
- - Trigger: Further extraction would mostly pass host state through or hide control flow.
- - Action: Stop, review, and document the boundary rather than creating one-use wrappers.
- - Flat and layered DAGs are both first-class.
- - Trigger: An extension/CLI has one entrypoint plus cohesive flat domain files, or a frontend/service has earned layered route/use-case/domain separation.
- - Action: Preserve the local shape if dependency direction and ownership are clear; do not impose the other shape for aesthetic consistency.
- - Severity is a ladder.
- - Trigger: A heuristic finds pressure but not a concrete break.
- - Action: Keep it as a warning until repeated evidence proves it should fail builds.
+ - Architecture semantics, calibration, extraction, severity, and configuration are owned by [SKILL.md](./SKILL.md); keep this file limited to development constraints for the skill and validator.
+ - Keep the skill and validator portable: no project-specific names, absolute local paths, stack-only assumptions, or external dependencies. Express project-specific checks through configuration rather than hard-coded repository rules.
+ - Validate this package with `bash scripts/validate-domain-dag.sh --root .`; its local `domain-dag.json` owns self-validation settings, not defaults for consuming projects.
+ - In human-readable validator output, separate section banners and final summaries from diagnostics with a blank line. Keep `--json` output free of those text banners and spacing rules.