Files
clean-architecture-backend-…/docs/design/2026-07-20-harness-policy-engine-design.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

9.8 KiB
Raw Blame History

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 대체됨
  • 작성일: 2026-07-20
  • 요약: 중복된 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 설계다.
  • 현재 정본: gradle/modules.json
  • 대체됨: docs/design/2026-07-25-harness-free-mode-b-amendment.md

SUPERSEDED — HISTORICAL PROVENANCE ONLY (2026-07-25): The user-approved harness-free Mode B amendment supersedes this design. Retain the body as historical provenance; it is not executable instruction.

Harness Policy Engine Refactoring Design

  • Date: 2026-07-20
  • Status: Approved by user request
  • Scope: repository-local development harness (.harness, .agents, .claude, .codex, root/module guidance, Gradle module registry integration)
  • Source: user-provided “개발 하네스 분석·리뷰” plus repository evidence gathered on 2026-07-20

1. Problem Statement

The repository now has 19 nested Gradle leaf modules, but the write-time import gate, agent prompts, runner allowlist, and root guidance still contain parts of the previous flat module topology. Platform variants are copied manually, so commit policy and orchestration already differ between Claude, Codex, and Antigravity. Verdict validation checks a text summary but does not consistently require enum fields, non-negative counts, or arithmetic balance.

The harness must move from duplicated platform prompts to a small policy engine with one project manifest, deterministic renderers, strict validators, and platform adapters.

2. Goals

  1. Make the actual nested Gradle topology a single machine-readable source of truth.
  2. Resolve a touched file to its nearest owning leaf module without assuming src/<module>.
  3. Generate write-time import policy and focused Gradle task validation from that registry.
  4. Validate machine verdicts with required fields, non-negative integers, arithmetic rules, upstream evidence, revision identity, and TDD red evidence for behavior changes.
  5. Materialize validated evidence as JSON artifacts that platform hooks can share.
  6. Render Claude, Codex, and Antigravity agent variants from one canonical source and fail parity checks when generated files drift.
  7. Use one human-only commit policy on every platform.
  8. Replace file-count and exhaustive-report rules with risk and review profiles.
  9. Add mutation and cross-platform static parity tests.

3. Non-Goals

  • This change does not run authenticated end-to-end golden tasks inside all three external products. It supplies the deterministic fixtures and validators those runs will consume.
  • It does not add application features or alter production Java behavior.
  • It does not require PyYAML, jsonschema, Pydantic, or another runtime dependency. Harness data files use JSON syntax, which is valid YAML, and validators use Python stdlib only.
  • It does not make natural-language agent self-reports authoritative. Hooks convert accepted reports into evidence artifacts; validators remain authoritative.

4. Architecture

.harness/project/modules.yaml ──┬── Gradle settings/includes
                                ├── Gradle dependency verification
                                ├── owning-module resolver
                                ├── import gate
                                └── Gradle command validator

.harness/agents/*.md + platforms.yaml
                                └── render_agents.py
                                    ├── .claude/agents/*.md
                                    ├── .codex/agents/*.toml
                                    └── .agents/agents/*/agent.json

Claude hook ───────────────┐
Antigravity hook adapter ──┼── verdict validator ── evidence JSON
Codex validation command ──┘

4.1 Project registry

modules.yaml contains, per leaf module:

  • stable module id
  • repository-relative source path
  • Gradle path
  • role
  • Java package roots (informational and import-policy lookup only)
  • allowed project dependencies
  • focused test command
  • profiles/capabilities
  • owning CLAUDE.md when present
  • an intentional mutation import used by gate tests

src/settings.gradle reads the registry to declare projects. The verifyCleanArchitectureDependencies task reads the same registry instead of maintaining a second dependency map.

4.2 Owning-module resolution

Owner selection uses the longest filesystem-boundary match among registered leaf source paths. Package prefixes never decide ownership because support owns a broad dev.caskeleton.adapter.outbound package and sample code mirrors production packages.

Instruction discovery walks upward from the touched file and returns the nearest CLAUDE.md; if a leaf has none, root CLAUDE.md and AGENTS.md are the explicit fallback.

4.3 Import gate

The import gate first resolves the registered leaf module, then applies:

  • dependency-derived sibling module isolation
  • role-specific framework rules for domain, application, inbound, outbound, persistence, identifier, shared-contract, bootstrap, and sample roles
  • global unsafe-pattern checks

All registered production modules receive a mutation test using their real nested source path. Sample-only exemptions are explicit registry data, not accidental regex misses.

4.4 Verdict and evidence

The canonical verdict schema requires agent, verdict, task_id, revision, and agent specific evidence. Non-blocked verdicts require every declared field. Counts are non-negative. Required equations include:

  • spec totals balance
  • Gradle run = passed + failed + skipped
  • ready Gradle results include at least one command and no failed command
  • behavior-changing implementation requires at least one observed red test
  • quality-ready references validated architecture and spec artifacts

Claude's fenced ca-verdict remains a compatibility input, but its accepted form is converted to the same JSON evidence model. Missing or malformed payloads for detected CA agents fail closed. Evidence records include a source-message hash and current revision/diff identity.

4.5 Platform rendering and hook adapters

Canonical agent Markdown lives under .harness/agents/; platform metadata lives in .harness/project/platforms.yaml. Generated files carry generated_from, source_hash, generator_version, and do_not_edit metadata.

Antigravity gains a plugin hooks.json and a platform adapter using the documented camelCase stdin/stdout contract. Claude keeps its native hook entry points but calls the common library. Codex variants instruct the runner/reviewer to invoke the common validation command because the repository has no equivalent local lifecycle-hook registration surface.

4.6 Risk and review profiles

Risk is determined by change surface, not file count:

  • high: security, migration/schema, public contract, module dependency, architecture rule, transaction/concurrency, CI/deployment
  • medium: behavior, multiple modules, external integration
  • low: docs/comments, test fixture, local refactor protected by characterization tests

Review profiles:

  • review-lite: direct diff references; no saved report by default
  • review-standard: verify blocking citations; one report only when risk or findings justify it
  • audit-deep: verify all quotes and persist detailed findings
  • regulated: immutable evidence and full traceability

Option analysis uses a dependency DAG and at most 3–5 materially distinct alternatives. Counterarguments are required for judgment-dependent findings, not deterministic failures.

5. Commit Policy

All platforms use human-only. Implementers never stage or commit. Reviewers may inspect a working-tree diff before commit or an explicit immutable range after the human commits.

6. Verification Strategy

  1. Stdlib unit tests for registry loading and owner resolution.
  2. Mutation tests for every registered production module path.
  3. Strict verdict negative tests: missing fields, negatives, arithmetic imbalance, missing upstream evidence, revision mismatch, and behavior change without red evidence.
  4. Golden renderer tests and --check parity validation.
  5. JSON validation of generated Antigravity hook and agent files.
  6. Gradle projects, architecture dependency verification, focused ArchUnit test, and full check after harness tests pass.

7. Migration and Compatibility

  • Existing fenced verdicts remain parseable only when they satisfy the new required fields.
  • Generated platform files are overwritten only by the renderer and documented as generated.
  • Root and module guidance is updated to the registered nested topology.
  • Actual external cross-platform golden executions remain a follow-up; static parity and seeded mutation coverage become mandatory in this change.

8. Acceptance Criteria

  • A seeded forbidden import under every nested production module is rejected.
  • No legacy flat adapter path remains in gate tests or agent task allowlists.
  • settings.gradle, dependency verification, import gate, and Gradle runner resolve the same 19 leaf modules from modules.yaml.
  • Missing/negative/inconsistent ready verdicts fail validation.
  • Claude and Antigravity adapters invoke the shared validator; accepted verdicts produce JSON evidence.
  • Rendering followed by --check reports no platform drift.
  • Agent variants uniformly state human-only commit policy and risk-based orchestration.
  • N! enumeration, all-quote routine grep, file-count report splitting, and unconditional counterargument requirements are absent from active rules.
  • Harness tests and Gradle checks pass, or every unrun/failing command is reported with risk.