macca-method 2.1.2 → 3.0.0-rc.1

package/.agents/skills/code-review/references/review-checklist.md

@@ -1,5 +1,7 @@
 # Code Review Checklist
 
+Follow `../../_shared/references/interaction-contract.md` loaded through the parent skill. Reuse current unchanged sources already read; refresh changed sources or unknown/compacted context. Delegates must read this checklist before reviewing. All checks below remain mandatory to assess internally: perform applicable checks, retain evidence, and mark only genuinely inapplicable checks `N/A` with a reason. Missing required evidence is `NOT VERIFIED`, never `N/A` or an assumed pass.
+
 ## Table of Contents
 
 1. Phase 1 - 27 Code Quality Points
@@ -7,7 +9,8 @@
 3. Self-Review Before Reporting
 4. Phase 3 - Report & Fix
 5. Post-Fix Validation
-6. Key Points
+6. Completion Handoff
+7. Key Points
 
 ## Phase 1 - 27 Code Quality Points (All Required)
 
@@ -56,6 +59,8 @@ For **CR-23**, prefer these tags:
 
 Never mark a single smoke test, regression test, or safety guard as bloat.
 
+Assess CR-22 and CR-23 together: the smallest design must still satisfy current requirements, applicable security/integrity controls, maintainability, and meaningful validation. Justify a "best practice" finding with relevant project evidence or version-appropriate official guidance, not taste or novelty. Do not recommend custom high-risk replacements merely to remove a dependency. Escalate severity according to concrete impact; an under-engineered security or correctness failure is not automatically MINOR.
+
 ### Level 4: INFO
 
 - **CR-25 Missing Comments**
@@ -87,20 +92,22 @@ Check all of these:
 Before producing the report:
 
 1. Verify that all 27 CR checks and 10 SEC checks were actually reviewed.
-2. Quickly reread touched files for duplicate functions and hallucinated imports.
+2. Recheck touched code for duplicate functions and hallucinated imports using fresh source already in context; read changed or missing sections instead of repeating unchanged file I/O.
 3. Recheck severity proportionality.
 4. Ask whether rerunning after fixing the current findings would reveal new findings. If yes, include them now.
 
 ## Phase 3 - Report & Fix
 
-Use this report structure:
+**Clean result:** Return evidence internally to developer, quick-dev, or bug-fix for one combined summary at the origin. Do not print the full clean checklist, zero-count table, or another mode announcement. A standalone review shows a compact result with reviewed scope, actual status, validation evidence, and limitations. Detailed check evidence remains available on request.
+
+**Findings or requested detail:** Use this report structure for findings; expand the internal checklist/evidence when requested. Missing required evidence and its owner must always be visible, even with zero findings. Omit empty headings and zero-count tables unless useful.
 
 ```markdown
 ## Code Review Report
 
 **Task/Phase:** [name]
 **Scope:** [reviewed files]
-**Status:** [💥 BLOCKER | 🔴 MAJOR | ⚠️ MINOR | ✅ PASS]
+**Status:** [💥 BLOCKER | 🔴 MAJOR | ⚠️ MINOR | NOT VERIFIED | ✅ PASS]
 
 ### Summary
 
@@ -112,7 +119,7 @@ Use this report structure:
 | ℹ️ Info    | X     |
 ```
 
-Then list findings by severity, followed by the checklist status table.
+Then list all findings by severity using the shared four-point format. Include affected or unverified checks; include the full checklist status table only on request. Do not suppress findings to make a report compact.
 
 Before a report-first gate, retain this fix manifest for actionable findings:
 
@@ -124,7 +131,7 @@ Before a report-first gate, retain this fix manifest for actionable findings:
 | [ID]    | `[path]` | [bounded change] | [targeted check] |
 ```
 
-If the workflow will update a phase plan status or append Code Review Notes, include that plan file and mutation in the manifest. Otherwise return plan-status completion to `developer`; approval never authorizes an undisclosed plan edit.
+Return plan-status completion and deviation notes to `developer`. Do not add a status-only finding to obtain mutation approval. An explicitly requested bounded plan correction must be disclosed as such; it does not authorize marking a whole phase done.
 
 Format every finding with the shared `finding-format.md` loaded by the parent skill. Keep exact technical targets and validation in the fix manifest, not as a fifth finding point.
 
@@ -132,8 +139,9 @@ Fix priority - follow `fixMode` from Shared Runtime Setup:
 
 **`report-first` (default):**
 
-- **When actionable findings exist (`💥 BLOCKER`, `🔴 MAJOR`, or actionable `⚠️ MINOR`):** Present the full report and fix manifest. Show the gate prompt (`[GATE — Mode: report-first]`) from the shared runtime contract (`fix-mode.md`). **End the response. DO NOT apply any fixes in the same response.** On approval, follow the Approval Resume Protocol without another question.
-- **When all checks pass (`✅ PASS` / 0 actionable findings):** Present the report with `Status: ✅ PASS`. **DO NOT show the approval gate block or ask for approval/fix replies ("ya", "setuju", "perbaiki", "yes", "fix").** Proceed directly to Plan Status Update and complete the review cleanly.
+- **When actionable findings exist (`💥 BLOCKER`, `🔴 MAJOR`, or actionable `⚠️ MINOR`):** Present all findings and the fix manifest. Show the gate prompt (`[GATE — Mode: report-first]`) from the shared runtime contract (`fix-mode.md`) once. **End the response. DO NOT apply any fixes in the same response.** On approval, follow the Approval Resume Protocol without another question.
+- **When all applicable required checks pass (including INFO-only reports):** Return `Status: ✅ PASS`, notes, and evidence to the origin for its combined summary; show a compact result if standalone. **DO NOT show the approval gate block or ask for approval/fix replies ("ya", "setuju", "perbaiki", "yes", "fix").** Do not edit plan status.
+- **When required evidence is missing:** Report `NOT VERIFIED`, identify the evidence/owner, and apply shared Gate Eligibility. Zero actionable findings is not sufficient for PASS; do not fabricate a fix manifest.
 
 **`fix-then-report`:**
 
@@ -141,11 +149,11 @@ Fix priority - follow `fixMode` from Shared Runtime Setup:
 - `🔴 MAJOR` -> fix before the next phase
 - `⚠️ MINOR` -> report and discuss
 - `ℹ️ INFO` -> backlog
-- `✅ PASS` -> no fixes needed, proceed directly to Plan Status Update
+- `✅ PASS` -> no fixes needed, return evidence to the origin without editing plan status
 
 ## Post-Fix Validation
 
-Before updating plan status or claiming completion:
+Before claiming remediation completion:
 
 1. Run the narrowest relevant tests and available type/lint/build checks.
 2. Recheck the approved findings and directly affected CR/SEC items only.
@@ -153,43 +161,15 @@ Before updating plan status or claiming completion:
 4. Report every approved ID as `resolved`, `partial`, or `unresolved`, with command/check evidence.
 5. Do not start a fresh unbounded finding pass. Newly noticed unrelated work is reported separately and is not auto-fixed.
 
-## Plan Status Update (run after all fixes are done)
-
-After fixes are applied and the review is complete, check whether a plan file exists for this phase (`project-context/plans/phase-[N]-*.md`). If it does:
-
-**Step 1 - Detect plan-level deviations.**
-
-A plan-level deviation is any finding where the implementation differs from a decision explicitly stated in the plan, for example:
-
-- The wrong library was used (the plan says Prisma, the code uses Drizzle)
-- The architectural pattern was not followed (the plan says repository pattern, the code puts queries in the controller)
-- Scope was expanded or reduced compared to the plan
-- The approach changed during implementation without a plan update
-
-Code quality findings are **not** plan deviations - naming issues, missing tests, performance, formatting, and security hardening do not count as plan deviations even if marked BLOCKER/MAJOR.
-
-**Step 2 - Update the plan file.**
-
-- **If plan-level deviations were found:**
-  1. Add this section at the bottom of the plan file:
-
-     ```markdown
-     ## Code Review Notes
-
-     **Reviewed:** [YYYY-MM-DD]
-     **Plan deviations found:**
-
-     - [Deviation 1 - short description of what differed and how it was resolved]
-     - [Deviation 2 - ...]
+## Completion Handoff
 
-     > These deviations were identified during code review. The implementation was corrected where possible. See the review report for full detail.
-     ```
+Retain the review unit, origin/return step, approved scope/files and IDs, criteria, checked sources/freshness, validation evidence, pending issues, and next action. Keep this context in the session without secrets or a new state file. A clean result is consolidated at the origin; findings and missing evidence are shown when discovered. Use plain language outside exact keys, IDs, paths, and gate markers.
 
-  2. Update the plan header: `status: code-review` -> `status: done`
+- **Standalone:** End with the report. Do not mutate Task.md or plan status automatically, even when every check passes or a phase plan exists.
+- **Task or bug review:** Return evidence to quick-dev, developer's selected task, or bug-fix at the retained return step. A task review never marks the whole phase done.
+- **Phase review:** Return the result and any plan-level deviations to developer's `close-phase.md`. Developer owns status completion after all phase tasks, formal spec sync, applicable DoD, and both gates pass.
 
-- **If no plan-level deviations were found (only code-quality findings):**
-  1. Update only the plan header: `status: code-review` -> `status: done`
-  2. Do not add a notes section.
+Plan deviations mean disagreement with an explicit plan decision (library, architecture, scope, or approach), not merely naming, formatting, tests, performance, or security findings. Report what differed and how it was resolved; the phase owner records useful Code Review Notes. Do not create an artifact for a standalone report unless requested.
 
 ## Key Points
 

package/.agents/skills/developer/SKILL.md

@@ -15,13 +15,17 @@ Paths written as `../...` below are relative to this SKILL.md's own folder, not
 
 Before continuing:
 
+An active approval reply resumes the originating review/remediation skill under `fix-mode.md` before identity, onboarding, or work-mode setup. Preserve its task/phase/bug scope and return step; do not treat it as a fresh implementation request.
+
 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. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. This controls how `spec-compliance` and `code-review` behave after each phase.
-6. Use `languagePreferences.communication.normalized` for chat.
-7. Use `languagePreferences.documents.normalized` for generated plans and spec-side artifacts.
+5. Read the configured fix-mode value from the safe preference summary under `language-config.md`. If it is missing, treat it as `"report-first"`. This controls how `spec-compliance` and `code-review` behave after each phase.
+6. Use the resolved communication language from `language-config.md` for chat.
+7. Use the resolved document language from `language-config.md` for generated plans and spec-side artifacts.
+
+Follow `../_shared/references/interaction-contract.md`, loaded by `language-config.md`: reuse already-read, current unchanged sources; refresh changed sources or context lost through compaction. Missing or uncertain context requires a read, not an assumption. Announce fix mode once per authorized workflow, not at each handoff. Use plain language outside exact config keys, IDs, paths, and gate markers.
 
 ---
 
@@ -46,7 +50,7 @@ Developer-specific additions:
 
 ## When You MUST Ask
 
-- If the user request adds business scope, endpoints, data, components, or behavior not recorded in `project-context/`
+- If business scope or behavior needs a new decision; route significant product expansion to `add-feature`
 - If 2+ valid approaches would change the final outcome significantly and the specs, `additionalSkills`, or MCP do not resolve the choice
 - If the change is destructive or hard to undo
 - If documents, plans, or user instructions conflict in a way that changes the next action
@@ -56,10 +60,12 @@ Developer-specific additions:
 - If the answer is already explicit in `project-context/`, relevant `additionalSkills`, or relevant MCP results
 - If the decision is purely technical, low-risk, and does not change business scope
 - If the change is easy to undo and stays within the current phase scope
+- If an explicit request already approves a bounded technical delta: follow `../_shared/references/scope-delta.md` and record it before coding. Absence from the specs alone does not require another question. Business-scope and destructive-change approvals remain distinct.
 
 **Workflow:**
 
 - Read only the specs needed for the current task - not all specs
+- `rules.md` and `architecture.md` are mandatory before any code change; if either is missing, route to its owning brainstorm skill and do not code
 - One phase at a time
 - Mark each completed task in `Task.md` with implementation notes if important decisions were made
 - After a phase completes: run `spec-compliance` then `code-review` - both follow `fixMode`
@@ -67,11 +73,12 @@ Developer-specific additions:
 - If all tasks in `Task.md` are done but the user still asks for small technical changes, hardening, cleanup, optimization, or workflow adjustments within the current work scope, keep using `developer` in **Post-Task / Maintenance Mode**.
 - In **Post-Task / Maintenance Mode**, MUST create a small delta phase or task in `Task.md` / the active phase plan before coding so the change stays traceable.
 
-**MCP (MUST use if available and relevant, based on `availableMCPs` in `developer-config.json`):**
+**MCP and additional skills:**
 
-- Use every MCP relevant to the current task. MUST NOT use MCPs the user did not register.
+- Detect available tools/skills from host context. Summary counts do not authorize use; check a requested tool's saved membership or a named skill's path through the local-only exception in `config-mutation.md`, returning only safe status and never raw saved names or paths. Availability alone is not authorization. Respect the saved `availableMCPs` allowlist and explicit denials; follow `references/onboarding.md` when a material authorization decision is missing.
+- Use available, authorized tools when relevant. Do not ask a tool-setup questionnaire for work that needs none.
 - Examples: `context7` for external library docs, `codebase-memory-mcp` for codebase discovery and symbol relationships
-- MUST NOT code against external libraries from memory if a relevant docs MCP exists
+- MUST NOT code against external libraries from memory when a relevant docs MCP is available and authorized. If current API evidence cannot be obtained, surface that gap without overriding tool permissions.
 
 **Priority:** Correctness -> spec compliance -> clean/safe code -> maintainability.
 
@@ -79,26 +86,13 @@ Developer-specific additions:
 
 ---
 
-## Step 0 - Identify Name & Project
-
-Read `.agents/developer-config.json` and extract `name`, `project`, and `developerPreferences.workMode`.
-
-**If name and project exist:**
-
-> "Welcome back, [name]. **Firdaus** here - ready to continue **[project]**. Let us see what needs work today."
+## Step 0 - Resolve the Request and Saved Preferences
 
-**If name exists but project is empty:**
+Use the safe preference summary from `language-config.md` for the configured work-mode value and identity configured indicators only. Do not extract or display saved identity labels.
 
-> "Welcome back, [name]. **Firdaus** here - ready to continue. Let us see what needs work today."
+Reuse the configured work-mode value. A user name supplied in the conversation may be used optionally; never recover it from config. An explicit implementation request proceeds without an identity interview, welcome banner, or generic "What needs work?" question. Missing `name` or `project` is optional setup, not a blocker. Ask for identity only when the user requests setup; save supplied values through the shared config-mutation contract, preserving unrelated fields.
 
-**If name does not exist:**
-
-> "Hi. I am **Firdaus**, the developer on this team. Before we start:
->
-> 1. What is your name?
-> 2. What is the project name?"
-
-After the user answers, **create or update `.agents/developer-config.json`** with `name` and `project`. Preserve all other fields.
+If no task was supplied, ask what the user wants to accomplish. Resolve only missing decisions that materially affect execution; use a concise scope acknowledgement when useful.
 
 ---
 
@@ -106,8 +100,12 @@ After the user answers, **create or update `.agents/developer-config.json`** wit
 
 Load only the current state:
 
-- Missing config, scope, work mode, or starting plan-first: read `references/onboarding.md`. If adding skill paths, also read `../_shared/references/additional-skills.md`.
+- A material setup decision is missing, setup was requested, or plan-first must start: read `references/onboarding.md`. Missing optional config alone does not trigger onboarding. If adding skill paths, also read `../_shared/references/additional-skills.md`.
 - Executing a task: read `references/execute-task.md`.
 - Closing a completed phase/project: read `references/close-phase.md`.
 
 Do not load all three by default.
+
+## Workflow Handoff
+
+Keep the review unit, origin and exact return step, approved scope/files and IDs, acceptance criteria, checked sources and freshness, validation evidence, pending issues, and next action in the current workflow context. A delegate must read the relevant reference pointer, using the same freshness rule; a summary does not replace unknown source instructions. Return clean compliance/review evidence internally for one combined result at the origin. Findings and missing evidence remain visible. Do not persist secrets or create a state file for this handoff.

package/.agents/skills/developer/references/close-phase.md

@@ -2,18 +2,23 @@
 
 Read this file only after every task in the active phase is complete.
 
+Follow `../../_shared/references/interaction-contract.md`. Reuse current unchanged sections already in context and refresh changed/unknown sources. A delegate reads the reference relevant to its work; send the review unit, origin/return step, approved scope/files and IDs, criteria, checked sources/freshness, pending issues, validation evidence, and next action. Keep this context in the session without secrets or a new state file.
+
 ## Close the Phase
 
-1. Show the phase summary.
+1. Assemble the phase summary for the combined closing result; do not print a separate clean report before each gate.
 2. Read the phase Definition of Done. Complete every applicable implementation-side item; mark inapplicable items `N/A` with a reason.
-3. If a phase plan exists, set `status: code-review`.
-4. Run `spec-compliance` using configured fix mode.
-5. Only after compliance passes, run `code-review` using configured fix mode.
-6. Mark quality-gate Definition of Done items complete only after both pass.
-7. Offer the next phase and wait according to Task.md execution rules.
+3. Read `../../_shared/references/scope-delta.md`. Collect approved deltas from Task.md and the phase plan, complete each named formal spec sync through its owning skill, and validate affected document pairs. Record sync evidence; unresolved sync blocks phase closure. Reuse approved technical decisions without reopening discovery.
+4. If a phase plan exists, set `status: code-review`.
+5. Run `spec-compliance` with review unit `phase`, all phase tasks, delta/sync evidence, and implementation-side DoD using configured fix mode. Its own result and downstream code-review remain pending, not circular prerequisites.
+6. Only after compliance passes, run `code-review` for that same phase using configured fix mode. Retain developer's phase-close return step across approval pauses.
+7. Only after both pass and all applicable DoD and sync evidence exist, developer marks quality-gate items complete and sets the phase plan to `status: done`. Record any relevant review deviation notes here. A task-only review or standalone report never authorizes phase completion.
+8. Show one combined phase result with changed files, actual validation/gate results, and remaining issues or limitations. Offer the next phase and wait according to Task.md execution rules and the user's ongoing authorization.
 
 In report-first mode, stop at the active gate. Do not invoke the next gate in the same response.
 
+All applicable compliance, code-quality, and security checks remain mandatory internally. Keep evidence available; show detailed findings and the actionable manifest with one shared gate when eligible. Missing evidence stays visible as `NOT VERIFIED`; `N/A` requires genuine inapplicability and a reason. Clean gate results return to developer for the combined summary, not separate user-facing tables. Announce fix mode only once for the authorized workflow.
+
 ## Project Complete
 
 When all phases are complete:

package/.agents/skills/developer/references/execute-task.md

@@ -2,9 +2,11 @@
 
 Read this file only when executing the current task.
 
+Follow `../../_shared/references/interaction-contract.md`. A delegate reads this reference when executing; pass the review unit, origin/return step, approved scope/files and IDs, checked sources/freshness, pending issues, and next action. Reuse current unchanged source already read; refresh changed sources or unknown/compacted context. Keep handoff context in the session, without secrets or a new state file.
+
 ## Select Relevant Specs
 
-`architecture.md` is required. Read `rules.md` and architecture for every task, then conditionally:
+`architecture.md` and `rules.md` are required. Before each task, ensure their fresh relevant sections are in context, including applicable boundaries and all relevant `[FORBIDDEN]` rules. Reuse sections already read from current unchanged sources; read again only for changes, missing sections, or unknown/compacted context. If `architecture.md` is missing, stop and route to `brainstorm-architecture`; if `rules.md` is missing, stop and route to `brainstorm-rules`. Do not write code until both documents exist.
 
 | Condition                | Additional source |
 | ------------------------ | ----------------- |
@@ -19,7 +21,9 @@ Scan `[FORBIDDEN]` in rules before coding. Enforce `developerPreferences.scope`
 
 Read the task, acceptance criteria, traceability, and Definition of Done. Follow the shared implementation principles loaded by the parent skill.
 
-If requested behavior is not recorded in `project-context/`, obtain one approval and record an `## Approved Scope Delta` in the active phase plan before coding:
+If requested behavior is not recorded in `project-context/`, read `../../_shared/references/scope-delta.md`. An explicit request is sufficient approval for a bounded technical delta; do not ask again merely because the specs have not recorded it. Ask only for an unresolved material scope/business decision or separate destructive-change approval. Record an `## Approved Scope Delta` before coding: use the active phase plan in plan-first mode, a lightweight Task.md entry for quick-dev, or Task.md/a minimal phase plan in direct mode. These are equivalent evidence; do not require a phase plan for a valid Task.md delta.
+
+Minimum example (also include the task/phase anchor, bounded change, validation, and owning-skill sync checklist):
 
 ```markdown
 ## Approved Scope Delta
@@ -31,10 +35,11 @@ If requested behavior is not recorded in `project-context/`, obtain one approval
 **Acceptance Criteria:**
 
 - [ ] [testable condition]
-      **Sync requirement:** Update the formal owning spec before phase close or when requested.
+
+**Sync requirement:** Update the named formal spec through its owning skill before phase close or when requested.
 ```
 
-Do not code an unapproved delta.
+Do not code an unapproved delta. Approved technical deltas grant bounded sync permission under `scope-delta.md`, not permission for broad spec rewrites or new product scope.
 
 ## Clarify and Define Behavior
 
@@ -44,12 +49,12 @@ Ask one focused question only for unresolved material ambiguity. For non-trivial
 
 Before coding:
 
-1. Read relevant registered additional skills.
-2. Use relevant registered MCPs; use current documentation for external APIs.
+1. Read relevant available and authorized additional skills, respecting saved allowlists and denials.
+2. Use relevant available and authorized MCPs; use current documentation for external APIs. Availability alone is not authorization; resolve material missing permission using `onboarding.md` without a general setup interview.
 3. Apply the shared implementation-principles ladder.
 4. Follow the testing workflow selected in `rules.md`.
 
-After coding, self-review:
+After coding, self-review internally and retain evidence for:
 
 ```text
 [SELF-REVIEW] Task: [name]
@@ -58,6 +63,8 @@ After coding, self-review:
 3. Spec assumption: [assumption or none]
 ```
 
+Show these details only for findings, material assumptions, missing evidence, or a user request; do not print a routine clean self-review banner.
+
 ## Validate and Record
 
 Run the narrowest relevant test/build/type/lint/manual check. Repair local defects and rerun before continuing.
@@ -72,4 +79,4 @@ After validation:
 1. Mark the task and satisfied acceptance criteria complete.
 2. Add a short implementation note only when useful.
 3. Do not mark phase Definition of Done items complete until evidence exists.
-4. Report files and validation evidence, then follow Task.md execution cadence.
+4. Retain files and validation evidence for the origin's combined summary, then follow Task.md execution cadence. Surface blockers immediately; do not print a separate clean report at each internal step.

package/.agents/skills/developer/references/onboarding.md

@@ -1,42 +1,39 @@
 # Developer Onboarding and Planning
 
-Read this file only when identity/config/work mode is incomplete or plan-first must start.
+Read this file only for a material missing setup decision, requested setup, or starting plan-first. Follow `../../_shared/references/interaction-contract.md` for source reuse, handoff, and compact output. Optional identity/config gaps do not block an explicit request.
 
-## Additional Skills and MCPs
+## Optional Configuration Owner
 
-If `additionalSkills` is missing:
+Read `../../_shared/references/config-mutation.md` before config use or persistence. `setup-macca-method` (`@Galbi`) owns optional setup, read-only settings display, and targeted saved-setting changes. Route an explicit configuration request there; use `help` for workflow guidance. Do not repeat a whole configuration interview inside developer or require setup just because `.agents/developer-config.json` is absent.
 
-1. Ask once whether the project uses framework/domain skills.
-2. For each named skill, search every MACCA tool destination: `.agents/skills/` (codex/kimi), `.github/skills/` (copilot), `.opencode/skills/`, `.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`, `.gemini/skills/`, `.kilo/skills/`. If none match, also check the global equivalents `~/.config/opencode/skills/`, `~/.claude/skills/`, and `~/.agents/skills/`. Only then fall back to matching workspace folders.
-3. If found, record its path. If absent, ask for the path or allow `skip`.
-4. Before saving, load `../../_shared/references/additional-skills.md` and use its canonical `paths` shape.
+Continue ordinary work with applicable saved choices and task-local intent. Ask only about a material unresolved decision for this work. A single answer explicitly chosen as a persistent preference may be saved here under the shared contract without a setup detour or repeated approval: validate the existing file and merged candidate with the shared validator before writing, preserve unrelated/unknown fields, and show only redacted known values. Missing validator blocks that mutation; invalid config is preserved and reported by field, not overwritten. Missing optional config does not block implementation. Never save defaults, inferred identity/project names, or task-local choices as consent.
 
-When an additional skill is relevant to a task, read it before coding.
+Use the safe preference summary from `../../_shared/references/language-config.md`; saved finite preferences are `configured`/`value` fields, not raw scalar fields. Identity has only configured indicators. Do not extract or display saved identity labels. A user name supplied in the conversation may be used optionally. Failed/unavailable reads are not absent preferences; stop the affected lookup instead of falling back to raw config.
 
-If `availableMCPs` is missing, ask once which MCPs are available or `none`. Save while preserving unrelated config. Use only registered MCPs that help the current task.
+## Additional Skills and MCPs
 
-## Developer Scope
+1. Inspect host-provided tool/skill descriptions, applicable permission instructions, and safe configured/count/denied summary indicators for `additionalSkills` / `availableMCPs`. Summary counts do not authorize use. For a requested tool's membership or a named skill's path, follow the local-only exception in `config-mutation.md`; keep raw saved names, paths, entries, and config out of tool output and return only safe status. Distinguish **installed**, **available**, and **user-authorized/allowed**. A visible tool or installed skill is not permission to use it. Discovery itself never executes a discovered skill or grants access.
+2. Respect saved allowlists, including an empty list or `none`, and explicit denials. Do not silently add a discovered tool or override a denial. A user can explicitly revise a saved choice; preserve unrelated config when saving the revision.
+3. If configuration is missing, use host context only where it establishes both availability and authorization for the current task. Do not convert discovery into a saved allowlist. Ask one focused question only if a needed tool/skill has unresolved authorization or another material decision is missing. No mandatory MCP questionnaire for simple work needing no MCP.
+4. Read a relevant authorized skill before coding, reusing current unchanged source already in context. For a user-named skill whose path is unresolved, follow the permitted-location discovery and host-path fallback in `../../_shared/references/additional-skills.md`. Do not scan denied paths or execute a skill just to identify it. Ask for its path or allow `skip` only if it remains needed and unresolved.
+5. Before saving user-authorized skill paths, load `../../_shared/references/additional-skills.md` and use its canonical `paths` shape. Never persist credentials or secrets.
 
-If `developerPreferences.scope` exists, use it. Otherwise ask once:
+## Developer Scope
 
-```text
-A) Frontend only
-B) Backend only
-C) Fullstack
-```
+Use an explicit user scope statement or the configured scope value from the safe preference summary (`developerPreferences.scope.configured` / `.value`). An explicit revision may change the saved boundary; a task that merely seems to need extra files does not. Never silently widen scope or treat a missing field as full-project authorization.
 
-Save `frontend`, `backend`, or `fullstack` through the shared config-mutation contract.
+For an unambiguous bounded request, infer its authorized files/behavior and proceed without a generic scope question. Ask only if an unresolved boundary materially changes the work. Use plain language, for example: "Should this cover only the screens, only server-side behavior, or both?" Map a supplied project preference to `frontend`, `backend`, or `fullstack` through the shared config-mutation contract; do not save an inferred task-local boundary as a global preference.
 
 ## Work Mode
 
-If `developerPreferences.workMode` exists, use it. Otherwise ask once:
+Reuse the configured work-mode value from the safe preference summary (`developerPreferences.workMode.configured` / `.value`) unless the user explicitly changes it. If missing, an explicit "implement/code now" or "plan first" request resolves the mode for this work. Ask only when the choice remains material and unresolved:
 
 ```text
 A) Code now — direct
 B) Plan first — review a phase plan before coding
 ```
 
-Save `direct` or `plan-first`.
+Save an explicitly chosen persistent preference as `direct` or `plan-first`; do not reopen a resolved choice on a handoff or approval resume.
 
 For `plan-first`: