JoyZoning Portable

JoyZoning is a small, host-neutral architecture steering layer for AI agents. This folder is a concept port of the JoyZoning behavior in LUMI, shaped as a package that another agent can embed.

Documentation

Start with docs/README.md for the documentation map and validation gate, then read docs/ARCHITECTURE.md for the strategy and ownership boundaries. See docs/LICENSING.md for Apache-2.0 scope and provenance. The .wiki/agent/playbook.md provides the short agent handoff path, while the module guides below remain the detailed contracts.

It answers three questions:

1. What architectural layer does this file appear to belong to?
2. Which boundaries, ownership seams, or dependency edges deserve attention?
3. What is the smallest safe next move, and what should be proved afterward?

It deliberately does not contain an agent loop, model calls, VS Code APIs, gRPC, persistence, or automatic file writes. The host agent owns execution and approval.

The model

JoyZoning uses five canonical layers:

Layer	Responsibility	Directional rule
Domain	Pure business rules, entities, policies	Must not depend on Infrastructure or UI
Core	Application orchestration and state transitions	Must not depend directly on UI
Infrastructure	Filesystem, network, storage, adapters	Must not depend on UI
UI	Rendering and interaction	Should not import Infrastructure directly
Plumbing	Small, context-free utilities and shared primitives	Must not depend on higher layers

There are two postures:

• canonical is an explicit structural contract. Supported source files need [LAYER: TYPE] tags and boundary violations are errors.
• blended is the safe default for an existing workspace. Native project structure wins; JoyZoning findings are non-blocking advisories.

auto selects canonical mode when stability.config.json or spider.spec.json is present, otherwise blended mode.

Use it as a library

import { auditWorkspace, buildAgentContext, formatAgentContext } from "joyzoning-portable"

const report = auditWorkspace({
  files: [
    { path: "src/domain/order.ts", content: sourceText },
    { path: "src/infrastructure/order-store.ts", content: adapterText },
  ],
  config: { mode: "blended" },
})

const context = buildAgentContext(report)
console.log(formatAgentContext(context))

// The host agent decides whether and how to act on these suggestions.
for (const recommendation of report.recommendations) {
  console.log(recommendation.action, recommendation.path)
}

The audit is deterministic and in-memory. It accepts either an array of { path, content } files or a { [path]: content } map. It returns:

• violations: machine-readable findings with stable IDs such as JZ-L01, JZ-B01, and JZ-C01;
• recommendations: suggested actions with effort, risk, rationale, and projected health gain;
• files and layers: per-file metrics and layer summaries;
• cycles, structuralSinks, qualityGateStatus, scores, grade, and an agent-ready signal.

The package also exports pure helpers for layer classification, tag parsing, tag insertion, and file metrics.

Every audit now includes a BroccoliDB-inspired report.policy view. It turns the JoyZoning findings into evidence-backed SPI diagnostics, stable IDs, repair directives, cause clusters, playbook steps, and gate-ready agent bundles. See POLICY.md for the strategy and AGENT-INTEGRATION.md for the host boundary.

Audits also expose report.orchestration, a host-neutral mutation plan derived from those policy directives. It carries risk, required approvals, verification commands, affected files, rollback intent, and scheduling metadata. The orchestrator also keeps hashed in-memory runtime snapshots, integrity reports, compaction summaries, causal views, and read-only replay projections. See ORCHESTRATION.md for the orchestration boundary.

The package also consolidates LUMI's core/agent-context and core/agent-context/capabilities into one host-neutral capability runtime. It provides a canonical catalog for thirteen capabilities, typed operation contracts, intent tracing, lifecycle/health snapshots, a bounded mailbox with shared-mailbox handoff, content-addressed storage, exact-source context compaction with projections/cursors, bounded telemetry, in-memory graph/reasoning/task/lock/scratchpad/query state helpers, token budgeting, and a guarded tool gateway. See AGENT-CONTEXT.md. The orchestration intent type aliases this capability intent so policy, capabilities, and orchestration share one causal model.

import { evaluatePolicyGate, runPolicyScenario, toPolicySarif } from "joyzoning-portable"

const preflight = runPolicyScenario(report.policy, "before-edit", {
  filePath: "src/domain/order.ts",
})
const gate = evaluatePolicyGate(report.policy, {}, "ci")
const sarif = toPolicySarif(report.policy)

The consolidated Spider transport adds JSON-safe check responses, wire-v2 session restore, structured failure envelopes, scenario/pipeline envelopes, problem matchers, and CI artifact manifests. Use getPolicyToolkitCatalog() to bootstrap another agent; use buildPolicyCiArtifacts() to plan upload files while leaving actual writes to the host.

Policy gates and directives remain read-only. A high-risk directive must still be approved and executed by the receiving agent.

import { JoyZoningOrchestrator } from "joyzoning-portable"

const runtime = new JoyZoningOrchestrator({ runtimeMode: "development" })
const session = runtime.beginSession({ taskId: "architecture-repair" })
runtime.recordAudit(session.sessionId, report.policy)
const plan = runtime.planRepairs({ audit: report.policy, sessionId: session.sessionId, policy: "ci_gate_only" })
// runtime.schedule(plan) and runtime.dispatch(hostExecutor) stay at the host-agent boundary.

CLI

npm install
npm run build

# Human-readable report; never edits the target workspace.
node dist/cli.js audit /path/to/project

# Compact context for an agent prompt.
node dist/cli.js audit /path/to/project --agent

# Machine-readable report.
node dist/cli.js audit /path/to/project --json

# CI-style failure only when canonical mode produces errors.
node dist/cli.js audit /path/to/project --mode canonical --fail-on-error

# Policy gate and bounded agent playbook.
node dist/cli.js check /path/to/project --phase ci --agent

# SARIF for CI/code-scanning consumers.
node dist/cli.js check /path/to/project --phase ci --format sarif

An optional joyzoning.config.json at the audited project root can set the same configuration values accepted by auditWorkspace.

Porting guidance

The intended integration is a small preflight/postflight hook:

1. Before an edit, audit the relevant files and pass buildAgentContext(report) into the agent's planning context. Attach AgentContextRuntime when the host has capability adapters.
2. Let the agent choose a native seam and ask for approval before applying a recommendation.
3. After the edit, audit the changed files or workspace again.
4. Use the report's proof obligations with the target project's own tests, typecheck, lint, and build commands.

JoyZoning is steering, not an excuse to impose domain/core/infrastructure/ui/plumbing folders on an established codebase. Use canonical mode when the receiving agent or project explicitly opts in.

Lineage from LUMI

This package keeps the portable ideas from LUMI's:

• src/utils/joy-zoning.ts — layer inference, tags, smells, and import constraints;
• src/core/policy/spider/ and StabilityDoctor — dependency graph signals, cycles, pressure, and health;
• IntegrityOptimizer and ModuleDecomposer — actionable recommendations rather than silent rewrites;
• proto/dietcode/joyzoning.proto — normalized audit/report fields.

Host-specific execution, snapshots, and persistence remain at the receiving agent's adapter boundary.