macca-method 1.1.0 → 2.1.1

package/.agents/skills/spec-audit/SKILL.md

@@ -1,19 +1,26 @@
 ---
 name: spec-audit
-description: Skill for checking consistency between `project-context/` documents or within the MACCA framework documents themselves. Detects cross-document conflicts, inconsistencies, and ambiguities, not internal writing quality. Reports where the issue is, why it matters, and the exact fix with reasoning.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Audits cross-document consistency in project specs or the MACCA framework and applies explicitly requested corrections. Use for spec alignment, framework drift, and when the user replies yes, fix, continue, or finding IDs to this skill's correction gate.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Spec Audit
 
 ## 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`.
-2. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`. See § Fix Mode Contract in runtime-config.md for the full enforcement rules.
-3. Use `languagePreferences.communication.normalized` for audit reports.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/fix-mode.md`.
+3. Read `../_shared/references/human-loop.md`.
+4. If this message answers this skill's active correction gate, resume directly under the Approval Resume Protocol. Do not rerun startup or the audit.
+5. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+6. Use `languagePreferences.communication.normalized` for audit reports.
 
 ---
 
@@ -41,7 +48,7 @@ You check **between** documents, not inside a single document.
 
 ## Fix Mode
 
-Mode is read in Shared Runtime Setup. Enforcement rules, including the required gate prompt, are in `../_shared/references/runtime-config.md § Fix Mode Contract`.
+Mode is read in Shared Runtime Setup. Enforcement rules, including the required gate prompt, are in `../_shared/references/fix-mode.md`.
 
 To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-config.json`.
 
@@ -92,14 +99,9 @@ Read everything that exists. Note ID patterns if they are used.
 
 ### Framework Mode
 
-Read:
-- `README.md` - workflow, skill list, structure
-- `.agents/skills/*/SKILL.md` - per-skill behavior contracts
-- `.agents/skills/_shared/references/*.md` - shared cross-skill contracts
-- `.agents/skills/*/references/*.md` - reference files with workflow/checklist detail
-- Installation/upgrade scripts if the audit touches them
+Resolve the active skill installation root. First read `_shared/references/skill-catalog.md`, `invocation-policy.md`, `output-ownership.md`, `scope-rules.md`, and the MACCA README only when this is the MACCA source repository.
 
-Read `README.md`, relevant `SKILL.md` files, and relevant reference files. Note instruction conflicts, duplication, workflow inconsistencies, and shared-contract drift.
+Compare compact contracts first. Read full `SKILL.md`, local references/assets, or installer code only for skills/relationships flagged by that comparison or explicitly named by the user. Do not load the entire collection by default. Do not treat an application's README as MACCA documentation.
 
 ---
 
@@ -110,36 +112,44 @@ Read `README.md`, relevant `SKILL.md` files, and relevant reference files. Note
 **SA-01: PRD ↔ architecture**
 - Does the architecture support the PRD NFRs (performance, security, accessibility)?
 - Do the PRD constraints fit the chosen tech stack?
+- Do PRD success metrics map to architecture observability signals where technical instrumentation is required?
+- Does product rollout align with deployment, rollback, and recovery constraints?
 
 **SA-02: PRD ↔ schema**
-- Does every PRD entity have a schema table?
-- Do schema constraints (e.g. "stock ≥ 0") reflect PRD business rules?
+- Does every persisted PRD entity have a datastore-native representation (table, collection, aggregate, node, stream, or equivalent)?
+- Do validation, relationship, consistency, and retention rules reflect PRD business rules?
 
 **SA-03: PRD ↔ api**
-- Does every PRD feature have supporting endpoints?
-- Does `api.md` contain endpoints for PRD non-goals?
+- Does every integration-facing PRD feature have supporting operations (endpoint, query/mutation, procedure, event, or equivalent)?
+- Does `api.md` contain operations for PRD non-goals?
 
 **SA-04: PRD ↔ Task.md**
 - Is every PRD feature mapped to >=1 task?
 - Does Task.md include tasks for features not in the PRD (scope creep)? If the feature is recorded in `## Approved Scope Delta`, mark it as `pending formal spec sync`, not a direct conflict.
 - Do PRD IDs (`FEAT-*`, `BR-*`) appear in Task.md traceability?
+- Do rollout, analytics, degraded behavior, and applicable NFR work have tasks or explicit N/A decisions?
 
 **SA-05: schema ↔ api**
-- Does every request/response field in `api.md` exist in the schema?
+- Does every persisted input/output field in `api.md` map to the data contract where appropriate?
 - Do response types match schema types?
 - If schema/api traceability is used, does it reference real PRD IDs?
+- Do API retry/idempotency assumptions align with schema concurrency and consistency rules?
 
 **SA-06: architecture ↔ rules**
 - Are architectural patterns (e.g. repository pattern) required in `rules.md`?
 - Do any rules conflict with the chosen architecture?
+- Do logging, migration, feature-flag, generated-code, and secret rules exist only when their architecture/schema mechanisms apply?
 
 **SA-07: architecture ↔ schema**
 - Does schema notation fit the architecture's database choice?
 - Is schema style consistent with the architecture's ORM choice?
+- Do tenancy, scale, migration, backup, and recovery assumptions align?
 
 **SA-08: StyleGuide ↔ PRD**
 - Does the CSS framework in StyleGuide match any PRD mention?
 - Are all PRD pages/features covered by StyleGuide components?
+- Do accessibility targets and supported locales match the PRD?
+- Do operational UI states cover PRD failure/degraded behavior where UI is involved?
 
 **SA-09: Task.md ↔ all specs**
 - Do task references point to real spec sections?
@@ -147,6 +157,7 @@ Read `README.md`, relevant `SKILL.md` files, and relevant reference files. Note
 - If task traceability IDs are used, do they reference real PRD/schema/api/rules IDs?
 - Are semi-structured fields (ID, table, `Trace to`, `Traceability ID`) preserved instead of replaced with free text?
 - If new scope exists only in `## Approved Scope Delta`, the audit must separate it as `temporary approval`, not mix it with uncontrolled scope creep.
+- Does each phase Definition of Done include only applicable controls from the specs and quality gates?
 
 ### Framework Mode
 
@@ -175,7 +186,7 @@ Read `README.md`, relevant `SKILL.md` files, and relevant reference files. Note
 - Are there dead ends, loops, or mismatched handoffs?
 
 **SA-F07: Persona consistency**
-- Are personas, roles, and assigned skills consistent across README, `rapat`, and skill frontmatter?
+- Are personas, roles, and assigned skills consistent across README, `meet`, and skill frontmatter?
 - Does any skill name the wrong owner?
 
 **SA-F08: Enforcement & order consistency**
@@ -242,6 +253,11 @@ Findings:
 [List of findings]
 
 Clean: [list of SA-XX / SA-FXX with no issues]
+
+Fix Manifest (only when corrections were requested):
+| Finding | Target document | Exact correction | Validation pair |
+|---|---|---|---|
+| [ID] | `[path]` | [bounded correction] | `[doc A] ↔ [doc B]` |
 ```
 
 If there are no issues:
@@ -250,8 +266,9 @@ If there are no issues:
 ```
 
 **Apply fixes:**
-- `fix-then-report` - apply the recommended fixes only if the user task explicitly asks for document corrections.
-- `report-first` - show the summary. Show the gate prompt from `../_shared/references/runtime-config.md § Fix Mode Contract`. End the response. Apply fixes only after user confirmation in the next message.
+- Audit-only invocation: report only, regardless of `fixMode`; do not offer a mutation gate unless the user requests corrections.
+- Correction requested + `fix-then-report`: apply actionable corrections, validate all affected document pairs, then report.
+- Correction requested + `report-first`: show the summary and shared gate. On approval, resume directly under the Approval Resume Protocol.
 
 ---
 

package/.agents/skills/spec-compliance/SKILL.md

@@ -1,19 +1,27 @@
 ---
 name: spec-compliance
-description: Verify that code matches all project spec documents (PRD.md, architecture.md, schema.md, api.md, rules.md, StyleGuide.md, Task.md). Run after each phase completes, before code-review.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Verifies that code matches all applicable project specs and applies approved compliance fixes. Use after each phase before code-review, on explicit compliance requests, and when the user replies yes, fix, continue, or finding IDs to this skill's report-first gate.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Spec Compliance
 
 ## 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.
+
 Before continuing:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`. See § Fix Mode Contract in runtime-config.md for the full enforcement rules.
-3. Use `languagePreferences.communication.normalized` for all user-facing reports and review output.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/fix-mode.md`.
+3. Read `../_shared/references/human-loop.md`.
+4. Read `../_shared/references/finding-format.md`.
+5. If this message answers this skill's active report-first gate, resume directly under the Approval Resume Protocol. Do not rerun startup or compliance analysis.
+6. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+7. Use `languagePreferences.communication.normalized` for all user-facing reports and review output.
 
 ---
 
@@ -41,7 +49,7 @@ You are a **QA Engineer and Spec Auditor** who ensures that no implementation dr
 
 ## Fix Mode
 
-Mode is read in Shared Runtime Setup. Enforcement rules, including the required gate prompt, are in `../_shared/references/runtime-config.md § Fix Mode Contract`.
+Mode is read in Shared Runtime Setup. Enforcement rules, including the required gate prompt, are in `../_shared/references/fix-mode.md`.
 
 To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-config.json`.
 
@@ -66,6 +74,8 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 - [ ] Acceptance criteria per feature are met (Given/When/Then from `PRD.md`)
 - [ ] No features from `PRD.md § Non-Goals` are included
 - [ ] NFRs are considered: performance, security, accessibility per `PRD.md § Non-Functional Requirements`
+- [ ] If this phase implements analytics or rollout behavior, it matches `PRD.md § Success Metrics and Rollout`; otherwise mark N/A
+- [ ] Failure/degraded behavior implemented by this phase matches the PRD where specified
 - [ ] If the PRD uses requirement IDs (`FEAT-*`, `BR-*`, etc.), phase code is traceable to the relevant IDs through Task.md
 - [ ] If changes are not yet in the PRD but are recorded in the active phase plan `## Approved Scope Delta`, DO NOT mark them as scope creep violations for this phase. Note them as `pending formal spec update` if needed.
 
@@ -87,6 +97,7 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 - [ ] Auth method matches `architecture.md § Authentication & Authorization`
 - [ ] State management is consistent - do not mix Zustand and Redux
 - [ ] API type is consistent - REST stays REST, not suddenly GraphQL
+- [ ] Operations, observability, rollback, and recovery constraints touched by this phase follow architecture; otherwise mark N/A
 
 **Example findings:**
 ```
@@ -101,11 +112,12 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 
 **Read:** `project-context/schema.md`
 
-- [ ] Table/column names match exactly in queries/ORM - no invented names
-- [ ] Naming conventions are followed (`schema.md § Global Conventions`) - snake_case, singular/plural
-- [ ] Relationships are correct - FKs, cascade delete as defined
-- [ ] Soft delete is respected - if using `deleted_at`, do not hard delete
-- [ ] Audit fields exist: `created_at`, `updated_at` on relevant models
+- [ ] Persisted entity and field names match the datastore-native contract; no invented names
+- [ ] Naming, identifier, validation, retention, and consistency conventions follow `schema.md`
+- [ ] Relationships/data placement match the selected model: keys, references, embedding, edges, streams, or equivalent
+- [ ] Delete, retention, archival, and projection behavior matches the contract where applicable
+- [ ] Required audit/version fields or event metadata exist where the selected model defines them
+- [ ] Tenant isolation, concurrency, and schema-evolution constraints touched by this phase match `schema.md`; otherwise mark N/A
 - [ ] PII is handled safely - never logged, never exposed in responses
 - [ ] If a table has `Trace to`, its usage aligns with the referenced requirement
 
@@ -122,15 +134,14 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 
 **Read:** `project-context/api.md`
 
-- [ ] Endpoint paths match the contract exactly - no typos, no version mismatch
-- [ ] HTTP methods are correct
-- [ ] Request body field names/types match the `api.md` schema
-- [ ] Response format (success/error) matches the standard in `api.md`
-- [ ] Error codes come only from `api.md § Error Catalog`
-- [ ] Pagination follows the `api.md` pattern where applicable
-- [ ] Auth headers exist/are correct per `api.md § Authentication`
-- [ ] If endpoints have `API-*` IDs, the implementation is traceable to the requirement
-- [ ] If a new endpoint is not yet recorded in `api.md` but is listed in `## Approved Scope Delta`, do not mark it as a rogue endpoint for the active phase. Note that a formal spec update is still pending.
+- [ ] Operation identity matches the selected protocol: REST method/path, GraphQL operation, RPC procedure, or event channel/topic
+- [ ] Input arguments/payload fields and types match `api.md`
+- [ ] Success result and error semantics match the protocol-native contract
+- [ ] Pagination/filtering or subscription/delivery behavior follows `api.md` where applicable
+- [ ] Authentication, authorization, idempotency, and replay controls match the contract
+- [ ] Deprecation, retry/timeout, SLO, and contract-test invariants touched by this phase match `api.md`; otherwise mark N/A
+- [ ] `API-*` operations remain traceable to requirements
+- [ ] A new operation listed in `## Approved Scope Delta` is temporary approved scope, not a rogue operation; note pending formal spec sync
 
 **Example findings:**
 ```
@@ -150,6 +161,7 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 - [ ] TypeScript rules are followed: strict, no `any`, no `enum` (if forbidden)
 - [ ] Code style rules are followed: no `console.log`, early return, max function length
 - [ ] Security rules are followed: tokens in httpOnly cookies, no secrets in code
+- [ ] Applicable logging, migration, feature-flag, generated-code, and secret-rotation rules are followed
 
 **Example findings:**
 ```
@@ -169,6 +181,7 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 - [ ] Spacing uses the system - no random margin/padding
 - [ ] Border radius/shadow follow `StyleGuide § Component Style`
 - [ ] Breakpoints follow `StyleGuide § Responsive & Breakpoints`
+- [ ] Applicable operational states, accessibility, localization, and UI performance constraints are implemented
 
 **Example findings:**
 ```
@@ -190,6 +203,7 @@ To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-confi
 - [ ] The task is not half-finished - no unfinished work remains
 - [ ] If the task has traceability IDs, all are valid and point to real upstream artifacts
 - [ ] If an active phase task implements new scope recorded only in `## Approved Scope Delta`, treat it as valid for the active phase, but mention that syncing into the main spec documents is still pending if not done yet.
+- [ ] Every applicable Phase Definition of Done item has evidence; `N/A` items include a reason
 
 **Example findings:**
 ```
@@ -260,26 +274,15 @@ The report is shown in this session chat. Do not save it to a file unless the us
 | developer-config.json (scope) | ✅ OK | — |
 ### Detailed Findings
 [list findings per item - use the 4-point format below]
-```
-
-**Format for each finding - MUST use these 4 points. MUST NOT show code:**
-
-```markdown
-#### [Severity] [ID] [Short Title]
 
-**Where?**
-[Page or file name only]
-
-**What happens if it is not fixed?**
-[Explain the impact in simple logic - as if speaking to a user who understands how the app works, not the code. Short and direct.]
-
-**What happens if it is fixed?**
-[Explain the benefit in simple logic. Short and direct.]
-
-**Recommended fix**
-[Explain what needs to change in logic and flow, not code syntax.]
+### Fix Manifest
+| Finding | Target | Intended change | Validation |
+|---|---|---|---|
+| [ID] | `[path]` | [bounded change] | [compliance check/test] |
 ```
 
+Format each finding with the shared `finding-format.md` loaded during setup.
+
 ---
 
 ## Execution Rules
@@ -295,8 +298,8 @@ The report is shown in this session chat. Do not save it to a file unless the us
 
 **`report-first`:**
 ```
-💥 BLOCKER / 🔴 MAJOR -> Report all findings. Show the gate prompt (see runtime-config.md § Fix Mode Contract). End the response. Wait for user confirmation in the next message before fixing.
-⚠️ MINOR / ℹ️ INFO   -> Only report.
+💥 BLOCKER / 🔴 MAJOR / ⚠️ actionable MINOR -> Report all findings and the fix manifest. Show one gate. On approval, edit the approved manifest directly, validate, and rerun only affected compliance checks without another gate.
+ℹ️ INFO / non-actionable note -> Report only; do not include it in the fix manifest.
 ✅ OK                 -> Continue to the code-review skill.
 ```
 

package/.agents/skills/spec-init/SKILL.md

@@ -1,17 +1,21 @@
 ---
 name: spec-init
-description: Generate all `project-context/` documents from an existing codebase. Supports Batch Generate (all at once) or Guided Generate (one by one with confirmation). Suitable for active projects or boilerplates.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Generates evidence-backed `project-context/` specs from an existing codebase in batch or guided mode, recording confidence and missing decisions. Use only when the user explicitly requests spec bootstrapping or reverse documentation.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Spec Init
 
 ## 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.
+
 Before starting:
 
-1. Read `../_shared/references/runtime-config.md`.
+1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/human-loop.md`.
 3. Read `../_shared/references/scope-rules.md`.
 4. Use `languagePreferences.communication.normalized` for chat output and review prompts.
@@ -42,6 +46,8 @@ Every claim carries a **confidence level**:
 
 ## Step 0 — Choose a Mode
 
+Before asking for a mode, inventory the target files in `project-context/`. Never overwrite an existing document implicitly. If any target exists, ask one decision for this run: preserve and skip existing files, regenerate named files, or cancel and review. List every file that would be replaced. This approval applies only to the named files.
+
 Ask the user before starting:
 
 ```
@@ -143,11 +149,22 @@ When any Medium or Low confidence exists, also include:
 - [question that still needs user confirmation]
 ````
 
+Every generated document must include unresolved decisions that cannot be observed from code:
+
+````markdown
+## Missing Decisions
+
+| Decision Needed | Why It Cannot Be Inferred | Recommended Owner Skill |
+|-----------------|---------------------------|-------------------------|
+| [decision] | [missing evidence] | `[brainstorm-* skill]` |
+````
+
 Rules:
 - Do not mark **High** unless direct evidence exists.
 - For **Medium**, explain the inference basis briefly.
 - For **Low**, write it as a question or note, not a final fact.
 - `PRD.md` usually mixes High and Medium confidence because it is synthesized last from other artifacts.
+- Never infer missing business motivation, rollout, SLO, tenancy, migration, recovery, or operational policy from convention alone. Record it under `Missing Decisions` and route it to the owning brainstorm skill.
 
 ---
 
@@ -216,40 +233,40 @@ Next steps:
 **Read:** folder structure, `package.json`, config files
 **Extract:** tech stack, folder structure, database choice, deployment setup, visible design patterns
 **Add:** `Input Evidence` listing the files and folders used to infer the architecture
-**Add if possible:** `Document Role`, `System Boundaries`, `Canonical Terminology`, `ADR Index`, `Assumptions & Open Questions`
+**Add if possible:** `Document Role`, `System Boundaries`, `Canonical Terminology`, `ADR Index`, observed operations/observability/recovery facts, `Assumptions & Open Questions`, `Missing Decisions`
 
 ### rules.md
 **Read:** `.eslintrc*`, `.prettierrc*`, `tsconfig.json`, 2-3 code examples
 **Extract:** naming conventions in use, indentation, quote style, consistent patterns
 **Add a `[FORBIDDEN]` section:** From ESLint rules and TypeScript strict settings, extract the 5-10 most critical technical prohibitions into a `[FORBIDDEN]` table format that matches `brainstorm-rules` output.
 **Add:** `Input Evidence` listing the config files and code examples used
-**Add if possible:** `Document Role`, `Rule Priority`, `Assumptions & Exceptions`
+**Add if possible:** `Document Role`, `Rule Priority`, observed conditional operational rules, `Assumptions & Exceptions`, `Missing Decisions`
 
 ### schema.md
 **Read:** `migrations/`, `models/`, `prisma/schema.prisma`, or equivalents
-**Extract:** table names, columns, data types, relationships, indexes
+**Extract:** datastore-native entities (tables, collections, aggregates, nodes, streams, or keys), fields/payloads, types, relationships, validation, retention, and indexes/projections
 **Add:** `Input Evidence` listing the schema sources inspected
-**Add if possible:** `Document Role`, `Entity Map`, `Not Yet Modeled / Deferred`, `Assumptions & Open Questions`
+**Add if possible:** `Document Role`, `Entity Map`, observed scale/tenancy/concurrency/migration facts, `Not Yet Modeled / Deferred`, `Assumptions & Open Questions`, `Missing Decisions`
 
 ### api.md
-**Read:** `routes/`, `controllers/`, `handlers/`, OpenAPI/Swagger if available
-**Extract:** method + path for each endpoint, request body, response format, auth requirements
+**Read:** protocol-native routing/integration sources such as `routes/`, `controllers/`, `handlers/`, GraphQL schemas/resolvers, RPC routers, event producers/consumers, and OpenAPI/Swagger if available
+**Extract:** protocol-native operation identity, request/input shape, response/output/event shape, auth requirements, lifecycle/deprecation facts, and reliability signals
 **Add:** `Input Evidence` listing the routing/controller sources inspected
-**Add if possible:** `Document Role`, `Scope Summary`, `Canonical Terminology`, `Endpoint Inventory`, `Assumptions & Open Questions`
+**Add if possible:** `Document Role`, `Scope Summary`, `Canonical Terminology`, operation inventory, observed reliability/deprecation facts, `Assumptions & Open Questions`, `Missing Decisions`
 
 ### StyleGuide.md
 **Read:** `tailwind.config.*`, `components/` folder, main CSS/SCSS files
 **Extract:** colors in use, existing components, spacing system, fonts
 **Skip if:** there is no UI folder or the project is backend-only
 **Add:** `Input Evidence` listing the UI assets inspected
-**Add if possible:** `Document Role`, `Supported Surfaces`, `Component Inventory`, `Non-Goals / Not Yet Defined`, `Assumptions & Open Questions`
+**Add if possible:** `Document Role`, `Supported Surfaces`, `Component Inventory`, observed accessibility/operational states, `Non-Goals / Not Yet Defined`, `Assumptions & Open Questions`, `Missing Decisions`
 
 ### PRD.md
 **Do not read new files**. Only synthesize from previous documents.
-**Extract:** features already built (from api + schema), business rules from schema constraints, non-goals (features that are *not* present)
+**Extract:** features already built (from API, UI, and schema evidence) and business rules supported by direct constraints or behavior. Treat absent capabilities as `not observed`, `unknown`, or `deferred`; absence is not evidence of an intentional non-goal.
 **Confidence note:** PRD usually mixes **High** and **Medium**. Do not state business motivation as fact unless it is explicitly visible in the codebase.
 **Add:** `Input Evidence` referencing the previously generated spec files used for synthesis
-**Add if possible:** `Document Role`, `Canonical Terminology`, `Reading Guide for AI`
+**Add if possible:** `Document Role`, `Canonical Terminology`, observed metrics/workarounds, `Reading Guide for AI`, `Missing Decisions`
 
 ---