antigravity-ai-kit 3.1.1 → 3.2.0

package/.agent/skills/plan-validation/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: plan-validation
+description: Quality gate for implementation plans. Validates schema compliance, cross-cutting concerns, and completeness scoring before user presentation.
+version: 1.0.0
+triggers: [post-plan-creation]
+allowed-tools: Read, Grep
+---
+
+# Plan Validation
+
+> Quality gate ensuring every implementation plan meets enterprise standards
+> before being presented to the user for approval.
+
+---
+
+## Overview
+
+This skill is used by the planner agent as a self-validation checklist after creating a plan but BEFORE presenting it to the user. The planner applies the validation pipeline below to its own output, verifying against the quality schema (`plan-schema.md`), checking cross-cutting concerns, and calculating a completeness score. Plans that fail validation are revised before presentation.
+
+**Invocation**: The planner runs this checklist during `/plan` workflow step 3.5. This is NOT a separate agent — the planner validates its own plan against these criteria.
+
+---
+
+## Validation Pipeline
+
+### Step 1: Task Size Classification
+
+Determine the task size from the plan content:
+
+| Indicator | Classification |
+|-----------|---------------|
+| Plan references 1-2 files | **Trivial** |
+| Plan references 3-10 files | **Medium** |
+| Plan references 10+ files | **Large** |
+| Estimated effort < 30 minutes | **Trivial** |
+| Estimated effort 1-4 hours | **Medium** |
+| Estimated effort > 4 hours | **Large** |
+
+Use the HIGHER classification when indicators conflict.
+
+### Step 2: Schema Compliance
+
+Verify all required sections are present and substantively populated:
+
+**Tier 1 Sections (Always Required)**:
+
+| # | Section | Check |
+|---|---------|-------|
+| 1 | Context & Problem Statement | Present and >= 2 sentences |
+| 2 | Goals & Non-Goals | Both goals AND non-goals stated |
+| 3 | Implementation Steps | Steps have file paths and verification criteria |
+| 4 | Testing Strategy | Test types specified with coverage targets |
+| 5 | Security Considerations | Substantive content or explicit "N/A — [reason]" |
+| 6 | Risks & Mitigations | At least 1 risk with severity and mitigation |
+| 7 | Success Criteria | Measurable, checkable outcomes |
+
+**Tier 2 Sections (Required for Medium/Large)**:
+
+| # | Section | Check |
+|---|---------|-------|
+| 8 | Architecture Impact | Components and files identified |
+| 9 | API / Data Model Changes | Schemas defined (or N/A with reason) |
+| 10 | Rollback Strategy | Concrete undo procedure |
+| 11 | Observability | Logging/metrics plan |
+| 12 | Performance Impact | Assessment provided |
+| 13 | Documentation Updates | Specific docs identified |
+| 14 | Dependencies | Blockers and dependents listed |
+| 15 | Alternatives Considered | At least 1 rejected alternative with reasoning |
+
+### Step 3: Cross-Cutting Verification
+
+These sections MUST be non-empty regardless of task domain:
+
+| Section | Acceptable Content |
+|---------|-------------------|
+| **Security Considerations** | Specific requirements from `rules/security.md` OR `N/A — [valid justification]` |
+| **Testing Strategy** | At least unit test plan with coverage target OR `N/A — [valid justification]` |
+| **Documentation Updates** | Specific docs listed OR `N/A — no docs affected` |
+
+**Unacceptable**: Empty section, placeholder text, section completely missing.
+
+### Step 4: Specificity Audit
+
+Verify that implementation steps are actionable, not vague:
+
+| Vague (FAIL) | Specific (PASS) |
+|-------------|-----------------|
+| "Update the component" | "Add `onSubmit` handler to `src/components/LoginForm.tsx`" |
+| "Add tests" | "Create `tests/auth.test.js` with login success/failure cases" |
+| "Fix the bug" | "Change line 42 of `lib/parser.js`: replace `==` with `===`" |
+| "Style the UI" | "Add Tailwind classes `flex gap-4 p-6` to `Header.tsx`" |
+
+**Rule**: Every implementation step MUST include a file path.
+
+### Step 5: Completeness Scoring
+
+Calculate the score using the rubric from `plan-schema.md`:
+
+**Tier 1 Scoring** (60 points max):
+
+| Section | Points |
+|---------|--------|
+| Context & Problem Statement | 10 |
+| Goals & Non-Goals | 10 |
+| Implementation Steps | 10 |
+| Testing Strategy | 10 |
+| Security Considerations | 10 |
+| Risks & Mitigations | 5 |
+| Success Criteria | 5 |
+
+**Tier 2 Scoring** (20 additional points):
+
+| Section | Points |
+|---------|--------|
+| Architecture Impact | 4 |
+| API / Data Model Changes | 3 |
+| Rollback Strategy | 3 |
+| Observability | 2 |
+| Performance Impact | 2 |
+| Documentation Updates | 2 |
+| Dependencies | 2 |
+| Alternatives Considered | 2 |
+
+**Score Rules**:
+- Section present and substantively populated = full points
+- Section present but placeholder/minimal = half points
+- Section missing = 0 points
+- "N/A" with valid justification = full points
+
+**Domain Enhancement Scoring** (bonus/penalty on top of tier score):
+- For each domain in `matchedDomains` from the loading engine:
+  - Domain enhancer section present and substantive = **+2 bonus points**
+  - Domain matched but enhancer section missing = **-2 penalty points**
+  - Domain matched with "N/A — [valid reason]" = no bonus, no penalty
+- Maximum domain bonus: +6 points (3 domains × 2 points)
+- Domain scoring does not change the pass threshold — it provides additional quality signal
+
+### Step 6: Verdict
+
+| Condition | Verdict | Action |
+|-----------|---------|--------|
+| Score >= 70% of tier max | **PASS** | Present plan to user with score |
+| Score < 70% of tier max | **REVISE** | Identify gaps, revise, re-validate |
+
+**Revision Protocol**:
+1. Identify the specific missing or weak sections
+2. Provide targeted instructions to the planner for revision
+3. Re-run validation after revision
+4. Maximum 2 revision cycles — then present with warnings
+
+---
+
+## Output Format
+
+After validation, append to the plan:
+
+```markdown
+## Plan Quality Assessment
+
+**Task Size**: [Trivial/Medium/Large]
+**Quality Score**: [X]/[max] ([percentage]%) [+N domain bonus / -N domain penalty]
+**Verdict**: [PASS/REVISE]
+
+### Validation Results
+
+| Check | Status |
+|-------|--------|
+| Schema Compliance | [sections present]/[sections required] |
+| Cross-Cutting Concerns | [All addressed / Missing: X, Y] |
+| Specificity Audit | [All steps have file paths / X steps lack paths] |
+| Domain Enhancement | [N domains matched, N enhancer sections present] |
+| Rules Consulted | [list of rule files referenced] |
+| Matched Domains | [list from loading engine] |
+```
+
+---
+
+## Integration
+
+- **Invoked by**: `/plan` workflow (step 3.5, between plan creation and user presentation)
+- **Depends on**: `plan-schema.md` for scoring rubric, `domain-enhancers.md` for domain sections
+- **Feeds into**: Plan quality score shown to user alongside the plan
+- **Learning**: Quality scores are logged to `.agent/contexts/plan-quality-log.md` for adaptive improvement
+
+---
+
+## Principles
+
+1. **Validate, don't block**: The goal is quality improvement, not gatekeeping. After 2 revision cycles, present the plan with warnings rather than blocking indefinitely.
+2. **Score transparently**: The user sees the quality score and understands what was checked.
+3. **Learn from outcomes**: Post-implementation retrospectives compare predicted vs. actual to calibrate future scoring.
+4. **Cross-cutting is non-negotiable**: Security, testing, and documentation sections must ALWAYS be addressed. This is the single most impactful quality gate.

package/.agent/skills/plan-writing/SKILL.md

@@ -42,17 +42,29 @@ Framework for breaking down work into clear, actionable tasks with verification
 
 ## Planning Principles
 
-> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
+> 🔴 **NO fixed templates. Each plan's CONTENT is UNIQUE to the task.**
+> ✅ **Every plan MUST satisfy the quality schema in `plan-schema.md`.**
+> Dynamic content within a consistent structure = the standard.
 
-### Principle 1: Keep It SHORT
+### Principle 1: Right-Size to Task Tier
 
-| ❌ Wrong                    | ✅ Right              |
-| --------------------------- | --------------------- |
-| 50 tasks with sub-sub-tasks | 5-10 clear tasks max  |
-| Every micro-step listed     | Only actionable items |
-| Verbose descriptions        | One-line per task     |
+Plan length MUST match task complexity:
 
-> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
+| Task Tier | Max Sections | Max Tasks | Guideline |
+| --------- | ------------ | --------- | --------- |
+| **Trivial** (1-2 files) | Tier 1 only (7 sections) | 5-8 tasks | ~1 page — concise, no specialist synthesis |
+| **Medium** (3-10 files) | Tier 1 + Tier 2 (15 sections) | 8-15 tasks | 2-3 pages — includes specialist input |
+| **Large** (10+ files) | Tier 1 + Tier 2 + domains (15+ sections) | 15-25 tasks | 3-5 pages — full multi-agent synthesis |
+
+| ❌ Wrong | ✅ Right |
+| -------- | -------- |
+| 50 tasks with sub-sub-tasks | Right-sized task count per tier |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+| Large task crammed into 1 page | Large task gets full Tier 2 coverage |
+| Trivial task with 15 sections | Trivial task uses Tier 1 only |
+
+> **Rule:** Trivial tasks stay concise (~1 page). Medium/Large tasks expand to cover all required tier sections. Never sacrifice completeness for brevity on complex tasks.
 
 ---
 
@@ -98,6 +110,33 @@ Framework for breaking down work into clear, actionable tasks with verification
 
 ---
 
+### Principle 5: Cross-Cutting Concerns Are Mandatory
+
+Every plan MUST explicitly address:
+
+1. **Security**: Reference `.agent/rules/security.md` — what security implications exist?
+2. **Testing**: Reference `.agent/rules/testing.md` — what test types are needed? Coverage targets?
+3. **Documentation**: Reference `.agent/rules/documentation.md` — which docs need updating?
+
+If a concern is genuinely not applicable, state `N/A — [one-line justification]`.
+
+**NEVER silently omit these sections.** Silent omission is a plan defect.
+
+---
+
+### Principle 6: Schema Compliance
+
+Every plan MUST satisfy the quality schema defined in `plan-schema.md`:
+
+- **Tier 1** sections are ALWAYS required. Omitting any Tier 1 section is a plan defect.
+- **Tier 2** sections are required for Medium and Large tasks (3+ files or 1+ hours).
+- Before presenting a plan, validate it against the schema checklist.
+- Plans scoring below 70% of their tier maximum must be revised before presentation.
+
+See also: `domain-enhancers.md` for domain-specific plan sections.
+
+---
+
 ## Plan Structure (Minimal)
 
 ```markdown

package/.agent/skills/plan-writing/domain-enhancers.md

@@ -0,0 +1,114 @@
+# Domain-Specific Plan Enhancers
+
+> When the loading engine matches specific domains for a task, the planner
+> MUST include the corresponding domain-specific sections below.
+> These sections are additive to the base plan schema (Tier 1 + Tier 2).
+
+---
+
+## Frontend Domain
+
+**Triggered when**: `frontend` domain matched (keywords: react, next.js, component, css, ui, ux, etc.)
+
+Include in plan:
+
+- **Accessibility (WCAG 2.1 AA)**: Identify components requiring ARIA labels, keyboard navigation, screen reader support, color contrast compliance
+- **Responsive Design**: Specify breakpoints to test (mobile 375px, tablet 768px, desktop 1280px), identify layout changes per breakpoint
+- **Bundle Size Impact**: Estimate size of new dependencies, identify tree-shaking opportunities, consider code splitting for new routes
+- **Core Web Vitals**: Assess impact on LCP (largest contentful paint), CLS (cumulative layout shift), INP (interaction to next paint)
+- **Component Composition**: Specify component hierarchy, prop interfaces, state management approach (local vs. global)
+
+---
+
+## Backend Domain
+
+**Triggered when**: `backend` domain matched (keywords: api, server, node, express, middleware, endpoint, etc.)
+
+Include in plan:
+
+- **API Contract**: Define request/response schemas (Zod validation), HTTP methods, status codes, error response format
+- **Error Handling**: Specify error response structure, error codes, client-facing messages vs. internal logging
+- **Rate Limiting**: Identify endpoints requiring rate limits, specify limits (requests/minute/user), throttling strategy
+- **Middleware Chain**: Document new middleware additions, execution order, impact on existing middleware stack
+- **Database Interaction**: Query patterns (parameterized), transaction boundaries, connection pooling impact
+
+---
+
+## Database Domain
+
+**Triggered when**: `database` domain matched (keywords: database, sql, migration, schema, query, orm, etc.)
+
+Include in plan:
+
+- **Migration Rollback**: Write both up and down migrations, test rollback procedure before deploying
+- **Index Impact Analysis**: Identify queries affected by schema changes, recommend index additions/removals, estimate query performance impact
+- **Data Integrity**: Define constraints (foreign keys, unique, not null, check), cascade behavior for deletions
+- **Backup Verification**: Verify backup exists before destructive migrations, test restore procedure for critical tables
+- **Query Performance**: Benchmark key queries before and after changes, set acceptable latency thresholds
+
+---
+
+## DevOps Domain
+
+**Triggered when**: `devops` domain matched (keywords: deploy, ci, cd, docker, kubernetes, pipeline, etc.)
+
+Include in plan:
+
+- **Infrastructure Changes**: Specify IaC modifications (Dockerfile, docker-compose, CI config), environment variable additions
+- **Monitoring & Alerting**: Define new metrics to track, alerting thresholds, dashboard updates
+- **Progressive Rollout**: Strategy for deployment (canary → staged → full), rollback triggers, health check endpoints
+- **Runbook Updates**: Document operational procedures for the new functionality, incident response steps
+- **Environment Parity**: Verify changes work across dev, staging, and production environments
+
+---
+
+## Security Domain
+
+**Triggered when**: `security` domain matched (keywords or implicit triggers: auth, login, signup, form, payment, etc.)
+
+Include in plan (in addition to mandatory security considerations):
+
+- **Threat Model (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege — assess each for the change
+- **Authentication Flow Impact**: How the change affects login, session management, token lifecycle
+- **Data Classification**: Identify data sensitivity levels (public, internal, confidential, restricted), storage and transmission requirements
+- **Compliance Requirements**: GDPR/CCPA implications (data minimization, consent, right to erasure)
+- **Secret Management**: New secrets required, rotation policy, storage mechanism (environment variables only)
+
+---
+
+## Performance Domain
+
+**Triggered when**: `performance` domain matched (keywords: slow, optimize, speed, bundle, lighthouse, cache, etc.)
+
+Include in plan:
+
+- **Performance Budget**: Define acceptable thresholds (page load time, API response time, memory usage)
+- **Profiling Strategy**: Tools and methods to measure before/after (Lighthouse, Chrome DevTools, load testing)
+- **Caching Strategy**: Cache layers (browser, CDN, application, database), TTL values, invalidation approach
+- **Lazy Loading**: Identify resources for deferred loading, intersection observer patterns, dynamic imports
+- **Benchmarking**: Define benchmark suite, baseline measurements, regression detection
+
+---
+
+## Mobile Domain
+
+**Triggered when**: `mobile` domain matched (keywords: mobile, react native, expo, ios, android, etc.)
+
+Include in plan:
+
+- **Platform Parity**: Identify iOS vs. Android differences in behavior, UI, or API access
+- **Offline Support**: Define offline behavior, data sync strategy, conflict resolution
+- **App Store Guidelines**: Compliance with Apple/Google review guidelines for the feature
+- **Native Modules**: Bridge requirements, native module dependencies, build configuration changes
+- **Device Testing**: Target device matrix, screen size variations, OS version compatibility
+
+---
+
+## Usage
+
+The planner reads this file when domain-specific sections are needed:
+
+1. Loading engine returns `matchedDomains` array
+2. For each matched domain, include the corresponding enhancer section
+3. Domain sections are added AFTER the base plan schema sections
+4. Multiple domains can be active simultaneously (e.g., frontend + backend for a full-stack feature)

package/.agent/skills/plan-writing/plan-retrospective.md

@@ -0,0 +1,116 @@
+# Plan Retrospective
+
+> Post-implementation review protocol for measuring plan accuracy
+> and feeding learnings back into future plan generation.
+
+---
+
+## Overview
+
+After a planned task reaches the VERIFY phase (all implementation complete, tests running), this retrospective compares the original plan against actual implementation to identify accuracy gaps and improve future planning.
+
+---
+
+## When to Run
+
+- **Primary Trigger**: The `plan-complete` hook in `.agent/hooks/hooks.json` fires when workflow state transitions to VERIFY phase
+- **Manual Trigger**: User runs `/retrospective` on a completed plan
+- **Data Flow**: The hook reads the original plan file (`docs/PLAN-{slug}.md`), compares against `git diff --name-only` from the plan's creation timestamp, then appends results to `.agent/contexts/plan-quality-log.md`
+- **Frequency**: After every planned task completes implementation
+- **Blocking**: No — this is a learning activity, not a quality gate (severity: medium, onFailure: log)
+- **Planner Integration**: The planner reads `plan-quality-log.md` during Requirements Analysis (Step 1) to adjust estimates and predictions for future plans
+
+---
+
+## Retrospective Dimensions
+
+### 1. File Prediction Accuracy
+
+Compare files listed in the plan vs. files actually modified:
+
+| Metric | Measurement |
+|--------|-------------|
+| **Files Predicted** | Count of unique file paths in the plan |
+| **Files Actually Modified** | Count from `git diff --name-only` against plan start |
+| **Prediction Accuracy** | Predicted / Actual (percentage) |
+| **Surprise Files** | Files modified that were NOT in the plan |
+| **Unused Predictions** | Files in the plan that were NOT modified |
+
+### 2. Task Completeness
+
+| Metric | Measurement |
+|--------|-------------|
+| **Tasks Planned** | Count of implementation steps in original plan |
+| **Tasks Completed** | Steps that matched actual work |
+| **Surprise Tasks** | Work done that wasn't in the plan |
+| **Dropped Tasks** | Planned tasks that turned out unnecessary |
+| **Completeness Score** | (Completed - Surprise) / Planned |
+
+### 3. Estimate Accuracy
+
+| Metric | Measurement |
+|--------|-------------|
+| **Estimated Effort** | Total hours from plan |
+| **Actual Effort** | Approximate actual time spent |
+| **Drift** | Actual / Estimated (ratio; 1.0 = perfect) |
+| **Drift Direction** | Over-estimated / Under-estimated / Accurate |
+
+### 4. Risk Prediction
+
+| Metric | Measurement |
+|--------|-------------|
+| **Risks Identified** | Count of risks in plan |
+| **Risks Materialized** | Planned risks that actually occurred |
+| **Surprise Risks** | Unplanned risks that emerged |
+| **Risk Prediction Rate** | Materialized / (Materialized + Surprise) |
+
+### 5. Specialist Contribution Value
+
+| Specialist | Contribution Accurate? | Key Insight That Helped |
+|-----------|----------------------|------------------------|
+| Architect | Yes/No/Partial | [what was most useful] |
+| Security-Reviewer | Yes/No/Partial | [what was most useful] |
+| TDD-Guide | Yes/No/Partial | [what was most useful] |
+
+---
+
+## Output Format
+
+Append one row to `.agent/contexts/plan-quality-log.md`:
+
+```markdown
+| [date] | [plan name] | [quality score] | [files predicted] | [files actual] | [surprise count] | [estimate drift] | [key learning] |
+```
+
+### Key Learning Format
+
+Capture the single most important learning in one sentence:
+
+**Good examples**:
+- "Auth tasks consistently require middleware changes not predicted in plans"
+- "Database migration effort was 2x underestimated due to index rebuilding"
+- "Frontend plans should always include accessibility testing as a task"
+
+**Bad examples**:
+- "The plan was good" (not actionable)
+- "Everything went as expected" (no learning value)
+
+---
+
+## Adaptive Feedback
+
+The planner agent reads `plan-quality-log.md` at the start of each planning session to:
+
+1. **Adjust estimates**: If historical drift is consistently 1.5x, multiply estimates by 1.5
+2. **Predict surprise files**: If auth tasks consistently miss middleware, proactively include middleware files
+3. **Weight risks**: If certain risk categories historically materialize, elevate their severity
+4. **Improve domain sections**: If specific domain enhancer sections are consistently unhelpful, deprioritize them
+5. **Value specialists**: If security-reviewer contributions are consistently accurate, weight their input more heavily
+
+---
+
+## Example Retrospective Entry
+
+```
+| 2026-03-16 | PLAN-user-auth | 72/80 | 8 | 11 | 3 (middleware, session config, error handler) | 1.4x | Auth plans should include middleware and session store files by default |
+```

package/.agent/skills/plan-writing/plan-schema.md

@@ -0,0 +1,119 @@
+# Plan Quality Schema
+
+> Defines the mandatory structure and scoring rubric for implementation plans.
+> Every plan produced by the `/plan` workflow MUST satisfy this schema.
+
+---
+
+## Task Size Classification
+
+Before applying the schema, classify the task:
+
+| Size | Criteria | Required Tiers |
+|------|----------|----------------|
+| **Trivial** | 1-2 files, <30 minutes estimated effort | Tier 1 only |
+| **Medium** | 3-10 files, 1-4 hours estimated effort | Tier 1 + Tier 2 |
+| **Large** | 10+ files, multi-day effort | Tier 1 + Tier 2 + architect consultation |
+
+---
+
+## Tier 1 — Always Required
+
+Every plan, regardless of task size, MUST include these sections:
+
+| # | Section | Description | Points |
+|---|---------|-------------|--------|
+| 1 | **Context & Problem Statement** | Why this change is needed. 2-3 sentences covering the problem, impact, and motivation. | 10 |
+| 2 | **Goals & Non-Goals** | What the plan achieves (goals) and what is explicitly out of scope (non-goals). Prevents scope creep. | 10 |
+| 3 | **Implementation Steps** | Ordered tasks with exact file paths, specific actions, and verification criteria per step. | 10 |
+| 4 | **Testing Strategy** | Test types required (unit, integration, e2e), coverage targets, key test cases. Reference `.agent/rules/testing.md`. | 10 |
+| 5 | **Security Considerations** | Applicable security requirements from `.agent/rules/security.md`. If genuinely not applicable, state `N/A — [one-line justification]`. | 10 |
+| 6 | **Risks & Mitigations** | At least 1 risk with severity (Low/Medium/High) and concrete mitigation strategy. | 5 |
+| 7 | **Success Criteria** | Measurable definition of done. Checkboxes with specific, verifiable outcomes. | 5 |
+
+**Tier 1 Maximum: 60 points**
+
+---
+
+## Tier 2 — Required for Medium & Large Tasks
+
+Plans for tasks affecting 3+ files or requiring 1+ hours MUST also include:
+
+| # | Section | Description | Points |
+|---|---------|-------------|--------|
+| 8 | **Architecture Impact** | Affected components/modules, integration points, dependency changes. Include component diagram for Large tasks. | 4 |
+| 9 | **API / Data Model Changes** | New or modified endpoints, request/response schemas, database schema changes. | 3 |
+| 10 | **Rollback Strategy** | How to undo the change if deployment fails or defects are discovered post-release. | 3 |
+| 11 | **Observability** | Logging additions, metrics to track, alerting changes, monitoring dashboards affected. | 2 |
+| 12 | **Performance Impact** | Bundle size changes, query performance, latency estimates, memory usage. | 2 |
+| 13 | **Documentation Updates** | Which docs need changing (ROADMAP, CHANGELOG, README, API docs, ADRs). Reference `.agent/rules/documentation.md`. | 2 |
+| 14 | **Dependencies** | What blocks this work (prerequisites). What depends on this work (downstream impact). | 2 |
+| 15 | **Alternatives Considered** | At least 1 rejected approach with reasoning for why the chosen approach is superior. | 2 |
+
+**Tier 2 Maximum: 20 points (added to Tier 1)**
+
+---
+
+## Domain Enhancement Scoring
+
+When the loading engine matches specific domains (e.g., frontend, backend, security), the corresponding domain enhancer sections from `domain-enhancers.md` MUST be included. Domain sections are scored as **bonus points** on top of the tier maximum:
+
+| Condition | Scoring Impact |
+|-----------|---------------|
+| Domain matched and enhancer section present + substantive | +2 bonus points per domain |
+| Domain matched but enhancer section missing | -2 penalty per missing domain (deducted from tier score) |
+| Domain matched with "N/A — [valid reason]" | No bonus, no penalty |
+| No domains matched | No impact |
+
+**Maximum domain bonus**: +6 points (3 domains × 2 points each).
+
+Domain scoring does NOT change the pass threshold — it provides additional quality signal. A plan can PASS without domain bonuses but will be penalized if matched domains are ignored.
+
+---
+
+## Scoring
+
+| Task Size | Max Score | Pass Threshold (70%) |
+|-----------|-----------|---------------------|
+| Trivial | 60 | 42 |
+| Medium | 80 | 56 |
+| Large | 100 | 70 |
+
+**Score Calculation**:
+- A section earns full points when present and substantively populated
+- A section earns zero points when missing or contains only placeholder text
+- "N/A" with a valid justification counts as populated (earns full points)
+
+**Verdict**:
+- **PASS**: Score >= 70% of tier maximum
+- **REVISE**: Score < 70% — identify missing sections and revise (max 2 revision cycles)
+
+---
+
+## Cross-Cutting Mandate
+
+Regardless of task domain, these sections MUST be substantively addressed in every plan:
+
+1. **Security Considerations** (Tier 1, #5) — Reference `.agent/rules/security.md`
+2. **Testing Strategy** (Tier 1, #4) — Reference `.agent/rules/testing.md`
+3. **Documentation Updates** (Tier 2, #13) — Reference `.agent/rules/documentation.md`
+
+If a cross-cutting section is genuinely not applicable, the plan MUST state:
+```
+N/A — [specific reason this concern does not apply to this task]
+```
+
+**NEVER silently omit a cross-cutting section.** Silent omission is a plan defect.
+
+---
+
+## Alignment Verification
+
+Every plan MUST include an alignment check against operating constraints:
+
+| Check | Question |
+|-------|----------|
+| Operating Constraints | Does this respect Trust > Optimization? |
+| Existing Patterns | Does this follow project conventions? |
+| Rules Consulted | Which rule files were reviewed? |
+| Coding Style | Does this comply with `.agent/rules/coding-style.md`? |