agents-templated 2.2.20 → 2.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.2.20",
+  "version": "2.2.22",
   "description": "Technology-agnostic development template with multi-AI agent support (Cursor, Copilot, VSCode, Gemini), security-first patterns, and comprehensive testing guidelines",
   "main": "index.js",
   "bin": {
@@ -39,6 +39,7 @@
     "lib",
     "agents",
     "templates",
+    "templates/.claude/agents",
     "templates/presets",
     "index.js",
     "README.md",

package/templates/CLAUDE.md

@@ -50,23 +50,23 @@ Skills add capability only. They must not override security, testing, or core co
 
 | Subagent | Path | Invoke when... |
 |----------|------|----------------|
-| planner | `.claude/agents/planner.md` | Breaking down features into phased execution plans |
-| architect | `.claude/agents/architect.md` | System design decisions, ADRs, trade-off analysis |
-| backend-specialist | `.claude/agents/backend-specialist.md` | Implementing backend features, APIs, and server-side logic |
-| frontend-specialist | `.claude/agents/frontend-specialist.md` | Implementing UI, interaction, accessibility, and client-side state |
-| database-migrator | `.claude/agents/database-migrator.md` | Planning safe migrations with validation and rollback gates |
-| deployment-specialist | `.claude/agents/deployment-specialist.md` | Deployment planning, config validation, rollout, and rollback |
-| performance-specialist | `.claude/agents/performance-specialist.md` | Bottleneck diagnosis (mode=profile) or load threshold validation (mode=load) |
-| qa-specialist | `.claude/agents/qa-specialist.md` | Pre-implementation test planning (mode=design) or post-implementation validation (mode=validation) |
-| e2e-runner | `.claude/agents/e2e-runner.md` | Running end-to-end test suites and reporting flakiness |
-| code-reviewer | `.claude/agents/code-reviewer.md` | Reviewing code for quality, correctness, and severity prioritization |
-| security-reviewer | `.claude/agents/security-reviewer.md` | Security risk gating — invoke when authn/authz, secrets, or new public endpoints are touched |
-| refactor-cleaner | `.claude/agents/refactor-cleaner.md` | Removing dead code and unused dependencies in approved cleanup windows |
-| build-error-resolver | `.claude/agents/build-error-resolver.md` | Fixing compile, type, lint, and import failures only |
-| compatibility-checker | `.claude/agents/compatibility-checker.md` | API contract compatibility and breaking-change verdicts |
-| dependency-auditor | `.claude/agents/dependency-auditor.md` | Auditing package risk, CVEs, and upgrade hygiene |
-| doc-updater | `.claude/agents/doc-updater.md` | Syncing docs and READMEs after accepted behavior changes |
-| test-data-builder | `.claude/agents/test-data-builder.md` | Building deterministic fixtures, seeds, and mock datasets |
+| planner | `.claude/agents/planner.md` | Break work into phased, testable execution plans when implementation scope must be sequenced, not when code fixes are already scoped and ready. |
+| architect | `.claude/agents/architect.md` | Define system-level design decisions and ADR-ready trade-offs when architecture choices are material, not for routine implementation tasks. |
+| backend-specialist | `.claude/agents/backend-specialist.md` | Implement backend APIs, services, and persistence logic after planning is complete, not for build-fix or compatibility-governance ownership. |
+| frontend-specialist | `.claude/agents/frontend-specialist.md` | Implement UI behavior, accessibility, and client interactions for scoped frontend phases, not for backend implementation or release-governance tasks. |
+| database-migrator | `.claude/agents/database-migrator.md` | Plan and validate schema/data migrations with rollback safety when persistence contracts change, not for general feature implementation. |
+| deployment-specialist | `.claude/agents/deployment-specialist.md` | Plan deployment execution and rollback-safe rollout gates when release movement is required, not for feature coding or QA verdict ownership. |
+| performance-specialist | `.claude/agents/performance-specialist.md` | Run explicit profile or load evaluations for performance decisions when orchestrator mode is declared, not for ambiguous or mode-inferred requests. |
+| qa-specialist | `.claude/agents/qa-specialist.md` | Execute design-mode test planning or validation-mode regression verdicts with explicit orchestrator mode, not as a self-selected mixed QA function. |
+| e2e-runner | `.claude/agents/e2e-runner.md` | Execute end-to-end journey validation with deterministic setup when integration behavior must be proven, not for unit-level or design-only testing. |
+| code-reviewer | `.claude/agents/code-reviewer.md` | Review diffs for correctness, risk, and policy alignment before merge, not for dependency-risk auditing or documentation synchronization ownership. |
+| security-reviewer | `.claude/agents/security-reviewer.md` | Perform conditional security review when trigger thresholds are met, not as an always-on mandatory step when risk signals are absent. |
+| refactor-cleaner | `.claude/agents/refactor-cleaner.md` | Remove dead code and simplify safely in bounded increments when cleanup is requested, not for repeated build-repair loops beyond retry policy. |
+| build-error-resolver | `.claude/agents/build-error-resolver.md` | Fix build, type, and lint failures with minimal diffs when the build is red, not for broad feature work or architectural refactors. |
+| compatibility-checker | `.claude/agents/compatibility-checker.md` | Assess backward compatibility and contract-version impacts when interfaces change, not for code implementation or release documentation updates. |
+| dependency-auditor | `.claude/agents/dependency-auditor.md` | Audit dependency risk, CVEs, and upgrade hygiene when package risk is in scope, not for code-style review or feature implementation. |
+| doc-updater | `.claude/agents/doc-updater.md` | Synchronize README and architecture documentation with implemented behavior after changes land, not for deciding code correctness or dependency risk. |
+| test-data-builder | `.claude/agents/test-data-builder.md` | Generate deterministic fixtures, seeds, and synthetic datasets for downstream validation/load phases, not for feature coding or final QA verdict ownership. |
 
 ### Subagent Auto-Routing Rules
 

package/templates/agents/commands/README.md

@@ -1,144 +0,0 @@
-# Deterministic Slash Command Contracts
-
-This directory is the modular source of truth for slash-command execution contracts.
-
-- Global protocol and safety framework: `AGENTS.MD` → `Deterministic Slash Command System Standard`
-- Global response schema: `.claude/commands/SCHEMA.md`
-- Command contracts:
-  - `plan.md`
-  - `task.md`
-  - `fix.md`
-  - `audit.md`
-  - `perf.md`
-  - `test.md`
-  - `pr.md`
-  - `release.md`
-  - `docs.md`
-  - `problem-map.md`
-  - `scope-shape.md`
-  - `arch-check.md`
-  - `ux-bar.md`
-  - `debug-track.md`
-  - `test-data.md`
-  - `risk-review.md`
-  - `release-ready.md`
-  - `learn-loop.md`
-
-Execution requirements:
-- Parse slash commands deterministically.
-- Return structured output only.
-- No conversational fallback in slash mode.
-- Enforce destructive confirmation token: `CONFIRM-DESTRUCTIVE:<target>`.
-- Enforce unique command purpose for each primary workflow command.
-
-## Command Integrity Guards
-
-- Primary workflow commands must have unique purpose identifiers.
-- Duplicate command purpose definitions fail CLI startup validation.
-- Deprecated aliases are not part of the active command surface.
-
-## Publish Inclusion
-
-The npm package scaffolds command contracts into `.claude/commands/`.
-
-Template source path in this repository:
-
-- `templates/agents/commands/`
-
-## Workflow Command Mapping
-
-Use these lifecycle commands as the recommended specialist sequence:
-
-- `problem-map` -> `plan.md`
-- `scope-shape` -> `plan.md`
-- `arch-check` -> `plan.md`
-- `ux-bar` -> `plan.md`
-- `debug-track` -> `fix.md`
-- `test-data` -> `test.md`
-- `risk-review` -> `audit.md`
-- `perf` -> `perf.md`
-- `release-ready` -> `release.md`
-- `docs` -> `docs.md`
-- `learn-loop` -> `task.md`
-
-The CLI command `agents-templated workflow` prints this lifecycle in order:
-
-Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect
-
-## Non-Overlap Routing Boundaries
-
-The orchestrator preserves explicit ownership boundaries between specialist decision surfaces.
-
-- Backend implementation remains separate from tactical build and compatibility remediation:
-  - `backend-specialist` owns implementation.
-  - `build-error-resolver` owns build/type/lint fixes.
-  - `compatibility-checker` owns external contract compatibility decisions.
-- Review chain remains ordered and non-overlapping:
-  - `code-reviewer` -> `dependency-auditor` -> `doc-updater`
-  - `doc-updater` should not absorb review or dependency decisions.
-
-## Test Data Handoff Routing
-
-The orchestrator routes deterministic data preparation through `test-data-builder` and then hands off to downstream consumers.
-
-- Upstream routes:
-  - `qa-design` and backend/database-oriented phases can route to `test-data-builder`.
-- Downstream consumers:
-  - `qa-specialist(mode=validation)`
-  - `e2e-runner`
-  - `performance-specialist(mode=load)`
-- Handoff metadata is emitted in orchestration output as `handoff_inputs`.
-
-## Deprecated Alias Redirects
-
-Deprecated workflow command aliases are supported as non-breaking redirects with deterministic notices.
-
-| Deprecated | Redirects To |
-|------------|--------------|
-| `quality-gate` | `risk-review` |
-| `perf-scan` | `perf` |
-| `docs-sync` | `docs` |
-
-Alias policy:
-
-- Redirects preserve behavior of the canonical command.
-- CLI prints a deprecation notice on each alias invocation.
-- New automation should use canonical command names only.
-
-## Automatic Orchestration
-
-The CLI command `agents-templated orchestrate "<objective>"` builds an automatic multi-phase handoff plan across specialist tracks.
-
-- Uses static scenario routing first.
-- Falls back to keyword intent matching when no explicit scenario override is provided.
-- Emits deterministic structured output compatible with `SCHEMA.md` in `slash-command-auto` mode.
-- Stops the chain on `blocked` or `failed` state and returns a populated `stop_condition`.
-- Includes scenario-conditioned optional delegation to existing subagents (for example `security-reviewer`, `e2e-runner`, `dependency-auditor`) without making them mandatory.
-
-Example:
-
-`agents-templated orchestrate "build auth api and dashboard" --json`
-
-## Mode-Locked Specialist Invocation
-
-The orchestrator must pass explicit mode values for mode-locked specialists and must never allow self-selection.
-
-Mode-locked specialists:
-
-- `qa-specialist`
-  - Allowed modes: `design`, `validation`
-  - Required invocation examples:
-    - `qa-specialist(mode=design, input=<spec>)`
-    - `qa-specialist(mode=validation, input=<changed_files + scope>)`
-- `performance-specialist`
-  - Allowed modes: `profile`, `load`
-  - Required invocation examples:
-    - `performance-specialist(mode=profile, input=<scope>)`
-    - `performance-specialist(mode=load, input=<scope + thresholds>)`
-
-HALT rules:
-
-- Missing mode -> stop execution and return a clarification request.
-- Unsupported mode -> stop execution and return allowed values.
-- Mode inference from context is forbidden.
-

package/templates/agents/commands/SCHEMA.md

@@ -1,42 +0,0 @@
-# Slash Command Output Schema
-
-All slash command responses MUST include the following top-level fields:
-
-- `command`
-- `execution_id`
-- `mode`
-- `status`
-- `inputs`
-- `prechecks`
-- `execution_log`
-- `artifacts`
-- `risks`
-- `safety_checks`
-- `stop_condition`
-- `next_action`
-
-Optional orchestration fields:
-- `artifacts.scenario`
-- `artifacts.scenario_reason`
-- `artifacts.phases[]`
-- `artifacts.phases[].optional_subagents[]`
-- `artifacts.phases[].invocation_mode`
-- `artifacts.phases[].handoff_inputs[]`
-- `artifacts.deprecation_notices[]`
-- `execution_log[].orchestration_phase`
-- `execution_log[].routed_subagent`
-- `execution_log[].routed_track`
-- `execution_log[].routed_skills`
-- `execution_log[].optional_subagents[]`
-- `execution_log[].invocation_mode`
-- `execution_log[].handoff_inputs[]`
-
-Constraints:
-- `mode` MUST be one of: `slash-command`, `slash-command-auto`.
-- `status` MUST be one of: `completed`, `blocked`, `failed`.
-- If a field value is unknown, set it to `null`.
-- Unknown or malformed slash commands MUST return structured error output and stop.
-- In `slash-command-auto` mode, orchestration chains MUST stop on first `blocked` or `failed` phase and return a non-null `stop_condition`.
-- Optional subagent delegation MUST remain non-required and scenario-conditioned.
-- For `qa-specialist` and `performance-specialist`, orchestrator invocation MUST include an explicit mode.
-- Missing or unsupported mode for mode-locked specialists MUST return `status=blocked` with a non-null `stop_condition`.

package/templates/agents/commands/arch-check.md

@@ -1,58 +0,0 @@
-# /arch-check
-
-## A. Intent
-Validate architecture readiness and implementation constraints before build begins.
-
-## B. When to Use
-- Use after scope lock and before implementation starts.
-- Do not use for post-release retrospectives.
-
-## C. Context Assumptions
-- Scope is frozen for current increment.
-- Architecture options are documented.
-- Test strategy can be defined.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `architecture_goal` | string | "multi-tenant API isolation" |
-| `design_options` | string[] | ["shared schema", "schema-per-tenant"] |
-| `design_artifact` | artifact | ADR doc, sequence diagram |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] design options are comparable
-- [ ] key edge cases are identified
-- [ ] test strategy exists for selected design
-
-## F. Execution Flow
-1. Review architecture options and constraints.
-2. Evaluate edge cases and failure modes.
-3. Validate selected option against requirements.
-4. Decision point ->
-   - condition A -> critical gap found -> block readiness
-   - condition B ->  no critical gaps -> continue.
-5. Build architecture decision and test implications.
-6. Emit architecture readiness report.
-
-## G. Output Schema
-
-```json
-{
-  "architecture_id": "string",
-  "decisions": ["array","of","strings"],
-  "risk_level": "low | medium | high",
-  "blocker": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- selected architecture lacks testable validation path
-- critical edge case has no mitigation
-
-## J. Safety Constraints
-- Hard block: hard block on architecture with unresolved critical failure modes
-- Warn only: warn when non-critical tradeoffs are accepted

package/templates/agents/commands/audit.md

@@ -1,58 +0,0 @@
-# /audit
-
-## A. Intent
-Produce a deterministic risk and compliance audit with prioritized findings.
-
-## B. When to Use
-- Use before release or for targeted quality/security reviews.
-- Do not use as a substitute for implementation planning.
-
-## C. Context Assumptions
-- Audit scope is defined.
-- Relevant artifacts are available.
-- Severity rubric is agreed.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `audit_scope` | string | "authentication flows" |
-| `checklist` | string[] | ["security", "tests", "rollback"] |
-| `evidence_set` | artifact | PR diff, logs, reports |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] scope is explicit
-- [ ] evidence artifacts are accessible
-- [ ] severity model is available
-
-## F. Execution Flow
-1. Collect scoped evidence and standards.
-2. Evaluate checks against evidence.
-3. Classify findings by severity.
-4. Decision point ->
-   - condition A -> critical unresolved finding -> block recommendation
-   - condition B ->  no critical blocker -> continue.
-5. Assemble remediation actions and owners.
-6. Emit audit report.
-
-## G. Output Schema
-
-```json
-{
-  "audit_id": "string",
-  "findings": ["array","of","strings"],
-  "severity": "low | medium | high",
-  "blocker": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- scope cannot be determined
-- critical evidence is missing
-
-## J. Safety Constraints
-- Hard block: hard block when critical finding lacks mitigation
-- Warn only: warn when medium findings are deferred

package/templates/agents/commands/debug-track.md

@@ -1,58 +0,0 @@
-# /debug-track
-
-## A. Intent
-Run root-cause-first debugging workflow and guarantee evidence-backed defect diagnosis.
-
-## B. When to Use
-- Use when behavior is broken, failing, or regressing in runtime.
-- Do not use to apply speculative patches without diagnosis.
-
-## C. Context Assumptions
-- Defect symptom is captured.
-- A reproduction path is available or can be derived.
-- Runtime context is accessible.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `defect_symptom` | string | "payment retries loop forever" |
-| `repro_steps` | string[] | ["submit order", "disconnect network"] |
-| `runtime_artifact` | artifact | error logs, trace screenshot, failing test |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] reproduction path is actionable
-- [ ] evidence can be collected at runtime
-- [ ] investigation scope is bounded
-
-## F. Execution Flow
-1. Reproduce issue and capture trace.
-2. Follow execution and state transitions.
-3. Confirm root cause with evidence.
-4. Decision point ->
-   - condition A -> root cause unverified -> continue investigation
-   - condition B ->  verified -> continue.
-5. Draft minimal patch strategy and checks.
-6. Emit debug investigation report.
-
-## G. Output Schema
-
-```json
-{
-  "debug_id": "string",
-  "evidence": ["array","of","strings"],
-  "certainty": "low | medium | high",
-  "root_cause": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- issue cannot be reproduced with available context
-- root cause cannot be evidenced
-
-## J. Safety Constraints
-- Hard block: hard block on symptom-only fixes without diagnosis
-- Warn only: warn when reproduction is intermittent

package/templates/agents/commands/docs.md

@@ -1,58 +0,0 @@
-# /docs
-
-## A. Intent
-Create deterministic documentation outputs aligned with current implementation behavior.
-
-## B. When to Use
-- Use when generating or updating docs as a direct deliverable.
-- Do not use for release decision making.
-
-## C. Context Assumptions
-- Source behavior is known.
-- Target audience is defined.
-- Doc destination is available.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `doc_scope` | string | "API auth endpoints" |
-| `source_refs` | string[] | ["src/auth.ts", "openapi.yaml"] |
-| `doc_artifact` | artifact | existing README path or docs URL |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] scope is explicit
-- [ ] source refs are accessible
-- [ ] destination path is writable
-
-## F. Execution Flow
-1. Collect implementation references.
-2. Draft structured documentation content.
-3. Validate examples and references.
-4. Decision point ->
-   - condition A -> mismatch with implementation -> revise doc content
-   - condition B ->  aligned -> continue.
-5. Assemble final documentation package.
-6. Emit documentation output.
-
-## G. Output Schema
-
-```json
-{
-  "doc_id": "string",
-  "updated_sections": ["array","of","strings"],
-  "confidence": "low | medium | high",
-  "gap": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: file
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- source references are unavailable
-- critical behavior cannot be documented accurately
-
-## J. Safety Constraints
-- Hard block: hard block on knowingly incorrect implementation claims
-- Warn only: warn when sections remain TODO with owner

package/templates/agents/commands/fix.md

@@ -1,58 +0,0 @@
-# /fix
-
-## A. Intent
-Apply the smallest safe code fix with regression evidence and bounded impact.
-
-## B. When to Use
-- Use after root cause is confirmed and a targeted fix is required.
-- Do not use when defect cause is still speculative.
-
-## C. Context Assumptions
-- Issue is reproducible or sufficiently evidenced.
-- Root cause has been identified.
-- Regression checks are available.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `defect_id` | string | "BUG-142" |
-| `affected_paths` | string[] | ["src/auth.ts", "tests/auth.test.ts"] |
-| `evidence` | artifact | stack trace, failing test output, screenshot |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] root cause evidence is present
-- [ ] fix scope is bounded
-- [ ] regression checks are defined
-
-## F. Execution Flow
-1. Read defect evidence and failing paths.
-2. Implement minimal change set.
-3. Run targeted validations.
-4. Decision point ->
-   - condition A -> validation fails -> iterate fix or abort
-   - condition B ->  validation passes -> continue.
-5. Prepare change rationale and impact summary.
-6. Emit fix package with evidence.
-
-## G. Output Schema
-
-```json
-{
-  "fix_id": "string",
-  "changed_files": ["array","of","strings"],
-  "risk": "low | medium | high",
-  "rollback_note": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- no verified root-cause evidence
-- regression validation unavailable for critical path
-
-## J. Safety Constraints
-- Hard block: no broad refactor inside fix-only workflow
-- Warn only: warn when temporary workaround is used

package/templates/agents/commands/learn-loop.md

@@ -1,58 +0,0 @@
-# /learn-loop
-
-## A. Intent
-Capture deterministic retrospective outcomes and convert lessons into next-cycle actions.
-
-## B. When to Use
-- Use after delivery milestones, incidents, or release cycles.
-- Do not use for pre-implementation planning.
-
-## C. Context Assumptions
-- Cycle outcome data is available.
-- Owners for follow-up actions can be assigned.
-- Retrospective scope is defined.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `cycle_name` | string | "Sprint 18" |
-| `observations` | string[] | ["test flakiness", "scope churn"] |
-| `evidence_artifact` | artifact | metrics dashboard, incident notes, PR links |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] observations are evidence-backed
-- [ ] action owners can be assigned
-- [ ] follow-up window is defined
-
-## F. Execution Flow
-1. Collect outcomes, wins, and misses.
-2. Identify root process issues and patterns.
-3. Prioritize actionable improvements.
-4. Decision point ->
-   - condition A -> no actionable item -> request clearer observations
-   - condition B ->  actionable set ready -> continue.
-5. Map actions to owners and timelines.
-6. Emit learn-loop action report.
-
-## G. Output Schema
-
-```json
-{
-  "loop_id": "string",
-  "actions": ["array","of","strings"],
-  "urgency": "low | medium | high",
-  "blocker": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- retrospective inputs are anecdotal without evidence
-- no owner can be assigned to critical actions
-
-## J. Safety Constraints
-- Hard block: hard block on publishing blame-focused output without actionable remediation
-- Warn only: warn when metrics are incomplete but direction is still usable

package/templates/agents/commands/perf.md

@@ -1,58 +0,0 @@
-# /perf
-
-## A. Intent
-Define and execute deterministic performance optimization workflow against known baselines.
-
-## B. When to Use
-- Use when improving latency, throughput, or resource efficiency.
-- Do not use for one-off smoke checks; use /perf-scan for quick regression comparison.
-
-## C. Context Assumptions
-- Baseline metrics exist or can be captured.
-- Performance target is defined.
-- Measurement method is repeatable.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `performance_goal` | string | "p95 latency under 200ms" |
-| `baseline_metrics` | string[] | ["p95=260ms", "cpu=70%"] |
-| `benchmark_artifact` | artifact | profiling report or benchmark output |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] goal is measurable
-- [ ] baseline metric set is present
-- [ ] benchmark method is consistent
-
-## F. Execution Flow
-1. Capture or validate baseline metrics.
-2. Apply targeted optimization changes.
-3. Measure post-change metrics.
-4. Decision point ->
-   - condition A -> target unmet -> iterate optimization
-   - condition B ->  target met -> continue.
-5. Summarize gains, tradeoffs, and risks.
-6. Emit performance optimization report.
-
-## G. Output Schema
-
-```json
-{
-  "perf_run_id": "string",
-  "metrics": ["array","of","strings"],
-  "impact": "low | medium | high",
-  "regression": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- baseline cannot be measured reliably
-- measurement method is non-deterministic
-
-## J. Safety Constraints
-- Hard block: do not trade correctness/security for performance gains
-- Warn only: warn when gains are within noise threshold