Architecture

The public acc architecture group observes or generates architecture evidence; it does not rewrite source files or apply a proposed migration. The model distinguishes where a subsystem belongs from whether one layer may depend on another. Both must be healthy for the combined guard to pass.

Use the canonical names shown here when calling impact, plan, orevolve. Unknown layer names fail closed rather than becoming new architecture.

The ownership scanner examines immediate directories under core/. Examples includecore/cli as CLI, core/architecture andcore/documentation as Core, core/runtime andcore/actions as Runtime, and core/release as Release. A directory without a matching rule is UNMAPPED and degrades architecture governance.

Ownership describes responsibility, not import permission. Adding a path rule must point to an existing canonical layer; it does not automatically authorize new cross-layer dependencies.

Same-layer dependencies are classified as INTERNAL. For cross-layer imports, an explicit allow policy yields ALLOW, an explicit prohibition yieldsDENY, and a missing policy yields UNDEFINED. Both deny and undefined are violations.

The policy registry includes allowed relationships and explicit critical prohibitions such as Runtime → CLI, Platform → Runtime, Core → CLI, and Release → Intelligence. A cross-layer relationship absent from the registry is not implicitly safe: enforcement returns no policy and rejects it.

acc architecture guard combines four checks: ownership has no unmapped paths, the policy registry is valid, static import analysis has no violations, and the dependency graph is healthy. A failure in any check returns a failed guard.

Current analysis excludes core/testing from production enforcement and does not model shell sourcing, runtime loaders, generated dependencies, event wiring, or other dynamic mechanisms. A healthy graph means the analyzed Python surface is healthy, not that every possible runtime dependency has been proven safe.

impact classifies a proposal as INTERNAL, ALLOW,DENY, or UNDEFINED. Internal and allowed proposals are accepted with low risk. A denied proposal is critical and reduces the projected score by 30; an undefined proposal is high risk and reduces it by 20.

plan adds ordered change steps, a recommendation, and an optional migration path. Its exit status is 0 for executable IMPLEMENT or MIGRATErecommendations and 2 when redesign is required. evolve ranks candidates, but neither command applies the recommendation.

1. Run scan to separate missing ownership from dependency violations.
2. Run metrics and guard to confirm the analyzed scope and failing checks.
3. Inspect the generated analysis report or the source import and its policy decision.
4. Use impact and plan with canonical layer names to evaluate a safer direction or migration.
5. Change ownership or policy only when the canonical responsibilities genuinely changed; otherwise move or invert the dependency.
6. Regenerate evidence and rerun the guard after the code change.

Do not add a blanket allow rule merely to reach zero violations. Undefined relationships are deliberately rejected, and a generated report is evidence of analysis rather than approval for the proposed design.

• Use status, scan, metrics, validate, policy, and guard for current-state inspection.
• Treat report and graph as writes because they replace generated Markdown outputs.
• Use layer names exactly as registered; the source/target order changes the policy decision.
• Preserve the command, commit identity, output, and generated diff together when using results as review evidence.
• Review non-Python and dynamic dependencies separately because the static graph cannot certify them.
• Run the full architecture guard after changes to path ownership, policies, imports, or layer responsibilities.

Read the current architecture state

acc architecture status
acc architecture scan
acc architecture metrics
acc architecture guard

Evaluate an allowed dependency without changing code

acc architecture impact Release Core
acc architecture plan Release Core

Evaluate a prohibited dependency and expect rejection

acc architecture impact Runtime CLI
acc architecture plan Runtime CLI

Regenerate reviewable architecture evidence

acc architecture report
acc architecture graph
git diff -- docs/architecture/analysis-report.md \
  docs/architecture/dependency-graph.md