fix(tooling): hexagen-monaco 0.8.0 + CI / architecture gates

[martinkrakowski]

What

Completes the hexagen tooling arc this branch started on 2026-06-09: bumps @hexagen-monaco/sync + @hexagen-monaco/arch-linter to ^0.7.0 and wires the CI gates the first session deliberately left out.

Why now

The 2026-06-09 session repaired the toolchain to 0.6.0 but did not gate CI on it, because at 0.6.0 every failure mode exited 0 — a gate would have passed vacuously (see .agents/session-log.md). Everything on that session's upstream blocker list shipped in hexagen-monaco 0.7.0:

Left open at 0.6.0	0.7.0 fix
sync + arch validate exit 0 on every failure	honest exit codes throughout
--dry-run not read-only (deleted barrels, wrote reports)	dry-run is read-only
43 phantom "would" lines on a converged tree	truthful counts; converged tree = Total ops : 0
failure rollback = git reset --hard && git clean -fd in this repo	journaled, scoped rollback (only files sync touched)
scaffolder pins a CLI older than the schema it writes	pins derived from the engine version

Changes

• package.json: both pins ^0.6.0 → ^0.7.0 (resolve to 0.7.0); new sync:check script.
• packages/shared/package.json: accepted yarn-4's normalized form (no empty "dependencies": {}). yarn 4 strips the empty block on every install and ≤0.6.0 sync re-added it on every run — a permanent churn loop between the two tools. 0.7.0 emits the block only when non-empty, so yarn's form is now the converged state.
• .github/workflows/ci.yml:
  • yarn install --immutable (lockfile is committed; also keeps an install-mutated lockfile from tripping the drift gate's clean-tree preflight)
  • yarn sync:check — drift gate: exit 1 iff the committed tree differs from what .architecture/manifest.yaml generates
  • yarn lint:arch — layer/import rule enforcement
  • Both ahead of the build: sub-second, fail-fast.

Verification

• sync:check on the converged tree: exit 0, Total ops : 0 (the 0.6.0 CLI showed 43 phantom ops here)
• Negative probe — deleted a generated barrel: exit 1, Drift detected: 1 pending change(s) (1 to create, …); tree restored, re-verified clean. The gate is non-vacuous in both directions.
• lint:arch: compliant, exit 0
• yarn install --immutable, build, typecheck, lint: all green
• test:cov: 287/287, 100% statements/branches/functions/lines

The earlier commits on this branch (0.6.0 repair: pin fix, .architecture/ reconciliation, first converged sync) are documented in the session log and were already reviewed in-session; this PR delivers the whole arc together.

First-run catch (red → green)

The gate's very first CI execution (run 27446848304) failed — legitimately: git can't track empty directories, so the 22 generated-but-still-empty layer dirs existed locally but not in the fresh checkout, and sync --check correctly reported 22 pending change(s) (22 to create). "Converged on my machine" was not "converged in a clone."

Fix (11aff11): .gitkeep in all 22 skeleton dirs (the engine probes the directory, not its contents — a kept dir contributes zero ops), plus removal of five stale value_objects/ (underscore) dirs orphaned by the June layer-naming reconciliation that empty-dir invisibility had been hiding. Verified via fresh clone (install --immutable + both gates green) before pushing; CI run 27447001987 confirms.

Filed upstream (hexagen-monaco): the generator should emit the skeleton in a git-representable form so consumers don't each rediscover this.

Summary by CodeRabbit

• Chores

  • Updated development tooling versions for architecture management and code synchronization
  • Reorganized internal module exports and removed placeholder files
  • Updated architecture configuration for bounded context dependencies

• CI/Build

  • Enhanced CI pipeline with architecture validation and drift detection checks
  • Switched to immutable dependency installation for consistency and reproducibility

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0)

Context used

✅ Compliance rules (platform): 4 rules

1. Overbroad arch whitelist 🐞 Bug ⚙ Maintainability

Description

Adding @campaignfoundry/CampaignOrchestration/** to the arch-linter global whitelist exempts all
imports from that package from validation, reducing the effectiveness of the new CI architecture
gate. This can allow future accidental deep imports/coupling to slip through without being flagged.

Code

.architecture/invariants/linter-config.yaml[R7-11]

+  # CampaignOrchestration owns the ports (ImageGeneratorPort, CompositorPort, …);
+  # adapter packages import those interfaces to implement them — edges depending
+  # on the core, per .agents/architecture.md.
+  - "@campaignfoundry/CampaignOrchestration"
+  - "@campaignfoundry/CampaignOrchestration/**"

Evidence

The linter config change explicitly whitelists all @campaignfoundry/CampaignOrchestration/**
imports. At least some packages import CampaignOrchestration already (e.g., CreativeGeneration
adapters), and the repo’s architecture guidance emphasizes enforcing inward dependencies—so
exempting a whole bounded context from checks reduces enforcement coverage.

.architecture/invariants/linter-config.yaml[4-11]
packages/CreativeGeneration/src/infrastructure/adapters/FireflyImageGenerator.ts[1-9]
.agents/architecture.md[7-16]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`.architecture/invariants/linter-config.yaml` adds `@campaignfoundry/CampaignOrchestration/**` to `global_whitelist`, which effectively disables arch validation for any import from that package. This weakens the CI gate because it can no longer detect when packages start depending on CampaignOrchestration internals beyond the intended port/type surface.

## Issue Context
Several packages legitimately import port/type APIs from `@campaignfoundry/CampaignOrchestration`. The intent is valid, but the current mechanism is too broad.

## Fix
Replace the broad `global_whitelist` patterns with the narrowest patterns supported by the arch-linter that still allow the intended imports (e.g., only the public entrypoint, or only specific subpaths for ports/types if your import conventions support it). If the linter supports rule-based allowlists per package edge, prefer that over a global whitelist.

## Fix Focus Areas
- `.architecture/invariants/linter-config.yaml[4-11]`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Stale test plan statement 🐞 Bug ⚙ Maintainability

Description

TEST_COVERAGE_PLAN.md states the shared stub files “are exported from shared’s barrels,” but this PR
removes the shared placeholder barrel exports, making that statement incorrect. This creates
misleading maintenance documentation for future cleanup/testing work.

Code

packages/shared/src/domain/index.ts[5]

-export * from "./value-objects/index.js";

Evidence

The coverage plan explicitly claims the listed stubs are exported from shared barrels, but the
current shared domain and infrastructure barrel files do not export value-objects or adapters
anymore—so the doc statement is now inaccurate.

TEST_COVERAGE_PLAN.md[44-58]
packages/shared/src/domain/index.ts[1-4]
packages/shared/src/infrastructure/index.ts[1-3]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`TEST_COVERAGE_PLAN.md` claims certain shared stub files are exported from `shared`’s barrels, but the shared barrels no longer export them after this PR’s barrel cleanup.

## Issue Context
The PR deletes/removes the placeholder re-exports from `packages/shared/src/domain/index.ts` and `packages/shared/src/infrastructure/index.ts`, so the coverage plan’s description is now out of sync with the actual public API surface.

## Fix
Edit `TEST_COVERAGE_PLAN.md` to reflect the current state (e.g., mark the deletion as already done, remove the claim about current exports, or update the table/wording accordingly).

## Fix Focus Areas
- `TEST_COVERAGE_PLAN.md[44-58]`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[martinkrakowski]

Reviewer's guide

Read order: package.json → packages/shared/package.json → .github/workflows/ci.yml → .agents/session-log.md.

The one-line story: 0.6.0's CLIs couldn't fail loudly, so CI never gated on them; 0.7.0's can, so now it does.

What to scrutinize

1. ci.yml — gate placement and semantics. sync:check and lint:arch run after install, before build. sync --check implies dry-run (read-only) and decides exit-1-iff-pending-change; in CI the checkout is always a clean tree, so the dirty-tree preflight can't false-positive — except via an install-mutated lockfile, which is why install becomes --immutable in the same diff. Those two changes are coupled; don't take one without the other.

2. packages/shared/package.json — the 2-line diff that looks unrelated. It's the churn-loop kill: yarn 4 deletes an empty "dependencies": {} on install, ≤0.6.0 sync re-added it on every run. If you git checkout this hunk away, the next yarn install recreates it and sync:check stays green either way (0.7.0 never re-injects the empty block) — but the committed form should be the one both tools agree on, which is yarn's.

3. Trusting the gate. The vacuity that blocked this in June is gone, verified in both directions locally: converged tree → exit 0 / Total ops : 0; deleted generated barrel → exit 1 / Drift detected: 1 pending change(s). This PR's own CI run is the first live execution of the gates.

Known cosmetic nit (upstream, not actionable here)

Dry-run logs each planned barrel op twice; the summary table and exit code count it once. Tracked upstream in hexagen-monaco.

Not in this PR

• setup-node's yarn cache stays disabled (its TODO comment stands) — enabling it requires moving corepack enable ahead of setup-node, a separate change.
• The first four commits (0.6.0 repair) predate this session; see the 2026-06-09 session-log entry for their review trail.

[qodo-code-review]

PR Summary by Qodo

fix(tooling): hexagen 0.7.0 and CI architecture drift/lint gates
⚙️ Configuration changes ✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

Walkthroughs

Description

• Bump @hexagen-monaco sync/arch-linter to ^0.7.0 and add sync:check script.
• Gate CI on architecture drift (sync --check) and layer rules (arch validate) before build.
• Update architecture spec/exports to match repo shape and generated barrel layout.

Diagram

graph TD
  CI["GitHub Actions CI"] --> Install["yarn install --immutable"] --> SyncCheck["sync:check (hexagen sync --check)"] --> Tree[("Repo working tree")]
  Install --> ArchLint["lint:arch (hexagen arch validate)"] --> Rules[("Arch rules")]
  SyncCheck --> Manifest[(".architecture/manifest.yaml")]
  ArchLint --> LinterCfg[("linter-config.yaml")]
  SyncCheck --> Barrels["Generated barrel exports"] --> Tree

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Gate on sync --dry-run + diff parsing

• ➕ Works on older hexagen versions without --check support
• ➕ Can surface a planned-op summary in CI logs without relying on exit codes
• ➖ Historically unreliable here (phantom ops and non-failing exit codes pre-0.7.0)
• ➖ More brittle: requires parsing human output or adding custom diff logic

2. Pre-commit hook for sync/arch validation

• ➕ Faster feedback loop for authors; fewer CI round trips
• ➕ Keeps main branch cleaner by preventing drift from landing
• ➖ Not enforceable for all contributors/automation
• ➖ Still needs CI as the source-of-truth gate to prevent bypasses

3. Only run arch gates on changed paths (selective CI)

• ➕ Can reduce CI time when changes are unrelated to architecture/generated artifacts
• ➖ Higher complexity and risk of missing drift introduced indirectly (tooling/lockfile changes, refactors)
• ➖ Current gates are sub-second, so the optimization is low value

Recommendation: Proceed with the PR’s approach: hexagen 0.7.0 makes sync --check a trustworthy, read-only CI drift gate with meaningful exit codes. Keeping the gates fail-fast ahead of the build is the right tradeoff given their low runtime and high signal for generated-artifact drift and architecture rule violations.

File Changes

Enhancement (5)

index.ts Add generated application barrel placeholder +3/-0

Add generated application barrel placeholder

• Introduces a hexagen-generated application index.ts that currently exports an empty module, reserving a stable import surface for future application exports.

packages/CreativeGeneration/src/application/index.ts

---

index.ts Add generated adapters barrel exports +9/-0

Add generated adapters barrel exports

• Adds a hexagen-generated adapters index.ts that re-exports the CreativeGeneration infrastructure adapter implementations.

packages/CreativeGeneration/src/infrastructure/adapters/index.ts

---

index.ts Add generated application barrel placeholder +3/-0

Add generated application barrel placeholder

• Introduces a hexagen-generated application index.ts that currently exports an empty module, reserving a stable import surface for future application exports.

packages/Distribution/src/application/index.ts

---

index.ts Add generated adapters barrel exports +3/-0

Add generated adapters barrel exports

• Adds a hexagen-generated adapters index.ts re-exporting FileSystemExporter.

packages/Distribution/src/infrastructure/adapters/index.ts

---

index.ts Add generated adapters barrel exports +3/-0

Add generated adapters barrel exports

• Adds a hexagen-generated adapters index.ts re-exporting BrandComplianceChecker.

packages/GovernanceAndCompliance/src/infrastructure/adapters/index.ts

---

Refactor (5)

index.ts Switch infrastructure exports to barrel + add fonts/safe-path +3/-6

Switch infrastructure exports to barrel + add fonts/safe-path

• Replaces individual adapter exports with a single adapters/index.js barrel export. Adds exports for fonts.js and safe-path.js alongside adapters.

packages/CreativeGeneration/src/infrastructure/index.ts

---

index.ts Switch infrastructure exports to adapters barrel +1/-1

Switch infrastructure exports to adapters barrel

• Replaces the direct adapter export with an adapters/index.js barrel export to match the generator’s structure.

packages/Distribution/src/infrastructure/index.ts

---

index.ts Switch infrastructure exports to adapters barrel +1/-1

Switch infrastructure exports to adapters barrel

• Replaces the direct adapter export with an adapters/index.js barrel export to match the generator’s structure.

packages/GovernanceAndCompliance/src/infrastructure/index.ts

---

index.ts Stop re-exporting removed shared value-objects barrel +0/-1

Stop re-exporting removed shared value-objects barrel

• Removes the value-objects index re-export since the shared kernel has no value objects and the placeholder barrel was deleted.

packages/shared/src/domain/index.ts

---

index.ts Stop re-exporting removed shared adapters barrel +0/-1

Stop re-exporting removed shared adapters barrel

• Removes the adapters index re-export since shared has no infrastructure adapters and the placeholder barrel was deleted.

packages/shared/src/infrastructure/index.ts

---

Documentation (1)

session-log.md Document hexagen 0.7.0 rollout and CI gating rationale +64/-0

Document hexagen 0.7.0 rollout and CI gating rationale

• Adds a detailed 2026-06-09 and 2026-06-12 log entry describing why earlier hexagen versions couldn’t be CI-gated and what 0.7.0 fixes. Captures decisions, verification steps, and remaining TODOs.

.agents/session-log.md

---

Other (4)

linter-config.yaml Whitelist CampaignOrchestration for adapter implementations +5/-0

Whitelist CampaignOrchestration for adapter implementations

• Expands the global whitelist to allow adapter packages to import CampaignOrchestration-owned port interfaces. Adds inline rationale tying this to the intended dependency direction (adapters depend on core).

.architecture/invariants/linter-config.yaml

---

manifest.yaml Align manifest with repo naming and bounded-context dependencies +6/-5

Align manifest with repo naming and bounded-context dependencies

• Renames the shared domain subfolder from value_objects to value-objects. Declares adapter contexts as depending on CampaignOrchestration and removes references to deleted external-service-client out-port stubs.

.architecture/manifest.yaml

---

ci.yml Add immutable installs and architecture drift/lint gates +17/-4

Add immutable installs and architecture drift/lint gates

• Switches dependency install to yarn install --immutable to prevent lockfile mutations in CI. Adds two fail-fast steps: sync:check (hexagen sync --check) to detect generated drift and lint:arch (hexagen arch validate) to enforce architecture rules before build/test.

.github/workflows/ci.yml

---

package.json Bump hexagen tooling to ^0.7.0 and add sync:check script +3/-2

Bump hexagen tooling to ^0.7.0 and add sync:check script

• Updates @hexagen-monaco/sync and @hexagen-monaco/arch-linter to ^0.7.0. Adds a sync:check npm script that maps to hexagen sync --check for CI drift gating.

package.json

---

[martinkrakowski]

Reviewer's guide — delta (first CI run caught a real gap)

What happened: the drift gate failed its own debut (run 27446848304): Drift detected: 22 pending change(s) (22 to create, 0 to update, 0 to delete) — every one a would create directory for an empty layer-skeleton dir (entities/, value-objects/, ports/in|out, use-cases/, adapters/).

Why it's a true positive, not a gate bug: git cannot represent an empty directory. The dirs existed in every long-lived working copy (the June sync session created them) but in no fresh checkout — so the committed tree genuinely did not converge. The local runs passed for the same reason the bug survived: nobody's working copy was fresh.

The fix (11aff11), and what to check:

• .gitkeep × 22 — exactly the dirs the CI log named, no more. The sync engine's layer-folders generator probes stat(dir), not contents, so a kept dir plans zero ops (verified locally and in a from-scratch clone before pushing).
• 5 × value_objects/ (underscore) dirs removed — stale leftovers from the June value_objects → value-objects rename, invisible until now because empty dirs never appear in git status. None had a tracked file; rmdir (not rm -rf) guaranteed they were empty.
• Run 27447001987: gates + full pipeline green on the real CI checkout.

Upstream note: this failure mode awaits every hexagen consumer that wires sync --check in CI while any generated layer dir is still empty. Filed on the hexagen-monaco backlog: the generator should emit the skeleton git-representably (emit .gitkeep itself, or classify dir-creates separately in --check).

[martinkrakowski]

Verification of the Qodo review findings

I dug into both findings against the actual arch-linter source, the package exports maps, and the git history. Verdicts below.

1. "Overbroad arch whitelist" — ✅ valid kernel, but overstated as a Bug → fixed in dd6c645

What's right: the mechanism is accurate. isGlobalWhitelisted() short-circuits isCrossPackageViolation() in @hexagen-monaco/arch-linter, so a matched specifier bypasses the per-package rules, and the /** pattern matches every @campaignfoundry/CampaignOrchestration/... subpath.

What's overstated:

• The risk is essentially moot. packages/CampaignOrchestration/package.json declares exports with only "." — there is no subpath map, so deep imports (.../CampaignOrchestration/src/...) don't resolve and fail at typecheck/build before the linter runs. The exports map, not the linter, is what forecloses deep imports.
• The /** entry matched zero imports: every importer uses the bare root specifier (e.g. FireflyImageGenerator.ts imports ImageGeneratorPort, AspectRatio, … from "@campaignfoundry/CampaignOrchestration"), and there are no subpath imports anywhere in packages/ or apps/.
• Not a bug — nothing was broken, and whitelisting the core's entrypoint is architecturally intended: CampaignOrchestration owns the ports and adapters import them inward, per .agents/architecture.md ("edges depend on the core").

Fix applied: dropped the @campaignfoundry/CampaignOrchestration/** line and kept the exact-root entry (which is load-bearing — without it the legitimate adapter→core imports would be flagged, since there are no package_rules). Strictly tighter, zero loss. yarn lint:arch stays green. The reviewer's "narrow to specific port/type subpaths" suggestion is inapplicable here — there are no subpath exports to narrow to; the root entrypoint already is the narrowest valid pattern.

2. "Stale test plan statement" — ✅ valid as an Informational nit, but mis-attributed and out of scope (no change)

What's right: TEST_COVERAGE_PLAN.md §1a ("They are exported from shared's barrels but used nowhere") is now inaccurate — the four stub files are gone and nothing re-exports them.

Corrections:

• This PR did not introduce the staleness. The four stubs were deleted earlier in 56722fc refactor(shared): delete unused generated stubs, after which value-objects/index.ts was already export {}; (exporting nothing). This PR only sweeps up the leftover empty barrel files / dangling re-export lines as part of the hexagen sync normalization.
• TEST_COVERAGE_PLAN.md is not touched by this PR and is a planning doc for a different branch (feat/test-coverage); §1a is a pre-work snapshot whose recommendation ("delete all four and their barrel re-exports") has since been fully executed.

Leaving it as-is — it reads correctly as a historical planning record, and editing an out-of-scope doc here would only widen this PR's surface. Happy to update the wording to past tense in a docs-only follow-up if preferred.

---

Net: one safe one-line tightening applied (dd6c645) for finding #1; finding #2 is a correct-but-minor, out-of-scope doc nit left for a separate pass.

_{🤖 Generated with Claude Code}