macca-method 1.1.0 → 2.0.0

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

@@ -1,8 +1,10 @@
 ---
 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
@@ -11,9 +13,13 @@ persona_role: "Tech Lead"
 
 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`.
+3. 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.
+4. 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]`.
+5. Use `languagePreferences.communication.normalized` for all user-facing reports and review output.
 
 ---
 
@@ -41,7 +47,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 +72,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 +95,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 +110,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 +132,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 +159,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 +179,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 +201,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 +272,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 +296,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,8 +1,10 @@
 ---
 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
@@ -11,7 +13,7 @@ persona_role: "Tech Lead"
 
 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 +44,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 +147,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 +231,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`
 
 ---