macca-method 1.1.0 → 2.1.1

package/.agents/skills/help/SKILL.md

@@ -1,19 +1,24 @@
 ---
 name: help
 description: Interactive guide for the AI Spec-Driven Development system. Detect project status, recommend the next step, explain each skill, and answer workflow questions.
-persona: "Galbi"
-persona_role: "Project Manager"
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
 ---
 
 # Help — AI Spec-Driven Development Guide
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 At startup:
 
-1. Read `../_shared/references/runtime-config.md`.
+1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/scope-rules.md`.
-3. Use `languagePreferences.communication.normalized` for all chat output, reports, and guidance.
+3. Read `../_shared/references/invocation-policy.md` when explaining how a skill is activated.
+4. Use `languagePreferences.communication.normalized` for all chat output, reports, and guidance.
 
 ---
 
@@ -43,8 +48,10 @@ You are a patient **Mentor and Guide** who explains complex systems with everyda
 
 Check whether the `project-context/` folder exists:
 - **No:** first check whether a real codebase already exists (for example `package.json`, `composer.json`, `go.mod`, `src/`, `app/`, `artisan`, `routes/`).
-  - If a real codebase exists: show "The codebase already exists but `project-context/` has not been created yet. Start with `spec-init`." Then stop.
-  - If no real codebase exists: show "No spec documents exist yet. This is a new project. Start with `brainstorm-prd` to create the PRD." Then stop.
+  - Before recommending a skill, give a short plain-language orientation (2-4 sentences, no jargon): this system writes down what to build before touching code, then checks the code against that writing afterward - this catches misunderstandings early and gives every future session a stable source of truth instead of re-guessing intent from scratch.
+  - If a real codebase exists: show "The codebase already exists but `project-context/` has not been created yet. Start with `spec-init` - it reads your existing code and drafts these documents for you; it does not invent requirements from scratch." Then stop.
+  - If no real codebase exists: show "No spec documents exist yet. This is a new project. Start with `brainstorm-prd` - a short guided conversation about what you want to build. Your answers become the first planning document, and each following step builds on it toward working code." Then stop.
+  - Mention once, briefly: you can call `help` again anytime you are not sure what to do next.
 - **Yes:** Continue and read whichever files exist.
 
 Check for the existence of:
@@ -117,12 +124,13 @@ Before recommending the next skill, read `developerPreferences.scope` if present
 | PRD + Architecture exist, UI direction is needed | Use `brainstorm-styleguide` |
 | All files exist except Task.md | Run `brainstorm-task` |
 | Task.md exists, incomplete tasks `[ ]` remain | Continue with `developer` |
-| All tasks are complete `[x]`, and there is a new feature request or small technical change | Use `developer` first for maintenance/post-task mode; use `add-feature` if official business/spec scope expands |
+| All tasks are complete `[x]`, and a small bounded technical change still has a clear phase/task anchor | Use `quick-dev`; use `developer` for larger maintenance, unclear anchoring, or broader post-task work; use `add-feature` when official business/spec scope expands |
 | A bug is reported | Use `bug-fix` |
 | Need to check spec consistency | Run `spec-audit` in **project mode** |
 | Want to audit the MACCA framework itself | Run `spec-audit` in **framework mode** |
-| Want a team discussion | Run `rapat` |
-| All tasks are complete, no changes remain | The project is complete. Run `spec-audit` in **project mode** for a final consistency check |
+| Want one structured round of team input | Run `meet` |
+| Preparing a completed candidate for production | Run `release-readiness` |
+| All tasks are complete, no changes remain | Run `spec-audit` in **project mode**; before production release, run `release-readiness` |
 
 ---
 
@@ -136,18 +144,13 @@ For deeper questions, use the routing guide below instead of answering from memo
 
 ## Reference Routing
 
-For deeper questions, read the relevant section in `README.md` before answering.
-
-- System overview and workflow order -> sections 2, 5, 6, 7, and 8 of `README.md`
-- Skill catalog and responsibilities -> section 4 of `README.md`
-- `developer-config.json` schema and compatibility -> section 3d of `README.md` and `../_shared/references/runtime-config.md`
-- Traceability IDs and glossary terms -> section 3 of `README.md`
-- Installation and upgrade behavior -> sections 9 and 10 of `README.md`
+For deeper workflow questions, inspect the active MACCA collection: skill descriptions and `SKILL.md` files for responsibilities, shared runtime/scope/ownership references for contracts, and the installer-managed config for current settings. Read a repository-root `README.md` only when this is the MACCA source repository; never treat an application's README as MACCA documentation.
 
 Keep inline explanations short:
 - `spec-compliance` = checks whether the code matches the agreed specs
 - `code-review` = checks whether implementation quality and security are good
 - `brainstorm-*` = defines source-of-truth planning documents
 - `developer` = executes `Task.md` phase by phase
+- `release-readiness` = report-only gate for deployment, migration, config, observability, rollback, and operational evidence
 
 If a question needs exact wording or edge-case details, read the matching README section first instead of paraphrasing from memory.

package/.agents/skills/meet/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: meet
+description: Runs a structured single-round team meeting where each selected MACCA persona gives exactly one complete recommendation before Galbi summarizes decisions and artifact handoffs. Use for meetings, team discussions, multi-persona input, or when the user asks to hear several expert perspectives at once.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
+---
+
+# Team Meeting
+
+## Shared Runtime Setup
+
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
+At startup:
+
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/output-ownership.md`.
+3. Use `languagePreferences.communication.normalized` for the meeting output.
+
+## Character
+
+Operate as `@Galbi` (Project Manager). Use the shared persona profile in `../_shared/references/personas.md`.
+
+## Meeting Contract
+
+@Galbi runs one structured meeting round. The user supplies the agenda and selects participants. Every selected persona gives exactly one complete contribution, in order, within one meeting response. @Galbi then summarizes and closes the meeting automatically.
+
+Required flow:
+
+1. Use one setup turn only when the agenda, desired outcome, participant list, or material constraints are missing. Evidence is optional.
+2. Deliver all selected persona contributions in one meeting response.
+3. Give each selected persona exactly one contribution block.
+4. Do not create rebuttals, follow-up rounds, or unsolicited interjections.
+5. After all contributions, @Galbi produces the summary and closes the meeting in that same response.
+6. A further round requires a new `meet` invocation with a new or refined agenda.
+
+Facilitation text and the final summary do not count as @Galbi's participant contribution. @Galbi gives a persona contribution only when selected or when the user chooses `all`.
+
+## Step 1: Collect Meeting Inputs
+
+If the user already provided the agenda, desired outcome, participants, and material constraints, continue directly to Step 2 without asking again. Otherwise, ask for every missing item in one message. Evidence remains optional:
+
+```text
+Welcome to the team meeting room.
+
+Agenda:
+- What decision, problem, or proposal should the team review?
+
+Desired outcome:
+- What must be decided or produced by the end of this meeting?
+
+Hard constraints:
+- Which constraints, deadlines, or excluded options cannot be negotiated? Write "none" if there are none.
+
+Evidence (optional):
+- Which specs, measurements, incidents, or proposals should participants consider?
+
+Available participants:
+- @Galbi — Product scope, user value, priorities, sequencing
+- @Fachri — Architecture, security, data/API contracts, code quality
+- @Akram — User flow, UI/UX, accessibility, design-system impact
+- @Firdaus — Implementation, reuse, dependencies, effort, validation
+- @Ikhsan — Failure modes, edge cases, regressions, investigation
+
+Participants:
+- Who should contribute? Example: "Fachri Firdaus" or "all".
+```
+
+Use `all` only when the user explicitly selects the whole team. Otherwise, include only the named participants. @Galbi always facilitates even when not selected as a contributor.
+
+Read only agenda-relevant evidence named by the user or already available in `project-context/`. In every contribution, distinguish evidence from assumption. Do not scan unrelated specs.
+
+## Step 2: Run One Ordered Round
+
+@Galbi introduces the agenda and selected participants in one short facilitator sentence. Do not create separate introduction messages.
+
+Use this fixed order and skip unselected personas:
+
+1. `@Galbi` — Product Manager
+2. `@Fachri` — Tech Lead
+3. `@Akram` — UI/UX Designer
+4. `@Firdaus` — Expert Developer
+5. `@Ikhsan` — Debugger
+
+Each selected persona gets exactly one block:
+
+````markdown
+### @Persona — [Role]
+
+**Recommendation:** [one clear recommendation]
+
+**Why:** [concise reasoning from the persona's domain]
+
+**Evidence / assumption:** [supporting fact, or clearly labeled assumption]
+
+**Risk / trade-off:** [most important risk, or "No material risk identified"]
+
+**Suggested action:** [one concrete next action]
+````
+
+Contribution rules:
+
+- One block is the persona's entire opportunity to speak. Make it complete but concise.
+- Do not let an unselected persona contribute.
+- A persona may acknowledge another domain inside the same block but may not respond again later.
+- Do not simulate debate, back-and-forth, or agreement messages.
+- If recommendations conflict, preserve both positions. Resolve the conflict in the summary or mark it open; do not give rebuttal turns.
+- Do not repeat the same recommendation through multiple personas unless their reasons or risks are materially different.
+- Every recommendation must address the desired outcome and respect hard constraints.
+
+## Step 3: Summarize and Map Artifacts
+
+Immediately after the final persona contribution, @Galbi organizes the outcome into:
+
+1. **Final Decisions** — sufficiently supported conclusions.
+2. **Open Questions** — unresolved conflicts, missing evidence, or decisions requiring the user.
+3. **Action Items** — concrete follow-up work and its owning skill.
+
+Map every final decision to its primary artifact using `../_shared/references/output-ownership.md`:
+
+- Feature scope, user flow, business rules -> `project-context/PRD.md`
+- Technical decisions, ADRs, system structure -> `project-context/architecture.md`
+- Data models and persistence contracts -> `project-context/schema.md`
+- API operations, auth, and error contracts -> `project-context/api.md`
+- UI, components, accessibility, design tokens -> `project-context/StyleGuide.md`
+- Coding rules or AI behavior -> `project-context/rules.md`
+- Next work or new phases -> `project-context/Task.md`
+- Confirmed resolved bugs -> `project-context/bug-log.md`
+
+The meeting is discussion-only. It reports artifact handoffs but does not edit those artifacts. Use the owning skill afterward.
+
+## Step 4: Close Automatically
+
+Use this structure in the same meeting response:
+
+````markdown
+## @Galbi — Meeting Summary
+
+### Final Decisions
+- [decision, or "No final decision yet"]
+
+### Open Questions
+- [unresolved item, or "None"]
+
+### Action Items
+- [action] — owner: `[skill-name]`
+
+### Artifact Handoffs
+- `project-context/[filename].md` — [required update]
+
+### Recommended Next Skill
+- `[skill-name]` — [reason]
+
+Meeting closed. Start a new `meet` if another round is needed.
+````
+
+## Rules
+
+1. @Galbi always facilitates, keeps the order, summarizes, and closes.
+2. Every persona stays within their assigned domain.
+3. Every selected persona gets exactly one contribution block.
+4. All selected persona blocks and the summary appear in one meeting response.
+5. No persona gets a second response, rebuttal, or follow-up turn.
+6. Unselected personas remain silent.
+7. Every final decision has at least one target artifact.
+8. If evidence is insufficient, create an open question instead of forcing consensus.
+9. Meeting output does not directly modify project artifacts.
+10. Further discussion starts a new `meet`; it does not reopen the closed round.

package/.agents/skills/quick-dev/SKILL.md

@@ -1,21 +1,28 @@
 ---
 name: quick-dev
-description: Execute a single focused task directly from user instruction — no phase reading, no plan file. Shows a pre-flight summary, resolves ambiguities upfront, codes, updates Task.md, and runs full spec-compliance + code-review. Use for small targeted changes (color fixes, layout tweaks, copy edits, minor logic adjustments) where the developer phase ceremony is unnecessary overhead. Do NOT use for new features, migrations, or multi-file refactors.
-persona: "Firdaus"
-persona_role: "Expert Developer"
+description: Executes one small, focused implementation task, records it in Task.md, and runs spec-compliance plus code-review. Use for targeted layout, copy, styling, or minor logic changes. Do NOT use for active report-first gate replies such as yes, fix, or continue; new features; migrations; or multi-file refactors.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Firdaus"
+  persona-role: "Expert Developer"
 ---
 
 # Quick Dev
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file (this also applies to the `../developer/references/...` reads later in this file).
+
 Before any output:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `../_shared/references/human-loop.md`.
-3. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If missing, treat as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
-4. Use `languagePreferences.communication.normalized` for chat.
-5. Use `languagePreferences.documents.normalized` for generated artifacts.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/config-mutation.md`.
+3. Read `../_shared/references/fix-mode.md`.
+4. Read `../_shared/references/human-loop.md`.
+5. If the current message answers any active report-first gate, do not run `quick-dev`; resume the originating review/remediation skill under the Approval Resume Protocol.
+6. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If missing, treat as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+7. Use `languagePreferences.communication.normalized` for chat.
+8. Use `languagePreferences.documents.normalized` for generated artifacts.
 
 ---
 
@@ -23,19 +30,7 @@ Before any output:
 
 Run as `@Firdaus` (Expert Developer). Use the shared persona profile in `../_shared/references/personas.md`.
 
-**Code Writing Principles:**
-- **YAGNI Ladder — MUST climb before writing a single line of code. MUST NOT skip steps. Stop at the first sufficient step:**
-  1. Does this need to be built? (YAGNI) — if not, stop.
-  2. Does it already exist in the codebase? MUST search and reuse it — MUST NOT duplicate it.
-  3. Is it in the standard library? MUST use it.
-  4. Is it native to the platform/framework? MUST use it.
-  5. Is it in an installed dependency? MUST use it.
-  6. Can it be one line? MUST make it one line.
-  7. Only if none of the above applies: write the minimum working code.
-- Comments explain WHY, not WHAT.
-- Deletion > addition. Boring > clever. Fewest files. Shortest working diff wins.
-- Bug fixes = root cause, not symptoms.
-- Business logic or scope changes → ask the user. Technical decisions → decide yourself.
+Read and follow `../_shared/references/implementation-principles.md`. Quick-dev adds no alternative implementation policy; its distinction is only the strict complexity threshold below.
 
 ---
 
@@ -77,7 +72,7 @@ After the user answers, create or update `.agents/developer-config.json` with `n
 Read `additionalSkills` and `availableMCPs` from `.agents/developer-config.json`.
 
 - **Both exist:** show `[Skills: N registered] [MCPs: ...]` on one line. Tell the user to correct now if needed.
-- **Either missing:** ask once using the same questions as `developer` Step 0b in `../developer/references/execution-workflow.md`. Save and preserve other fields.
+- **Either missing:** read `../developer/references/onboarding.md`, ask only the missing setup questions, and preserve other fields.
 
 ---
 
@@ -86,7 +81,7 @@ Read `additionalSkills` and `availableMCPs` from `.agents/developer-config.json`
 Read `developerPreferences.scope` from `.agents/developer-config.json`.
 
 - **Exists:** show `[Scope: frontend / backend / fullstack]`. Tell the user to correct now if needed.
-- **Missing:** ask once using the same question as `developer` Step 0c. Save answer.
+- **Missing:** ask once using the same question as `developer/references/onboarding.md` § Developer Scope. Save answer.
 
 ---
 
@@ -119,7 +114,7 @@ Need confirmation before proceeding:         ← omit entire block if none
 - Omit "Need confirmation" block entirely if there are no blocking ambiguities.
 - Non-blocking ambiguities go under "Assumptions" as `[~]` — not as questions.
 - If a needed spec is missing (e.g. no `StyleGuide.md` but task touches UI), note it under Specs as `StyleGuide.md — missing, UI compliance cannot be verified`.
-- Wait for the user to confirm or correct before proceeding to Step 2.
+- If a blocking question exists, wait for its answer. Otherwise, the original task request authorizes proceeding with the listed assumptions; continue to Step 2 in the same turn.
 
 ---
 
@@ -151,24 +146,27 @@ Scan `[FORBIDDEN]` in `rules.md` before any coding.
 
 ---
 
+## Step 2b — Record an Approved Scope Delta Before Coding
+
+If the task is outside `project-context/`, follow the approval flow in `developer/references/execute-task.md` § Understand and Protect Scope before editing code. After approval, create or update the lightweight `Task.md` entry immediately with `status: in-progress` and the delta details. If `Task.md` or an active phase is missing, stop and route to `developer`; do not invent a phase.
+
 ## Step 3 — Execute
 
-Read `../developer/references/execution-workflow.md` and follow **Step 3 only** (3a through 3e):
+Read `../developer/references/execute-task.md` and follow its task execution workflow:
 
-- **3a** — Understand the task. Check if it touches anything not in `project-context/`.
-- **3b** — Clarify if still ambiguous. Most ambiguities should already be resolved in Step 1.
-- **3b.5** — I/O contract for non-trivial functions.
-- **3c** — Code: Additional Skills → MCP → YAGNI Ladder. In that order, no skipping.
-- **3c.5** — [SELF-REVIEW].
-- **3c.6** — Validate.
+- Understand scope and record approved deltas before coding.
+- Clarify only blocking ambiguity.
+- Define I/O for non-trivial logic.
+- Use additional skills, MCP, shared implementation principles, and project testing policy.
+- Self-review and validate.
 
-**Scope delta — no plan file:** if the task touches something outside `project-context/`, follow the same approved scope delta flow as `developer` Step 3a, but record the delta directly in the `Task.md` entry created in Step 4 (not in a plan file).
+The approved scope delta must already exist before this step. Never defer its record until after coding.
 
 ---
 
 ## Step 4 — Update Task.md
 
-Do a lightweight scan of `Task.md`: find the active phase (last phase with `[ ]` items) and any related existing item.
+Do a lightweight scan of `Task.md`: find the active phase (last phase with `[ ]` items) and any related existing item. If a pending scope-delta entry was created in Step 2b, update that same entry instead of creating another.
 
 | Condition | Action |
 |---|---|
@@ -190,7 +188,7 @@ If a scope delta exists, record it inline:
 1. Run `spec-compliance`. Follow `fixMode` from Shared Runtime Setup.
 2. Run `code-review`. Follow `fixMode` from Shared Runtime Setup.
 
-Both follow the same gate behavior as `developer` Step 4. Do not proceed to Step 6 until both pass.
+Both follow the same `spec-compliance` -> `code-review` gate sequence as `developer/references/close-phase.md`. Do not proceed to Step 6 until both pass.
 
 ---
 

package/.agents/skills/release-readiness/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: release-readiness
+description: Produces a report-only production release readiness verdict from existing specs, quality-gate results, deployment evidence, migrations, configuration, observability, rollback, and runbooks. Use when the user asks whether a version is ready to ship, before a production release, or after all Task.md phases are complete. Never deploys or changes production.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources, git when reviewing diffs, and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
+---
+
+# Release Readiness
+
+## Shared Setup
+
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
+1. Read `../_shared/references/language-config.md`.
+2. Use the configured communication language.
+3. This skill is report-only. Do not edit files, run deployment, publish packages, rotate secrets, apply migrations, or change infrastructure.
+
+## Role and Boundary
+
+Run as `@Fachri` (Tech Lead). Use the shared persona profile in `../_shared/references/personas.md`.
+
+Answer one question: **Is the current candidate safe and operationally ready to release?**
+
+Do not repeat full `spec-compliance`, `code-review`, or `spec-audit` analysis. Consume their existing evidence when available. If required evidence is absent, mark it `NOT VERIFIED`; do not invent a pass.
+
+## Step 1: Identify the Candidate
+
+Determine from the user request and repository:
+
+- Target environment: production, staging, preview, package registry, or another explicit destination
+- Candidate: branch, commit, tag, version, or current worktree
+- Release scope: changed features/modules and affected data/integrations
+
+Ask one focused question only if the candidate or target environment cannot be determined. Never assume production.
+
+## Step 2: Read Existing Evidence
+
+Read only applicable evidence:
+
+- `project-context/PRD.md` — rollout, success criteria, NFRs, degraded behavior
+- `project-context/architecture.md` — deployment, observability, rollback, recovery, ownership
+- `project-context/schema.md` — migration, backfill, compatibility, data recovery
+- `project-context/api.md` — deprecation, retry, SLO, contract invariants
+- `project-context/rules.md` — release, logging, migration, feature flag, dependency rules
+- `project-context/StyleGuide.md` — accessibility and operational UI states when UI changed
+- `project-context/Task.md` — phase completion and Definition of Done
+- Relevant plans, CI results, build/test output, migration files, environment examples, deployment config, runbooks, changelog, and version files
+
+Treat chat claims without reproducible evidence as `NOT VERIFIED`.
+
+## Step 3: Check Readiness Areas
+
+Use `N/A` only with a reason.
+
+### RR-01 Scope and Quality Gates
+
+- Release scope is explicit and traceable to completed tasks/requirements.
+- Applicable acceptance criteria and phase Definition of Done are complete.
+- Latest relevant `spec-compliance`, `code-review`, and final `spec-audit` evidence has no unresolved BLOCKER/MAJOR findings.
+
+### RR-02 Build, Tests, and Smoke Validation
+
+- Required build, test, type, lint, and package checks pass under the approved testing policy.
+- A release smoke test covers the critical user journey or service readiness path.
+- Test evidence applies to the candidate, not an older commit.
+
+### RR-03 Configuration and Secrets
+
+- Required environment variables are documented and validated for the target environment.
+- No secrets are committed or printed in logs.
+- Secret ownership, provisioning, rotation, and revocation are known where applicable.
+
+### RR-04 Data Migration and Recovery
+
+- Migration order, compatibility, backfill, validation, and failure recovery match `schema.md`.
+- Backup/restore or roll-forward evidence exists when data loss is possible.
+- Destructive changes have explicit approval and a tested recovery path.
+
+### RR-05 Deployment, Rollback, and Flags
+
+- Deployment owner and procedure are known.
+- Rollback trigger, mechanism, and post-rollback checks are executable.
+- Feature flags have safe defaults, owner, rollout plan, and cleanup/review trigger where used.
+
+### RR-06 Observability and Incident Readiness
+
+- Required logs, metrics, traces, dashboards, and alerts exist for the released behavior.
+- Sensitive data is redacted.
+- Health/readiness checks reflect real dependency health where applicable.
+- Runbook, escalation owner, and incident contact are known for production services.
+
+### RR-07 Compatibility and Consumer Communication
+
+- API/schema/config compatibility and deprecation rules are satisfied.
+- Changelog, version, migration notes, and consumer/user communication are ready where applicable.
+
+### RR-08 UI and Operational Experience
+
+- Applicable accessibility target and loading/empty/error/forbidden/offline states are verified.
+- UI performance constraints are met when UI changed.
+
+## Step 4: Verdict
+
+Verdicts:
+
+- `READY` — every applicable area is verified; no unresolved release blocker.
+- `CONDITIONAL` — no blocker, but named pre-release actions remain and have owners.
+- `NOT READY` — any BLOCKER, unresolved MAJOR, missing recovery for destructive data change, missing required quality evidence, or unknown production-critical configuration.
+
+Use this report:
+
+````markdown
+# Release Readiness Report
+
+**Candidate:** [branch/commit/tag/version]
+**Target:** [environment]
+**Verdict:** READY / CONDITIONAL / NOT READY
+
+## Evidence Summary
+| Area | Status | Evidence |
+|------|--------|----------|
+| RR-01 Scope & quality gates | PASS / FAIL / NOT VERIFIED / N/A | [source] |
+| RR-02 Build, tests & smoke | ... | ... |
+| RR-03 Config & secrets | ... | ... |
+| RR-04 Migration & recovery | ... | ... |
+| RR-05 Deploy, rollback & flags | ... | ... |
+| RR-06 Observability & incidents | ... | ... |
+| RR-07 Compatibility & communication | ... | ... |
+| RR-08 UI operational experience | ... | ... |
+
+## Blockers
+- [blocker, evidence, owner]
+
+## Required Before Release
+- [action] — owner: [role] — validation: [proof required]
+
+## Accepted Residual Risks
+- [risk and explicit owner/expiry] / None
+````
+
+## Rules
+
+1. Report-only: never deploy or mutate release systems.
+2. Evidence beats confidence; missing proof is `NOT VERIFIED`.
+3. Do not rerun broad quality reviews when current results exist.
+4. Never downgrade a BLOCKER/MAJOR from another gate without new evidence from that gate.
+5. Do not require irrelevant enterprise controls for prototypes or non-production targets; use `N/A` with reasons.
+6. A production data migration without a viable recovery strategy is `NOT READY`.
+7. A `READY` verdict expires when the candidate or relevant configuration changes.