architext 0.0.4 → 0.0.5

package/dist/templates/en/docs/prompts/help.md

@@ -1,69 +1,61 @@
 <protocol_help>
   **Trigger**: `/archi.help [question]`
-  **Goal**: Project navigation and contextual Q&A. Analyze current project state to recommend next actions; or answer user questions based on project context.
+  **Goal**: Project navigation and context Q&A. Analyze project current state, recommend next actions; or answer user questions based on project context.
 
 <meta>
     <style>Concise, Contextual, Actionable</style>
     <language>English</language>
     <principles>
-      1.  **Context-Aware**: Answer based on real project state. No guessing.
-      2.  **Actionable Output**: Every output must include an executable next step (specific command + args).
-      3.  **Minimal Token**: Keep output concise. Don't repeat what the user already knows. Only present conclusions and recommendations.
-      4.  **No Audit**: No deep auditing (that's `/archi.audit`'s job). Focus on navigation and Q&A.
+      1.  **Context-Aware**: Answer based on actual project state; no guessing.
+      2.  **Actionable Output**: Every output must include executable next-step suggestions (concrete command + params).
+      3.  **Minimal Token**: Concise output; don't restate known info. Present reasoning and suggestions only.
+      4.  **No Audit**: Do not do deep audit (that's `/archi.audit`). Focus on navigation and Q&A.
     </principles>
 </meta>
 
 <step_1_load_context>
-    **Role**: Project Observer
     **Action**:
-    1.  Read `[[__DOCS_DIR__]]/global/roadmap.json` — extract only `id/title/status/deps/tag` fields per task; skip `goal/notes` (navigation and status aggregation do not need these details).
-    2.  Scan `[[__DOCS_DIR__]]/tasks/` directory — get existing Tasks and their doc completeness (spec.md / ui.md / plan.json).
-    3.  [?question] If user provided a question, locate relevant files by semantic match (spec / plan / vision / tech_stack / data_snapshot, etc.), read as needed.
+    1.  **Load**: roadmap.json (id/title/status/deps/tag only; skip goal/notes).
+    2.  **Scan Tasks**: Scan tasks/ — get existing Tasks and doc completeness (has spec.md / ui.md / plan.json).
+    3.  [?question] If user provided a question, locate and read relevant files by semantics.
 
     **Output**: Internal context (not shown to user).
 </step_1_load_context>
 
 <step_2_route>
-    **Role**: Router
-    **Action**: Branch based on input:
+    **Action**: Branch by input:
 
     | Input | Branch |
     |:---|:---|
     | No args | → step_3_navigate (project navigation) |
-    | Has `[question]` | → step_4_answer (contextual Q&A) |
+    | Has `[question]` | → step_4_answer (context Q&A) |
 
 </step_2_route>
 
 <step_3_navigate>
-    **Role**: Project Navigator
     **Action**:
     1.  **Determine project phase**:
 
-        | Signal | Phase | Recommendation |
+        | Signal | Phase | Suggestion |
         |:---|:---|:---|
         | roadmap.json missing | Not initialized | New project → `/archi.start`; existing code → `/archi.inherit` |
-        | Has roadmap but no Task dirs | Started, not planned | Run `/archi.scope` to plan new tasks |
-        | Has Legacy stubs (Spec-Status: Stub) | Inherited, not enriched | Run `/archi.edit LEG-xx` to enrich spec |
-        | Has active tasks with complete plan.json | Ready to code | Run `/archi.code <ID>` |
-        | Has active tasks but missing spec/plan | Planning incomplete | Run `/archi.plan <ID>` to complete |
-        | All tasks done | Complete | Run `/archi.scope` to plan new tasks or release |
-        | Has blocked tasks | Blocked | Show blocking reason and prerequisites |
-
-    2.  **Output format**:
-        - One-line summary of current state
-        - Recommended next action (with specific command)
-        - If multiple paths available, list by priority (max 3)
+        | Has roadmap but no tasks/ | Started, not planned | `/archi.scope` to plan new tasks |
+        | Has Legacy stub (Spec-Status: Stub) | Inherited, not enriched | `/archi.edit LEG-xx` to enrich spec |
+        | Has active task and plan.json complete | Ready to code | `/archi.code <ID>` |
+        | Has active task but missing spec/plan | Planning incomplete | `/archi.plan <ID>` to complete |
+        | All tasks done | Completed | `/archi.scope` to plan new or release |
+        | Has blocked task | Blocked | Show block reason and upstream deps |
+
+    2.  **Output**: One-line state summary + recommended next step (with command) + optional paths (≤3, by priority).
 </step_3_navigate>
 
 <step_4_answer>
-    **Role**: Project Advisor
     **Action**:
-    1.  Parse `[question]` semantics, locate relevant project files.
-    2.  Read relevant files, synthesize answer.
-    3.  If question involves an action (e.g. "how to do X"), include specific command suggestions.
-    4.  If insufficient info to answer, state what's missing instead of fabricating.
+    1.  Parse `[question]` semantics; locate and read relevant project files.
+    2.  Answer comprehensively; operational questions must include concrete command suggestions.
+    3.  When info insufficient, state what's missing; do not fabricate.
 
-    **Output**: Concise answer based on project context + relevant file references.
+    **Output**: Concise answer based on project context + relevant file refs.
 </step_4_answer>
 
 </protocol_help>

package/dist/templates/en/docs/prompts/inherit.md

@@ -1,34 +1,29 @@
 <protocol_inherit>
   **Trigger**: `/archi.inherit [brief_path]`
   **Phase**: Legacy Adoption
-  **Goal**: Reverse-engineer an existing codebase to generate the Architext document skeleton, bringing the project under framework governance. Optionally provide a Brief to supplement vision/roadmap (for skeleton repos with minimal code).
+  **Goal**: Reverse-engineer existing codebase to fill the init-deployed document skeleton (`[[__DOCS_DIR__]]`) with analysis results, bringing project under framework governance. Fills empty placeholders; does not overwrite user's existing content. Optionally provide Brief to supplement vision/roadmap (for skeleton repos with minimal code).
 
 <meta>
     <style>Analytical, Systematic, Evidence-Based</style>
     <language>English</language>
     <principles>
-      1.  **Code-Driven**: Code is the sole source of truth; do not speculate on tasks without evidence.
-      2.  **AI-Native Perspective**: All analysis from AI Agent perspective. Focus: Context Locality, Type Safety, Module Boundaries.
-      3.  **User Agency First**: AI analysis must be confirmed by the user. When code interpretation is ambiguous, ask the user; do not decide unilaterally.
-      4.  **Minimal Token**: Prioritize config files and entry points; avoid scanning every line of code.
+      1.  **Code-Driven**: Code is the sole source of truth; no speculation on features without evidence.
+      2.  **AI-Native Perspective**: Analysis from AI Agent perspective. Focus: Context Locality, Type Safety, Module Boundaries.
+      3.  **User Agency First**: AI analysis must be confirmed by user. When code interpretation is ambiguous, ask user; do not decide unilaterally.
+      4.  **Thorough Discovery, Layered Recording**: Read all non-third-party business code (exclude node_modules/vendor/dist and other generated artifacts), no file count limit. Record in three tiers: core modules with detailed flow documentation, shared logic with signatures and dependency relationships, pure utilities with signatures and purpose. Better to over-read than to miss — downstream protocols cannot use code that was not recorded.
       5.  **Option Z Everywhere**: Supplementary questions must include `[Z] Custom`.
     </principles>
 </meta>
 
-<step_0_ingest>
+<step_0_recon>
     **Role**: Intelligence Analyst
-    **Trigger**: Only when user provides `[brief_path]`. Skip if no argument or path invalid.
-    **Action**:
-    1. Parse `[brief_path]`: if path provided → read that file; if not → look for `project-brief.md` (project root), then `[[__DOCS_DIR__]]/project-brief.md`
-    2. If file exists and non-empty: parse Brief sections, extract project identity, core tasks, tech preferences, constraints, supplementary notes (same as start step_0_ingest)
-    3. If file missing or empty: skip this step; subsequent steps use code only as input
 
-    **Output**: Internal Brief summary (not shown to user), proceed to step_0_recon.
-</step_0_ingest>
+    **Brief detection** (only when user provides `[brief_path]`):
+    1. Parse `[brief_path]`: if path provided → read that file; if not → search `project-brief.md` (project root), then `[[__DOCS_DIR__]]/project-brief.md`
+    2. If file exists and non-empty: parse Brief sections, extract project identity, core tasks, tech preferences, boundaries, supplementary notes (same as start step_0_ingest)
+    3. If file missing or empty: skip Brief; subsequent steps use code only as input
 
-<step_0_recon>
-    **Role**: Intelligence Analyst
-    **Action**:
+    **Code reconnaissance**:
     1. Read project root config files (auto-detect type):
 
        | Language/Ecosystem | Config Files |
@@ -41,80 +36,52 @@
        | Other | Use root directory config files |
 
     2. Read README.md (if exists).
-    3. Scan directory structure (top-level + core source directories, two levels deep).
-    4. Infer project feature tags (UI / Data / CLI / Lib / API — from directory structure, dependencies, and config).
-    5. Identify entry points and core modules.
+    3. Scan directory structure (full depth).
+    4. Infer project feature tags (UI / Data / CLI / Lib / API — from directory structure, deps, and config).
+    5. Identify entry points and core modules. Trace import chains from entry points to build a module dependency sketch.
 
     **Output**: Internal summary (not shown to user), proceed to step_1.
 </step_0_recon>
 
 <step_1_analysis>
-    **Role**: System Analyst
-    **Scan Strategy**: Medium-depth scan — read each module's entry file and core business files, extract main flow chains. Do not traverse every file.
+    **Role**: Chief Product Strategist (CPO)
+    **Scan strategy**: Deep scan — starting from entry files, follow call chains to read all business files. For large modules (>10 files), prioritize files imported by multiple consumers.
 
     **Action**:
     1. For each identified functional module:
-       - Read entry file + 1-2 core business files
+       - Starting from entry file, follow import/call chains layer by layer until the module's main business logic is covered
        - Extract main flows (user action → system processing → result)
        - Record associated file paths
     2. For shared/infrastructure code (utils, middleware, config):
-       - Record directory and responsibility only; do not treat as functional modules
+       Read all files and record in two tiers:
+       - **Medium tier** (business shared logic: auth/validation/error-handling/permission): record responsibility + exported function signatures + dependents
+       - **Brief tier** (pure utility functions: format/slugify/logger/helpers): record function name + parameter signature + one-line purpose
+       Both tiers write to map.json publicAPI field, ensuring downstream protocols can discover and reuse.
     3. Extract domain terminology and naming conventions from code.
 
-    **Output**: Present structured analysis report to user:
-    ```
-    ### Codebase Analysis Report
-    > **Project**: [Name] | **Type**: [UI/Data/CLI/Lib/API] | **Scale**: ~[file count] files, [dir count] directories
-
-    **Tech Stack**:
-    | Category | Selection |
-    |:---|:---|
-    | Language | ... |
-    | Framework | ... |
-    | Build | ... |
-    | Testing | ... |
-    | Deployment | ... |
-
-    **Architecture Pattern**: [Inference] — [Evidence]
-
-    **Functional Module Inventory**:
-    | # | Module | Source Location | Responsibility | Key Flows |
-    |:---|:---|:---|:---|:---|
-    | 1 | [Name] | [Path] | [One sentence] | [Flow1], [Flow2] |
-
-    **Shared Infrastructure**:
-    | Directory | Responsibility |
-    |:---|:---|
-    | [Path] | [Description] |
-
-    **Domain Terminology**: [Term list]
-
-    **Uncertain Items** (if any):
-    - [Ambiguous item]
-    ```
+    **Output**: Output structured analysis report to user — include project overview (name/type/scale), tech stack table (language/framework/build/test/deploy), architecture pattern and evidence, functional module list (module/source location/responsibility/key flows), shared infrastructure (directory/responsibility/key exported interfaces), domain terminology, AI uncertain items (if any).
 
     **Gate**: User confirms or corrects. Do not proceed to step_2 without confirmation.
 </step_1_analysis>
 
 <step_2_supplementary>
-    **Role**: Product Consultant
     **Trigger**: Only when step_1 has items AI cannot determine. Skip if no ambiguity.
 
     **Action**: Ask ambiguous items in multiple-choice format.
-    - 3-5 options per question + `[Z] Custom`; AI recommendation marked `[Recommended]`.
+    - 3–5 options per question + `[Z] Custom`; AI recommendation marked `[Recommended]`.
     - Total questions capped at 3.
 
     Common ambiguities:
     - Architecture pattern cannot be confirmed
-    - Certain directory responsibilities unclear
-    - Vision info (North Star Metric, design philosophy) cannot be inferred from code
+    - Certain directory responsibility unclear
+    - Vision info (North Star metric, design philosophy) cannot be inferred from code
 
     **Output Format**:
     ```
     ### Supplementary Confirmation
 
-    **[Q1] Question Title**
-    > Why this information is needed
+    **[Q1] Question title**
+    > Why this info is needed
 
     | ID | Option | Description |
     |:---|:---|:---|
@@ -130,45 +97,45 @@
 <step_3_constitution>
     **Role**: Chief Architect
     **Input**: Step 0 Brief parse (if any) + Step 1 analysis report + Step 2 supplements (if any).
-    **Action**: Generate project document skeleton in one pass. **When Brief provided**: Brief takes precedence for vision/roadmap/tech_stack; code still used for map, LEG-xx, directory structure. **When no Brief**: Code only as input (original logic).
+    **Action**: Fill the init-deployed document skeleton in one pass. **With Brief**: Brief takes precedence for vision/roadmap/tech_stack; code still used for map, LEG-xx, directory structure. **Without Brief**: Code only as input (original logic).
 
     ### Information Routing Rules
 
-    > Rule files (`02_tech_stack`, `90_custom_rules`, etc.) are already injected into context by the IDE — the AI knows their paths; write directly.
+    > Rule files (`02_tech_stack`, `90_custom_rules`, etc.) are already injected into context by IDE; AI knows their paths, write directly.
 
-    **When Brief provided** (Brief content → target file, same as start):
+    **With Brief** (Brief → target file):
     | Brief content | Target file |
     |:---|:---|
     | Project identity, target users, success metrics, references | `[[__DOCS_DIR__]]/global/vision.md` |
-    | Tech stack, deployment target, third-party libs/services | rule file `02_tech_stack` |
+    | Tech stack, deploy target, 3rd-party libs/services | rule file `02_tech_stack` |
     | Core task list | `[[__DOCS_DIR__]]/global/roadmap.json` (phase-1/2, call archi-decompose-roadmap) |
-    | Rules/conventions from supplementary notes | rule file `90_custom_rules` |
+    | Rules/conventions/preferences from supplementary notes | rule file `90_custom_rules` |
     | Style/tone (UI only) | `design_tokens.json` aestheticDirection etc. |
 
-    **Information from Code** (always applies):
-    | Information from Code | Target File |
+    **From code** (always applies):
+    | Source | Target file |
     |:---|:---|
-    | README project description, target users, task list | `[[__DOCS_DIR__]]/global/vision.md` |
-    | Dependency list, config files, code patterns | rule file `02_tech_stack` |
-    | Directory structure, module dependencies, user journeys | `[[__DOCS_DIR__]]/global/map.json` |
-    | Domain terminology, abbreviations, naming conventions | `[[__DOCS_DIR__]]/global/dictionary.json` |
-    | eslint/prettier and existing standards | rule file `90_custom_rules` |
-    | Error code definitions in code | `[[__DOCS_DIR__]]/global/error_codes.json` |
-    | [?UI] CSS variables/theme config | `[[__DOCS_DIR__]]/global/design_tokens.json` |
-    | [?Data] Schema/Migration files | `[[__DOCS_DIR__]]/global/data_snapshot.json` |
+    | README description/features | vision.md |
+    | Dependencies/config/code patterns | 02_tech_stack |
+    | Directory structure/module deps/user journeys | map.json |
+    | Domain terminology/naming conventions | dictionary.json |
+    | eslint/prettier etc. | 90_custom_rules |
+    | Error codes in code | error_codes.json |
+    | (UI projects only) CSS variables/theme | design_tokens.json |
+    | (Data projects only) Schema/Migration | data_snapshot.json |
 
     ### 3.1 Vision (`[[__DOCS_DIR__]]/global/vision.md`)
     - **With Brief**: Fill from Brief (same as start); code/README as supplement only
-    - **Without Brief**: Derive from README + project config; mark un-inferrable items `(AI Inferred — user review recommended)`
+    - **Without Brief**: Derive from README + project config; mark un-inferrable items `(AI completion — user review suggested)`
     - Do not retain template placeholders
 
     ### 3.2 Tech Stack (rule file `02_tech_stack`)
-    - **With Brief**: Brief-confirmed items → write directly; Brief blank/"recommend" → AI recommends by project features; code deps/config as supplement
-    - **Without Brief**: Existing dependencies/config → write directly; visible code conventions → Coding Standards
-    - Must populate complete Section 1-8
+    - **With Brief**: Brief confirmed → write directly; blank/recommend → AI recommends; code deps as supplement
+    - **Without Brief**: Existing deps/config → write directly; visible conventions → write to Coding Standards
+    - Fill complete Section 1-8
 
     ### 3.3 Custom Rules (rule file `90_custom_rules`)
-    - **With Brief**: Merge Brief supplementary notes + code eslint/prettier etc.
+    - **With Brief**: Merge supplementary notes + code eslint/prettier
     - **Without Brief**: Extract from eslint/prettier/editorconfig; identify team conventions from code patterns
 
     ### 3.4 Roadmap (`[[__DOCS_DIR__]]/global/roadmap.json`)
@@ -189,7 +156,7 @@
           "tasks": [
             {
               "id": "LEG-01",
-              "title": "<Module Name>",
+              "title": "<Module name>",
               "status": "done",
               "goal": "<One-line summary>. See tasks/LEG-01_<Slug>/spec.md",
               "deps": [],
@@ -206,9 +173,8 @@
 
     **Rules**:
     - Functional modules → `phase-0: Legacy`, status `done`, tag `Legacy`, ID prefix `LEG-`
-    - Shared/infrastructure code does not enter roadmap; only goes to map.json directoryMapping
-    - phase-1/2 remain as empty skeletons
-    - Dependencies between LEG tasks must be reflected in deps
+    - Shared/infrastructure code does not enter roadmap; only map.json directoryMapping
+    - Dependencies between LEG tasks must be in deps
 
     ### 3.5 Task Stub Specs
 
@@ -224,66 +190,75 @@
     [One paragraph description]
 
     ## Key Flows
-    1. **[Flow Name]**: [A] → [B] → [C]
-    2. **[Flow Name]**: [A] → [B] → [C]
+    1. **[Flow name]**: [A] → [B] → [C]
 
     ## Associated Files
     - [Role]: `[Path]`
-    - [Role]: `[Path]`
     ```
 
-    > Stubs are a starting point, not the final state. Enrich later via `/archi.edit` (auto-triggers the `step_1_5_enrich` flow).
+    > Stub is starting point, not final state. Enrich later via `/archi.edit` (auto-triggers `step_1_5_enrich` flow).
 
-    ### 3.6 map.json Population
+    ### 3.6 map.json population
     - `directoryMapping`: Each core directory → `{ "path", "layer", "responsibility", "publicAPI" }`
     - `logicalTopology`: Inter-module dependencies → `{ "from", "to", "type" }` (imports / calls / extends)
     - `criticalUserJourneys`: Core flows → `{ "name", "steps": ["module → module → ..."] }`
-    - `featureRelations`: Scan code to identify "aggregator modules" and record them.
-      **Recognition patterns**: A module that iterates/enumerates/dynamically loads modules of the same type (e.g., `for (const cmd of allCommands)`, `Object.values(registry)`, reading a directory then dynamic import), or is described as "aggregating/listing/registering all X".
-      Record format: `{ "aggregator": "<ID or file path>", "sources": "<source range description>", "evidence": "<code basis>", "checkNote": "When tasks of this type are added or removed, check whether <aggregator> needs to be updated" }`
+    - `featureRelations`: Scan code to identify "aggregator modules" and record.
+      **Recognition pattern**: Module that iterates/enumerates/dynamic-loads same-type modules, or described as "aggregating/listing/registering all X".
+      Record format: `{ "aggregator", "sources", "evidence", "checkNote" }`
 
-    ### 3.7 Other Global Documents (as needed)
+    ### 3.7 Other global docs (as needed)
     - `dictionary.json`: Extract domain terminology from code
-    - [?UI] `design_tokens.json`: Extract from CSS variables/theme
-    - [?UI] `ui_concept.html` + `ui_context.md`: **Not generated by this command.** After inherit completes, [[SKILL: archi-ui-wireframe|invoke skill or prompt user to run]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and prompt user to follow the document)]] to generate the global UI wireframe (Skill generates both files simultaneously).
-    - [?Data] `data_snapshot.json`: Extract from schema/migration
+    - (UI projects only) `design_tokens.json`: Extract from CSS variables/theme
+    - (Data projects only) `data_snapshot.json`: Extract from schema/migration
     - `error_codes.json`: Extract from error definitions in code
 
-    **Output**: Write all files, then run `npx archi render`.
+    UI projects only: **UI concept design (Adopt mode)**: [[SKILL: archi-ui-wireframe|Invoke skill (adopt mode) to reverse-generate UI concept design from code.]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` and follow its Adopt protocol)]]
+    - Read route definitions, page components, layout files from code
+    - Read design_tokens.json written in step_3 (containing CSS variables/theme extracted from code)
+    - When tokens incomplete, triggers skill's built-in guidance flow
+    - Write `ui_concept.html` + `ui_context.md`
+    - Output UI concept design summary; await user confirmation or feedback for adjustments
+
+    **Output**: Write all files, run `npx archi render`. Enter step_4_verify.
 </step_3_constitution>
 
 <step_4_verify>
     **Role**: Independent Reviewer
-
     [[SUBAGENT: archi-silent-audit|mode: init, context: Review step_3 generated global files (vision, tech_stack, roadmap, map, dictionary, stub specs, etc.)]][[NO-SKILL: (Skill not installed: read `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`, follow mode: init review dimension table item by item)]]
 
     [[INCLUDE: shared/verify-result-handling.md]]
 </step_4_verify>
 
 <step_5_signoff>
-    **Terminal Gate** (Do not skip; must complete before output summary):
-    | Step | Command | Pass Condition |
-    |:---|:---|:---|
-    | 1 | `npx archi task --check` | No ERROR-level issues |
-    | 2 | `npx archi render` | `.md` views generated |
-
-    **Action** (After Gate passes):
-    1.  Run `npx archi task` to display task overview.
+    **Terminal Gate** (do not skip): Standard check (task --check + render).
+
+    **Pre-signoff Checklist** (confirm each item after Gate passes, before Output):
+    □ vision.md — filled (without Brief: inferred content annotated `(AI completion — review recommended)`)
+    □ 02_tech_stack.md — Sections 1-8 fully filled
+    □ roadmap.json — each functional module has a corresponding LEG-xx (status: done, tag: Legacy)
+    □ tasks/LEG-xx_<Slug>/spec.md — each LEG has a corresponding Stub spec (with related file list)
+    □ map.json — directoryMapping + logicalTopology + criticalUserJourneys + featureRelations all filled
+    □ dictionary.json + error_codes.json — extracted from codebase
+    □ (UI projects only) design_tokens.json + ui_concept.html + ui_context.md — Adopt mode executed
+    □ Step 4 Silent Audit — executed, all CRITICAL issues resolved
+
+    **Action** (after Checklist confirmed):
+    1.  Run `npx archi task` to output task overview.
     2.  Output summary.
 
-    **Output**: Reverse-engineering summary containing:
-    - **Project Overview**: Type, scale, number of core modules
-    - **Legacy Tasks**: LEG-xx list (ID / Name / Source location)
-    - **Generated Documents**: File list
-    - **AI Inferred Items**: Mark confidence level (High/Medium/Low)
+    **Output**: Reverse-engineering summary, including:
+    - **Project overview**: Type, scale, core module count
+    - **Legacy tasks**: LEG-xx list (ID / name / source location)
+    - **Generated docs**: File list
+    - **AI completions**: Mark confidence (High/Medium/Low)
     - **Next Steps**:
 
-    | Priority | Action | Description |
+    | Priority | Action | Notes |
     |:---|:---|:---|
-    | 1 | Review vision.md | Confirm AI-inferred vision description is accurate |
-    | 2 | `/archi.edit LEG-xx` | Enrich core module stubs into full specs (auto-triggers Enrich flow) |
-    | 3 | `/archi.scope [file_path]` | Plan new tasks/major modules |
-    | 4 | `/archi.plan <task ID>` | Deep-plan individual tasks |
+    | 1 | Review vision.md | Confirm AI-completed vision description |
+    | 2 | `/archi.edit LEG-xx` | Enrich core module stubs into full spec (auto-triggers Enrich flow) |
+    | 3 | `/archi.scope [file_path]` | Plan new features/major modules |
+    | 4 | `/archi.plan <task ID>` | Deep-plan individual task |
 </step_5_signoff>
 
 </protocol_inherit>

package/dist/templates/en/docs/prompts/map.md

@@ -1,131 +1,109 @@
 <protocol_map>
-  **Trigger**: `/archi.map`
-  **Goal**: Scan actual project directory structure, diff against `map.json`, identify additions/stale/changes, and update the architecture map after user confirmation.
+  **Trigger**: `/archi.map` | Auto-loaded by Workflow Dispatch on natural language trigger
+  **Goal**: Scan project actual directory structure, compare with `map.json`, identify additions/stale/changes; update architecture map after user confirmation.
 
 <meta>
     <style>Systematic, Precise, Architecture-Aware</style>
     <language>English</language>
     <principles>
-      1.  **Scan vs Map**: Actual filesystem is Ground Truth; map.json is the old snapshot.
-      2.  **Smart Granularity**: Directory-level by default; drill to file-level when a single file carries multiple responsibilities.
-      3.  **Architecture Inference**: New entry classification must reference existing map patterns + `02_tech_stack.md`.
-      4.  **Batch Confirm**: Present all changes at once; user confirms in batch.
+      1.  **Scan vs Map**: Actual filesystem is Ground Truth; map.json is old snapshot.
+      2.  **Smart Granularity**: Directory-level by default; when single file has multiple responsibilities, refine to file-level.
+      3.  **Architecture Inference**: New entry layer/location must reference existing map pattern + `02_tech_stack.md`.
+      4.  **Batch Confirm**: Show all changes at once; user confirms in batch.
+      5.  **IDE-Native First**: Leverage IDE native capabilities to drive execution rhythm; this protocol defines quality standards and checkpoints, not fight IDE planning/execution mechanisms.
     </principles>
 </meta>
 
 <step_1_scan>
-    **Role**: Surveyor
     **Action**:
     1.  **Read Map**: Read `[[__DOCS_DIR__]]/global/map.json` — current architecture map.
-    2.  **Read Tech Stack**: Read `02_tech_stack.md` — directory conventions, architecture patterns.
+    2.  **Read Tech Stack**: Read `02_tech_stack.md` — directory structure conventions, architecture pattern.
     3.  **Scan Directory Tree**: Scan project directory structure.
-        - **Exclude**: `.git/`, `node_modules/`, `dist/`, `build/`, `[[__DOCS_DIR__]]/`, and paths declared in `.gitignore`.
-        - **Depth**: Follow granularity patterns of existing map.json entries. If existing entries include file-level → scan to file-level too.
+        - **Exclude**: `.git/`, `node_modules/`, `dist/`, `build/`, `[[__DOCS_DIR__]]/`, and paths in `.gitignore`.
+        - **Depth**: Follow granularity pattern of existing map.json entries.
 
-    **Output**: Internal data (actual tree + existing map structure), not shown to user.
+    **Output**: Internal data (actual dir tree + existing map structure); not shown to user.
 </step_1_scan>
 
 <step_2_diff>
-    **Role**: Diff Analyst
-    **Action**: Compare actual directory tree against map.json entry by entry, classify into three diff types.
+    **Action**: Compare actual dir tree with map.json entry by entry; classify as three diff types.
 
     | Diff Type | Criteria | Handling |
     |:---|:---|:---|
-    | **New** | Exists on disk but not in map | Classify and register |
-    | **Stale** | In map but no longer exists on disk | Remove directly |
-    | **Possible Rename** | Map path missing, but a new path has highly similar structure/content | Flag as rename candidate |
+    | **New** | Exists in reality but not in map | Must classify and register |
+    | **Stale** | In map but no longer exists | Remove directly |
+    | **Suspected Rename** | Map path gone, but new path structure/content highly similar | Mark as rename candidate |
 
-    ### File-Level Detection
+    ### File-level detection
 
-    Quick-scan files in new directories (read exports/declarations) to identify **single-file multi-responsibility** cases:
-    - A file exporting multiple unrelated classes/functions/modules
-    - An entry file aggregating multiple sub-module registrations (e.g. route registration, store registration)
-    - A file serving multiple Tasks
+    Quick scan of files in new directories; identify **single file multi-responsibility** → refine granularity to file-level.
 
-    When detected → drill granularity to file-level, register the file separately in map with its contained responsibilities.
-
-    **Output**: Diff list (internal), proceed to step_3.
+    **Output**: Diff list (internal); proceed to step_3.
 </step_2_diff>
 
 <step_3_classify>
     **Role**: Chief Architect
-    **Action**: Classify new entries by architectural layer.
+    **Action**: Classify new entries by architecture.
 
-    ### Classification Strategy
+    ### Classification strategy
 
-    1.  **Pattern Matching**: Reference existing entries at the same level. If `src/services/auth/` is "Service Layer", then `src/services/payment/` likely is too.
-    2.  **Tech Stack Conventions**: Directory structure rules defined in `02_tech_stack.md` (e.g. "commands/ is Task Layer").
-    3.  **Content Inference**: Read file contents (imports, export types) to determine architectural role.
-    4.  **Uncertain**: Mark as `[?]`, let user specify during confirmation.
+    1.  **Pattern match**: Reference same-level existing entries in map.json.
+    2.  **Tech Stack conventions**: Directory structure rules in `02_tech_stack.md`.
+    3.  **Content inference**: Read file content (imports, exported types).
+    4.  **Cannot determine**: Mark `[?]` for user to specify.
 
-    For each new entry, populate:
-    - `path`: Directory or file path
-    - `layer`: Architectural layer
-    - `description`: One-line responsibility description
-    - `[?file-level]` `contains`: List of sub-responsibilities in the file
+    For each new entry fill: `path`, `layer`, `description`, `[?file-level] contains`.
 
-    **Output**: Classified new entries list (internal), proceed to step_4.
+    **Output**: Classified new entries list (internal); proceed to step_4.
 </step_3_classify>
 
 <step_4_propose>
-    **Role**: Advisor
-    **Action**: Present the full change manifest to user.
+    **Action**: Present full change list to user.
 
     **Output**:
     ```
     ### Architecture Map Change Proposal
 
     **Scan scope**: [project root]
-    **Current map entries**: N | **After update**: M
+    **Current map entries**: N | **After change**: M
 
     ---
 
-    #### Stale Entries (will remove)
-    | Path | Original Layer |
+    #### Stale entries (to remove)
+    | Path | Original layer |
     |:---|:---|
-    | src/legacy/old-module/ | Service Layer |
 
-    #### New Entries (will register)
+    #### New entries (to register)
     | Path | Layer | Description | Granularity |
     |:---|:---|:---|:---|
-    | src/services/payment/ | Service Layer | Payment service module | Directory |
-    | src/utils/validators.ts | Shared Layer | Form + data + API param validation | File |
-    | src/routes/api.ts [?] | [to specify] | Aggregates multiple API route registrations | File |
 
-    #### Possible Renames
-    | Original Path | New Path | Confidence |
+    #### Suspected renames
+    | Original path | New path | Confidence |
     |:---|:---|:---|
-    | src/helpers/ | src/utils/ | High (file content match) |
 
     ---
-    > Reply **OK** to confirm all; or specify changes:
-    > - "src/routes/api.ts belongs to App Layer"
-    > - "src/helpers/ is not a rename, keep original entry"
-    > - "add src/config/ as Config Layer"
+    > Reply **OK** to confirm all; or specify modifications.
     ```
 
     **Gate**: Proceed to step_5 after user confirms.
 </step_4_propose>
 
 <step_5_apply>
-    **Role**: System Administrator
     **Action**:
-    1.  Update `[[__DOCS_DIR__]]/global/map.json` per confirmed changes:
-        - Remove stale entries
-        - Add new entries (with layer, description)
-        - Handle renames (update path, preserve other metadata)
-    2.  Update `lastUpdated` field.
-
-    **Terminal Gate** (Do not skip; must complete before output summary):
-    | Step | Command | Pass Condition |
-    |:---|:---|:---|
-    | 1 | `npx archi render` | `.md` views generated |
+    1.  Update map.json per confirmed list (remove stale, add new, handle renames).
+    2.  Update `lastUpdated`.
+
+    **Terminal Gate** (do not skip): Standard check (task --check + render).
+
+    **Pre-signoff Checklist** (confirm each item before Output):
+    □ User explicitly confirmed change list in step_4 (Gate passed before execution)
+    □ Stale entries removed from directoryMapping
+    □ New entries correctly classified (path + layer + description all filled)
+    □ Renamed entries explicitly handled (not silently ignored)
+    □ lastUpdated updated
+    □ Terminal Gate — task --check + render passed
 
-    **Output**: Update summary:
-    - **Removed**: N stale entries
-    - **Added**: N entries (M file-level)
-    - **Renamed**: N entries
-    - **Current map total**: X entries
+    **Output**: Update summary — removed N / added N (M file-level) / renamed N / total entries.
 </step_5_apply>
 
 </protocol_map>