Governance Rules

29 anti-patterns tracked | 6-layer enforcement | Content classification matrix

This page documents the governance rules that the ADLC framework enforces across all agent interactions. Rules are derived from adlc-governance.md (source of truth) and implemented through hooks, permissions, and behavioral constraints.

---

Anti-Pattern Registry

The ADLC framework tracks 29 anti-patterns discovered through production incidents. Each pattern has a root cause analysis, prevention mechanism, and detection hook.

Coordination Anti-Patterns

#	Pattern	Description	Prevention
1	STANDALONE_EXECUTION	Specialist work without PO+CA approval	remind-coordination.sh (exit 1)
2	RUBBER_STAMP_COORDINATION	Running PO+CA in background then proceeding immediately	FOREGROUND-only rule
3	COORDINATION_WITHOUT_DELEGATION	PO+CA ran but Claude used raw Edit/Write instead of specialist Task	enforce-specialist-delegation.sh (exit 2)
4	PLAN_MODE_COORDINATION_BYPASS	Plan mode framing overrides coordination-first requirement	Rules-layer + invocation verb patterns
5	SCOPE_DRIFT_BYPASS	Logs from prior scope treated as valid for new question	Rules-layer: self-check log scope
6	HITL_REPORT_SCOPE_DRIFT	Implementation logs used to authorize HITL report deliverable	remind-coordination.sh v4.3.0 scope detection
7	EXPLORE_AGENT_BYPASS	invoke.*agent regex matched non-coordination agents (Explore, Plan) — coordination check falsely satisfied	remind-coordination.sh: tighten COORDINATION_PATTERNS to explicit product.owner|cloud-architect names only
8	RAW_TOOL_OVER_SKILL	Using raw Edit/Bash instead of task commands or ADLC skills	CLAUDE.md "Use This / NOT This" table

Evidence Anti-Patterns

#	Pattern	Description	Prevention
9	NATO_VIOLATION	Completion claims without evidence paths	detect-nato-violation.sh (exit 2)
10	SKIP_EVIDENCE	Completion without artifacts in tmp/	detect-nato-violation.sh + evidence gate
11	TEXT_OUTPUT_BYPASS	Implementation content in text without PO+CA coordination	Rules-layer (unhookable surface)
12	KISS_MISINTERPRETATION	KISS principle misread as "shorten output" -- strips evidence	Rules-layer: KISS governs code, not evidence
13	JSON_ONLY_NATO	Updating JSON evidence files without updating corresponding HITL-consumable deliverable (executive report, stakeholder summary)	Rules-layer: when evidence JSON changes materially, update HITL deliverable in the SAME session

Security Anti-Patterns

#	Pattern	Description	Prevention
14	GITHUB_API_TREE_CORRUPTION	Git tree via API without base_tree deletes all other files	validate-bash.sh v2.1.0 blocks gh api git endpoints
15	HOOK_BYPASS_VIA_API	Using alternative API to circumvent hook-blocked action	Rules-layer: hooks are governance, not obstacles
16	BARE_METAL_TOOLS	Running terraform/tflint/checkov on host instead of container	enforce-container-first.sh (exit 2)

Infrastructure Anti-Patterns

#	Pattern	Description	Prevention
17	CI_CONTAINER_EACCES	Container job without options: --user 0	Mandatory CI pattern
18	SUBMODULE_PAT_MISSING	Checkout with submodules using default GITHUB_TOKEN	token: ${{ secrets.SUBMODULE_PAT }}
19	CHECKOUT_BARE_TAG_NAME	actions/checkout with bare tag name fails on dispatch	Normalize to refs/tags/ prefix
20	MONOLITHIC_CI	Cost/security jobs in ci.yml instead of separate workflows	Single-responsibility workflows
21	BLIND_PLAN_EXECUTION	Plan items executed without verifying prerequisites	Gate-check each plan item
22	FALSE_AS_IS_STATE	Explore agent returned "not found" for staged content	Cross-validate with git status

Resource Discovery Anti-Patterns

#	Pattern	Description	Prevention
23	NARROW_SEARCH_SCOPE	Searching a subset of accounts manually when org-wide discovery tools exist — per-account search past 3 accounts signals org-wide tools should be used	Rules-layer: attempt org-wide tools FIRST (Config Aggregator, Resource Explorer AGGREGATOR, Cost Explorer). Per-account is P2 fallback only
24	SINGLE_ACCOUNT_ASSUMPTION	Trusting the task-provided account ID without verifying the resource actually exists there	Rules-layer: Phase 0 MUST verify resource's actual account via org-wide discovery BEFORE deep-diving the provided account
25	DELAYED_ORG_WIDE_ESCALATION	Continuing per-account manual search instead of escalating to org-wide discovery after repeated NOT_FOUND	Rules-layer: after N=3 NOT_FOUND (configurable via ADLC_ORG_SEARCH_THRESHOLD), MANDATORY switch to org-wide discovery

Version Anti-Patterns

#	Pattern	Description	Prevention
26	FOCUS_VERSION_HALLUCINATION	Assuming FOCUS 1.3 when spec says 1.2+	Grep-verify before writing
27	MANUAL_VERSION_BUMP	Editing VERSION/CHANGELOG when release-please exists	Detect release-please presence
28	RELEASE_PLEASE_DOUBLE_RELEASE	Manual git tag after release-please adoption	Mode-detection block
29	VERSION_DRIFT_SILENT_FAIL	release-please string-replace skips stale VERSION	4-file consistency check

---

Content Classification

Defines what requires PO+CA coordination versus what agents can answer directly.

Requires Coordination (BLOCKING)

All of the following require current, in-scope coordination logs:

• Architecture decisions (choosing between design patterns, module structures)
• Design comparisons ("why not X vs Y", "should we use A or B")
• Technology selection rationale (which tool, library, framework)
• Business value analysis (cost/benefit, trade-off assessments)
• Implementation recommendations (how to build or change something)
• Infrastructure strategy (deployment targets, scaling approaches)
• Security posture decisions (sandboxing strategy, access control design)
• HITL deliverables (manager reports, executive summaries, decision matrices)

Exempt from Coordination

The following can be answered directly without coordination logs:

• Factual lookups ("What does this Terraform resource do?")
• CLI/tool output interpretation (explaining error messages)
• Reading and summarising existing files without recommending changes
• Status checks ("Does this file exist?", "What is in this directory?")
• Simple Q&A about existing code ("What does this variable do?")
• Error debugging of existing code (identifying bugs, not redesigning)

Boundary Cases

Question Type	Classification	Rationale
"What does this pattern do?"	Exempt	Factual description
"Is this pattern correct?"	Requires	Implies design judgement
"Should we use X or Y?"	Requires	Comparative design decision
"How do I fix this syntax error?"	Exempt	Mechanical correction
"How should we restructure this?"	Requires	Architectural recommendation
"Generate a HITL report"	Requires	Distinct deliverable scope

---

CI Container Pattern (Mandatory)

All GitHub Actions jobs using container: directive must include options: --user 0:

container:
  image: nnthanh101/terraform:2.6.0@sha256:<pinned-sha>
  options: --user 0  # Prevents EACCES on /__w/_temp/

All checkout steps with submodules: recursive must include token:

- uses: actions/checkout@v4
  with:
    submodules: recursive
    token: ${{ secrets.SUBMODULE_PAT }}

PAT scoping: Fine-grained PAT, single-repo (submodule repo only), Contents: Read-only, 90-day expiry.

---

Hook Coverage Limitation

Claude's text response stream is the one ungated surface -- no hook event fires on text output.

Hook Event	Fires On	Can Block
UserPromptSubmit	User's incoming prompt	Yes
PreToolUse	Edit/Write/Task/Bash tool calls	Yes
PostToolUse	Tool completion	No (audit only)
Text response	Not hookable	No

Mitigation: Rules-layer prohibition in CLAUDE.md and adlc-governance.md. Claude must not produce implementation content in text output unless coordination logs exist and are scoped to the current question.

---

Evidence Requirements

Type	Path Pattern	Format
Coordination logs	tmp/<project>/coordination-logs/*.json	JSON with ISO8601 timestamps
Test results	tmp/<project>/test-results/*.json	JSON with pass/fail counts
Evidence packages	tmp/<project>/evidence/*.md	Markdown with verification details
Audit trail	tmp/<project>/security/*.jsonl	JSON Lines (append-only)
PDCA state	tmp/<project>/pdca-cycles/*.json	JSON with cycle counts

---

Related Pages

• Hook Enforcement Reference - Implementation details for all 12 hooks
• Permissions - 3-tier permission model
• Principle I: Acceptable Agency - HITL approval boundaries
• Principle VI: Governance & Compliance - Certification and audit