Codd Evolve

CoDD Evolve — Conversational Brownfield Evolution

Take a Lord-style natural-language change request and automatically determine which design docs, lexicon entries, source files, and tests must move together to preserve CoDD coherence. The user expresses intent; this skill figures out scope.

When to Use

• The user describes a functional change to an existing system, not a bug
• Examples of trigger phrases:
  • "Add a logout button to the admin nav"
  • "Change course management — courses should be a shared master with separate delivery targets"
  • "Restructure the learner list to drill down: facility → learner → course → progress"
  • "Remove the daily log append step from the karo completion flow"
  • "受講者管理を施設フィルター起点に変更"
• The user does NOT want to think about which design docs, lexicon entries, or source files to touch
• The project is already CoDD-initialized (has codd/codd.yaml and at least the design doc layout)

Do NOT use this for:

• Greenfield generation from scratch — use /codd-init then /codd-generate
• Pure bug fix where requirements and design are correct — use codd fix or codd fix [PHENOMENON]
• Reverse-engineering an undocumented codebase — use codd extract (or /codd-restore)
• Single-doc impact analysis only — use /codd-impact
• Code-only refactoring with no behavioral change — use codd propagate

What This Does — Role Separation

This skill makes a single contract explicit:

The user must never have to choose which file to touch.

Workflow

Step 1 — Confirm prerequisites

Before starting, verify:

1. Current directory is a CoDD-initialized project (codd/codd.yaml exists)
2. Working tree is clean OR uncommitted changes are intentional (warn the user otherwise)
3. codd verify currently passes (red 0) — if not, the user should fix existing red first, per codd fix [PHENOMENON] prerequisite
4. If codd verify returns exit 0 with silent stdout (a known mode where build/test phases run but emit no text), fall back to codd dag verify for an explicit red-count readout. Use both signals when the baseline is uncertain.
5. If runtime verification_test nodes are unsuitable for the local environment, prefer an explicit config or skip over silent omission: set verify.verification_timeout.total_seconds / per_node_seconds, or run codd verify --runtime --runtime-skip verification-test and preserve the reported SKIP evidence.

If red exists, STOP and surface it. Do not attempt to layer new changes on a red baseline.

Step 2 — Parse intent and classify

Classify the user's request into one of:

If classification is ambiguous, ask one clarifying question (see Step 3).

Drift detection against existing design

After classification, scan the affected design docs for pre-existing references to the proposed change. Examples:

• The intent says "add logout button to admin nav," but ux_design.md already documents a logout entry in the tenant_admin / learner sidebars (impl never caught up).
• The intent says "add delivery_target table," but database_design.md has an Open Question (OQ-DB-NN) that proposes the same structure under a different name.

When such drift is found, classify it:

• Drift A — broader-than-intent: design covers more roles/cases than the intent. Either (a) flag to the user and ask whether to keep the narrower intent or align to the design, or (b) treat as a Step 3 gate-5 "ambiguous scope" trigger.
• Drift B — design proposed, impl absent: an Open Question or TODO matches the new intent. Reuse the existing terminology and mark the OQ as resolved.
• Drift C — contradiction: design says X, intent says not-X. Halt as a Step 3 gate-3 "structural impossibility."

Recording drift in the report prevents silent vocabulary divergence on subsequent evolutions.

Step 3 — Stop-and-ask gates

Stop and ask the user only when one of these triggers fires:

1. New lexicon term required. The change introduces a vocabulary not in project_lexicon.yaml. Ask: "I'll add <term> to the lexicon meaning <definition>. OK?"
2. Breaking change to existing behavior. Existing users / callers will see different output. Ask: "This changes how <X> behaves for existing users. Is breaking change acceptable?"
3. Coherence is structurally impossible. Requirements would contradict an existing invariant. Surface the contradiction; do not proceed silently.
4. Cross-cutting scope explosion. The change touches more design docs than the user likely realized (rule of thumb: >4 docs). Confirm scope before charging ahead.
5. Ambiguous role/scope. "Add logout" — for which role? Or all roles? Ask once.
6. 1:N/N:N data model change -> UI page topology. When Step 2 classification == change_data_model and the change introduces a 1:N or N:N relation that does not yet have an operation_flow.ui_pattern declared for the parent/child pair, ask which UI topology should be used: (a) single screen with everything inline, (b) master-detail on the parent's detail page, (c) drilldown to a dedicated child page, or (d) defer to LLM auto-decision, which is discouraged and may trigger a ui_coherence warning. Record the answer to requirements/*.md operation_flow as a new Operation entry.

Pre-approved branch

If the orchestrator (multi-agent system, task YAML, prior conversation, etc.) already records explicit approval for one or more of these gates, treat them as immediately confirmed without re-asking. Examples:

• A task YAML that states "lexicon delivery_target is pre-approved" → skip gate 1 prompt for that term.
• A task YAML that states "breaking change accepted by stakeholder" → skip gate 2 prompt.
• A handoff that names the role explicitly ("update only the central_admin nav") → skip gate 5 prompt; if drift detection (Step 2) finds the design covers more roles, surface the drift in the report instead of blocking.
• A task YAML that states "ui_pattern for <child> is master_detail" → skip gate 6 prompt and record the pre-approved topology source in the report.

Always record in the report which gates were short-circuited and the source of the prior approval. Pre-approval never applies to gate 3 (structural impossibility) — that always halts.

Do not ask the user:

• Which file to touch
• Which doc to update
• What order to do things in
• What to name a commit
• Which version to bump

Step 4 — Execute the coherence chain

Once intent is confirmed, execute in this order (each step's output feeds the next):

1. Update requirements/*.md
   - Append new requirement / modify existing / mark deprecated
   - Preserve frontmatter, traceability IDs, and Bloom levels

2. Update affected design/*.md docs (in dependency order)
   - Determine order via codd's existing CEG (depends_on graph)
   - Update each doc body to reflect the new requirement
   - Preserve frontmatter exactly

3. Update project_lexicon.yaml if needed
   - Only after user confirmed in Step 3
   - Keep alphabetical / grouped order if existing convention

4. Run codd implement to (re)generate source from updated design
   - For incremental change, codd implement updates only affected modules
   - For pure data model changes, also generate migration files if applicable
   - **Generated-code impact check**: if the project keeps codd-generated output under `src/generated/**` (or equivalent), classify whether the change requires regenerating those modules or whether it stays in the hand-edited area (handlers, UI, tests). Record the decision in the report so future evolutions know whether `src/generated/**` was intentionally untouched.
   - **Prerequisite (cmd_345 K-3)**: if any design doc declares `operation_flow`, ensure `codd.yaml` has `ai_commands.impl_step_derive` set. Without it, `operation_flow_hint()` is silently skipped and declared UI patterns will not influence generation. Verify with `grep impl_step_derive codd/codd.yaml`; CoDD also emits a `WARNING` on stderr when this gap is detected.

5. Update tests
   - Tests for new requirements MUST be added (no silent skip)
   - Tests for removed requirements MUST be removed
   - Tests for changed behavior MUST be updated

6. Run codd verify
   - MUST reach red 0
   - If red persists, see Step 5 (failure handling)

7. Run codd propagate
   - Final cross-doc consistency pass
   - Catches any drift between source-as-implemented and design-as-written

8. Runtime smoke verification (MANDATORY — not optional)
   - Run `codd verify --runtime` from the project root and paste or link the generated runtime smoke report.
   - `codd verify --runtime` automatically checks:
     a. Local DB up via `codd.yaml runtime_smoke.db_check.command`
     b. Dev server up via `runtime_smoke.dev_server.url`
     c. Smoke connectivity via `runtime_smoke.smoke_connectivity[]`
     d. Real-browser E2E via `runtime_smoke.e2e.command`
     e. Opt-in CRUD flow reflection via `runtime.crud_flow_targets[]`
   - For every visible or `operation_flow` command/control/action that mutates
     state or emits a business result, add or reuse a CRUD flow target, an
     `action-outcome` target, or an equivalent E2E proving: trigger → server
     acceptance/mutation → re-fetch or observable outcome → visible reflection,
     persistence, emitted event, expected output, or absence as appropriate. A
     green GET smoke alone is not enough for mutating actions.
   - All results are written with raw logs to `reports/runtime_smoke_{{timestamp}}.md` unless the project config overrides the path.
   - Self-reported runtime smoke is not acceptable evidence. If `--runtime-skip <category>` is used, including `--runtime-skip verification-test` or `--runtime-skip crud-flow`, the report must show the skipped category explicitly and it must never be described as passed.
   - If `codd verify --runtime` fails: the change is NOT done. Either fix forward or revert. Reporting done with the server down is a critical violation of CoDD coherence.

Never reorder these steps. Doc updates always precede source updates — that is the CoDD coherence invariant. Step 8 is the actual completion gate — Steps 1-7 produce coherent artifacts, Step 8 proves the user can actually use them.

Step 5 — Failure handling

If codd verify red persists after Step 4:

1. First retry: run codd fix once to let CoDD self-repair common issues
2. Second attempt: surface the failing test output, classify the cause
   • Test outdated → update test
   • Design contradicts requirement → ask user
   • Implementation cannot match design → ask user whether design is wrong or impl approach is wrong
3. Do not loop more than 3 times. After 3 failed attempts, STOP and report to user with concrete diagnostics

Local database unavailable

change_data_model work often needs a migration command (e.g. prisma migrate dev) that requires a running local database. If the DB cannot be reached:

1. Do not apply the migration to any non-local target (e.g. staging, production VPS).
2. Author the migration by hand under the project's migrations directory (Prisma example: prisma/migrations/<timestamp>_<slug>/migration.sql). Mirror the conventions of existing files in that directory (column order, index naming, foreign-key style).
3. Validate the schema declaration alone — prisma validate (or the framework's equivalent) — to confirm the model file parses and matches expectations.
4. Note in the report that the migration is generated but unapplied, and call out what the user must run locally once the DB is back (prisma migrate deploy for hand-authored migrations).
5. Treat this as an acceptable verification path only when codd dag verify and codd propagate also pass; it is not a substitute for full codd verify when build/test phases are reachable.

Step 6 — Report

Generate a concise summary for the user:

Updated:
- requirements/foo.md (added: ログアウト機能)
- design/auth_design.md (added: NextAuth signOut handler)
- design/ux_design.md (added: 中央管理者ナビ Logout ボタン)
- src/components/AdminNav.tsx (added)
- src/app/api/auth/signout/route.ts (new)
- tests/e2e/logout.spec.ts (new)

Lexicon: no changes
Verify: red 0 ✅
Propagate: 0 drift ✅
Runtime smoke (Step 8):
  - `codd verify --runtime`: ✅
  - report: reports/runtime_smoke_20260517_210000.md
Done: ✅ (user can open the app and use the new feature)

If any Step 8 check is ❌, the change is NOT done. Either fix forward or revert; never report done with the runtime broken.

Suggest a commit message and offer to commit. Do not auto-commit unless the user confirms.