@atlashub/smartstack-cli 1.33.0 → 1.35.0

package/templates/skills/_resources/mcp-validate-documentation-spec.md

@@ -0,0 +1,183 @@
+# MCP Tool Specification: validate_documentation
+
+## Status: FUTURE
+
+> This tool does not yet exist in SmartStack.mcp. This file is a specification for its implementation.
+> Until implemented, use the `docs-sync-checker` agent as a fallback.
+
+## Tool Definition
+
+```typescript
+{
+  name: "mcp__smartstack__validate_documentation",
+  description: "Validate documentation freshness, completeness, and accuracy for SmartStack modules",
+  parameters: {
+    module: {
+      type: "string",
+      description: "Module path (e.g., 'business/support/sla'). Empty for all modules.",
+      required: false
+    },
+    checkType: {
+      type: "string",
+      enum: ["freshness", "completeness", "accuracy", "all"],
+      default: "all",
+      description: "Type of validation to perform"
+    },
+    path: {
+      type: "string",
+      description: "Project path (default: SmartStack.app path from config)",
+      required: false
+    }
+  }
+}
+```
+
+## Check Types
+
+### freshness
+Compare `docs-manifest.json` with git history to detect stale documentation.
+
+**Input:** manifest entries, git log
+**Logic:**
+```
+FOR each module in manifest:
+  lastCodeCommit = git log -1 --format="%aI" -- {codeFiles}
+  IF lastCodeCommit > module.lastDocUpdate:
+    status = "drift"
+    driftDays = daysBetween(module.lastDocUpdate, lastCodeCommit)
+```
+
+**Output:**
+```json
+{
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "status": "drift",
+      "driftDays": 15,
+      "lastCodeChange": "2026-01-28",
+      "lastDocUpdate": "2026-01-13"
+    }
+  ]
+}
+```
+
+### completeness
+Verify that documented modules have all 8 business-first sections.
+
+**Input:** frd-data.ts files, i18n JSON files
+**Logic:**
+```
+FOR each module with documentation:
+  Read frd-data.ts
+  Check presence of:
+    1. overview (valeur métier)
+    2. useCases (cas d'usage)
+    3. benefits (bénéfices concrets) — in i18n
+    4. beforeAfter (avant/après) — in i18n
+    5. features (fonctionnalités)
+    6. steps (comment ça marche)
+    7. faq (FAQ métier) — in i18n
+    8. technicalRef (référence technique)
+  Report missing sections
+```
+
+**Output:**
+```json
+{
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "completeness": "6/8",
+      "missingSections": ["beforeAfter", "faq"],
+      "i18nComplete": { "fr": true, "en": false, "it": false, "de": false }
+    }
+  ]
+}
+```
+
+### accuracy
+Compare documented permissions, endpoints, and entities against actual code.
+
+**Input:** frd-data.ts, controllers, PermissionConfiguration.cs, entities
+**Logic:**
+```
+FOR each module:
+  documentedPermissions = frdData.permissions
+  actualPermissions = scan PermissionConfiguration.cs for module path
+  IF documentedPermissions != actualPermissions:
+    issues.push("permission mismatch")
+
+  documentedEndpoints = frdData.apiEndpoints
+  actualEndpoints = scan Controller for [Http*] attributes
+  IF documentedEndpoints != actualEndpoints:
+    issues.push("endpoint mismatch")
+
+  documentedEntities = frdData (entity references)
+  actualEntities = scan Domain/Entities for module
+  IF documentedEntities != actualEntities:
+    issues.push("entity mismatch")
+```
+
+**Output:**
+```json
+{
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "accuracy": "partial",
+      "issues": [
+        {
+          "type": "endpoint_mismatch",
+          "documented": ["GET /api/business/sla", "POST /api/business/sla"],
+          "actual": ["GET /api/business/sla", "POST /api/business/sla", "PATCH /api/business/sla/{id}/status"],
+          "message": "Endpoint PATCH /api/business/sla/{id}/status exists in code but not in documentation"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Combined Output (checkType: "all")
+
+```json
+{
+  "summary": {
+    "totalModules": 5,
+    "synced": 2,
+    "drift": 2,
+    "missing": 1,
+    "overallScore": "60%"
+  },
+  "modules": [
+    {
+      "path": "business/support/sla",
+      "freshness": { "status": "drift", "driftDays": 15 },
+      "completeness": { "score": "6/8", "missingSections": ["beforeAfter", "faq"] },
+      "accuracy": { "status": "partial", "issues": 1 }
+    }
+  ],
+  "recommendations": [
+    "Run `/apex -d` for business/support/sla to sync documentation",
+    "Run `/business-analyse` for business/support/tickets to create documentation"
+  ]
+}
+```
+
+## Integration Points
+
+| Consumer | When | Fallback |
+|----------|------|----------|
+| APEX step-04b (doc-sync) | After code validation | `docs-sync-checker` agent |
+| BA step-04 (validate) | During specification validation | Read manifest + git log |
+| APEX step-05 (examine) | During adversarial review | Manual checklist |
+| Drift hook (pre-commit) | Before commit | Bash script reading manifest |
+
+## Implementation Notes
+
+- Tool should read `docs-manifest.json` from project root
+- Must handle missing manifest gracefully (return "no manifest" status)
+- Git operations should use `--no-pager` flag
+- Performance: cache git log results across modules
+- The tool should be idempotent (no side effects)

package/templates/skills/_shared.md

@@ -138,3 +138,11 @@ if (entity.UserType == UserType.System || entity.UserType == UserType.LocalAdmin
 | `mcp__smartstack__validate_frontend_routes` | Valider synchronisation routes frontend/backend | step-04-validate |
 | `mcp__smartstack__scaffold_frontend_extension` | Générer infrastructure extension frontend | step-03-execute |
 | `mcp__smartstack__analyze_extension_points` | Analyser points d'extension dans les pages React | step-01-analyze |
+
+### Outils Documentation
+
+| Tool | Usage | Step APEX |
+|------|-------|-----------|
+| `mcp__smartstack__validate_documentation` | Valider fraîcheur, complétude et exactitude de la documentation (FUTURE - voir `_resources/mcp-validate-documentation-spec.md`) | step-04b-doc-sync |
+
+> **Fallback** : En attendant l'implémentation MCP, utiliser l'agent `docs-sync-checker` pour la détection de drift et l'agent `docs-context-reader` pour l'injection de contexte documentation.

package/templates/skills/apex/SKILL.md

@@ -49,6 +49,7 @@ See `<parameters>` for complete flag list.
 | `-s` | `--save` | Save mode: output each step to `.claude/output/apex/` |
 | `-t` | `--test` | Test mode: include test creation and runner steps |
 | `-e` | `--economy` | Economy mode: no subagents, save tokens |
+| `-d` | `--doc` | Documentation sync: update docs after validation (ON by default) |
 | `-r` | `--resume` | Resume mode: continue from a previous task |
 | `-b` | `--branch` | Branch mode: verify not on main, create branch if needed |
 | `-pr` | `--pull-request` | PR mode: create pull request at end (enables -b) |
@@ -62,6 +63,7 @@ See `<parameters>` for complete flag list.
 | `-S` | `--no-save` | Disable save mode |
 | `-T` | `--no-test` | Disable test mode |
 | `-E` | `--no-economy` | Disable economy mode |
+| `-D` | `--no-doc` | Disable documentation sync |
 | `-B` | `--no-branch` | Disable branch mode |
 | `-PR` | `--no-pull-request` | Disable PR mode |
 </flags>
@@ -133,6 +135,7 @@ All outputs saved to PROJECT directory:
 ├── 02-plan.md        # Implementation plan
 ├── 03-execute.md     # Execution log
 ├── 04-validate.md    # Validation results
+├── 04b-doc-sync.md   # Documentation sync (if -d)
 ├── 05-examine.md     # Review findings (if -x)
 ├── 06-resolve.md     # Resolution log (if -x)
 ├── 07-tests.md       # Test creation (if -t)
@@ -161,6 +164,7 @@ When provided, step-00 will:
 5. Load step-02-plan.md -> create strategy
 6. Load step-03-execute.md -> implement
 7. Load step-04-validate.md -> verify
+7b. If `{doc_mode}` = true: Load step-04b-doc-sync.md -> sync documentation
 8. If `--test`: Load step-07-tests.md -> create tests
 9. If `--test`: Load step-08-run-tests.md -> run until green
 10. If `-x` or user requests: Load step-05-examine.md -> adversarial review
@@ -182,6 +186,7 @@ When provided, step-00 will:
 | `{save_mode}`           | boolean | Save outputs to .claude/output/apex/                   |
 | `{test_mode}`           | boolean | Include test steps (07-08)                             |
 | `{economy_mode}`        | boolean | No subagents, direct tool usage only                   |
+| `{doc_mode}`            | boolean | Documentation sync after validation (ON by default)    |
 | `{branch_mode}`         | boolean | Verify not on main, create branch if needed            |
 | `{pr_mode}`             | boolean | Create pull request at end                             |
 | `{interactive_mode}`    | boolean | Configure flags interactively                          |
@@ -207,6 +212,7 @@ When provided, step-00 will:
 | 02   | `steps/step-02-plan.md`      | File-by-file implementation strategy                 |
 | 03   | `steps/step-03-execute.md`   | Todo-driven implementation                           |
 | 04   | `steps/step-04-validate.md`  | Self-check and validation                            |
+| 04b  | `steps/step-04b-doc-sync.md` | Documentation sync (if doc_mode, manifest exists)    |
 | 05   | `steps/step-05-examine.md`   | Adversarial code review (optional)                   |
 | 06   | `steps/step-06-resolve.md`   | Finding resolution (optional)                        |
 | 07   | `steps/step-07-tests.md`     | Test analysis and creation (if --test)               |

package/templates/skills/apex/steps/step-00-init.md

@@ -29,6 +29,7 @@ examine_mode: false   # -x: Auto-proceed to adversarial review
 save_mode: false      # -s: Save outputs to .claude/output/apex/
 test_mode: false      # -t: Include test creation and runner steps
 economy_mode: false   # -e: No subagents, save tokens
+doc_mode: true        # -d: Documentation sync (ON by default)
 ```
 </defaults>
 
@@ -46,6 +47,7 @@ economy_mode: false   # -e: No subagents, save tokens
 {save_mode}    = false
 {test_mode}    = false
 {economy_mode} = false
+{doc_mode}     = true
 ```
 
 **Step 2: Parse user input and override defaults:**
@@ -57,6 +59,7 @@ Enable flags (lowercase - turn ON):
   -s or --save     -> {save_mode} = true
   -t or --test     -> {test_mode} = true
   -e or --economy  -> {economy_mode} = true
+  -d or --doc      -> {doc_mode} = true
 
 Disable flags (UPPERCASE - turn OFF):
   -A or --no-auto         -> {auto_mode} = false
@@ -64,6 +67,7 @@ Disable flags (UPPERCASE - turn OFF):
   -S or --no-save         -> {save_mode} = false
   -T or --no-test         -> {test_mode} = false
   -E or --no-economy      -> {economy_mode} = false
+  -D or --no-doc          -> {doc_mode} = false
 
 Other:
   -r or --resume   -> {resume_task} = <next argument>
@@ -115,6 +119,8 @@ questions:
         description: "Include test creation and runner steps"
       - label: "Economy mode (-e)"
         description: "No subagents, direct tools only (saves tokens)"
+      - label: "Doc sync mode (-d) — ON by default"
+        description: "Sync documentation after validation (disable with -D)"
     multiSelect: true
 ```
 
@@ -141,6 +147,7 @@ questions:
 | Save mode | {save_mode} |
 | Test mode | {test_mode} |
 | Economy mode | {economy_mode} |
+| Doc mode | {doc_mode} |
 
 ## User Request
 
@@ -159,6 +166,7 @@ _To be defined in step-01-analyze_
 | 02-plan | Pending |
 | 03-execute | Pending |
 | 04-validate | Pending |
+| 04b-doc-sync | {doc_mode ? "Pending" : "Skip"} |
 | 05-examine | {examine_mode ? "Pending" : "Skip"} |
 | 06-resolve | {examine_mode ? "Pending" : "Skip"} |
 | 07-tests | {test_mode ? "Pending" : "Skip"} |
@@ -182,6 +190,7 @@ APEX: {task_description}
 | {save_mode} | true/false |
 | {test_mode} | true/false |
 | {economy_mode} | true/false |
+| {doc_mode} | true/false |
 
 -> Analyzing...
 ```

package/templates/skills/apex/steps/step-01-analyze.md

@@ -182,6 +182,42 @@ Write findings to `{output_dir}/01-analyze.md`:
 - Add timestamp at the end
 - Update 00-context.md Progress table: 01-analyze -> Complete
 
+### 6b. Generate Context Digest (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Generate a compact digest (max 50 lines) for inter-step context transfer.
+Use the template from `_resources/context-digest-template.md`.
+
+```markdown
+## Context Digest — step-01-analyze
+
+### Changes
+- N/A (analysis only)
+
+### Decisions
+- {key architectural or approach decisions from analysis}
+
+### Findings
+- {most important files found with paths}
+- {patterns identified, utilities available}
+
+### State
+- {acceptance_criteria}: [inferred list]
+- Files analyzed: {count}
+
+### Blockers
+- {open questions or ambiguities}
+
+### Next
+- Step-02 should focus on: {key areas for planning}
+```
+
+Write digest to `{output_dir}/01-analyze-digest.md`
+
+**Purpose:** Step-02 reads ONLY this digest (not the full 01-analyze.md) to minimize token usage.
+Exception: If `{resume_task}` is set, read the full output instead.
+
 ### 7. Present Context Summary
 
 ```

package/templates/skills/apex/steps/step-02-plan.md

@@ -153,6 +153,44 @@ Write plan to `{output_dir}/02-plan.md`:
 - Add timestamp
 - Update 00-context.md Progress table: 02-plan -> Complete
 
+### 5b. Generate Context Digest (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Generate a compact digest (max 50 lines) for inter-step context transfer.
+Use the template from `_resources/context-digest-template.md`.
+
+```markdown
+## Context Digest — step-02-plan
+
+### Changes
+- {files planned for modification with summary}
+
+### Decisions
+- {approach chosen and why}
+- {key design decisions}
+
+### Findings
+- {risks identified}
+- {dependencies between files}
+
+### State
+- Plan approved: {yes/no}
+- Files to modify: {count}
+- New files: {count}
+
+### Blockers
+- {any user questions pending}
+
+### Next
+- Step-03 should implement files in this order: {ordered list}
+```
+
+Write digest to `{output_dir}/02-plan-digest.md`
+
+**Purpose:** Step-03 reads ONLY this digest + the plan structure (not full analysis) to minimize token usage.
+Exception: If `{resume_task}` is set, read the full outputs instead.
+
 ### 6. Present Plan for Approval
 
 ```

package/templates/skills/apex/steps/step-03-execute.md

@@ -153,6 +153,45 @@ Finalize `{output_dir}/03-execute.md` with:
 
 **Then proceed to validation.**
 
+### 6b. Generate Context Digest (if save_mode)
+
+**If `{save_mode}` = true:**
+
+Generate a compact digest (max 50 lines) for inter-step context transfer.
+Use the template from `_resources/context-digest-template.md`.
+
+```markdown
+## Context Digest — step-03-execute
+
+### Changes
+- {files modified with line ranges and summary}
+- {new files created}
+
+### Decisions
+- {implementation choices made during execution}
+
+### Findings
+- {issues encountered and how resolved}
+- {patterns that deviated from plan}
+
+### State
+- Todos completed: {X}/{Y}
+- Files modified: {count}
+- Files created: {count}
+
+### Blockers
+- {any remaining issues}
+
+### Next
+- Step-04 should validate: {specific checks needed}
+- Files to verify: {list of modified files}
+```
+
+Write digest to `{output_dir}/03-execute-digest.md`
+
+**Purpose:** Step-04 reads ONLY this digest (not full execution log) to minimize token usage.
+Exception: If `{resume_task}` is set, read the full outputs instead.
+
 ---
 
 ## SUCCESS METRICS:

package/templates/skills/apex/steps/step-04-validate.md

@@ -35,6 +35,7 @@ From previous steps:
 | `{save_mode}` | Save outputs to files |
 | `{test_mode}` | Include test steps |
 | `{examine_mode}` | Auto-proceed to review |
+| `{doc_mode}` | Documentation sync enabled |
 | `{output_dir}` | Path to output (if save_mode) |
 | Implementation | Completed in step-03 |
 </available_state>
@@ -111,6 +112,32 @@ mcp__smartstack__check_migrations:
 - [ ] Tenant isolation (ITenantEntity where required)
 - [ ] Controller routes (NavRoute attributes)
 
+### 3b. Documentation Impact Check (informative)
+
+**If `{doc_mode}` = true:**
+
+Check if `docs-manifest.json` exists in the project root. If it does:
+
+1. Read `docs-manifest.json`
+2. Compare modified files (from step-03 todos) against `codeFiles` in manifest
+3. For each impacted module, note:
+   - Module name and featureId
+   - Last documentation update date
+   - Which code-to-doc mapping applies (entity → businessRules, controller → apiEndpoints, etc.)
+
+**Report (informative only, does not block validation):**
+
+```
+Documentation Impact:
+- Module: {app}/{module} (FEAT-NNN) — last doc update: {date}
+  - Entity changes → businessRules, features may need update
+  - Controller changes → apiEndpoints need update
+```
+
+**If `docs-manifest.json` absent:** Skip silently.
+
+> **Note:** Actual documentation sync happens in step-04b-doc-sync.md (next step if doc_mode enabled).
+
 ### 4. Self-Audit Checklist
 
 Verify each item:
@@ -185,7 +212,10 @@ Write to `{output_dir}/04-validate.md`:
 **Decision tree:**
 
 ```
-IF {test_mode} = true:
+IF {doc_mode} = true AND docs-manifest.json exists:
+    -> Load step-04b-doc-sync.md (documentation sync)
+
+ELSE IF {test_mode} = true:
     -> Load step-07-tests.md (test analysis and creation)
 
 ELSE IF {examine_mode} = true:

package/templates/skills/apex/steps/step-04b-doc-sync.md

@@ -0,0 +1,162 @@
+---
+name: step-04b-doc-sync
+description: Documentation sync - detect affected modules and update documentation
+prev_step: steps/step-04-validate.md
+next_step: steps/step-05-examine.md
+---
+
+# Step 4b: Documentation Sync
+
+## MANDATORY EXECUTION RULES:
+
+- NEVER skip this step when {doc_mode} = true
+- NEVER create documentation from scratch (that is BA skill's job)
+- ALWAYS update existing documentation only
+- ALWAYS update docs-manifest.json after changes
+- IF docs-manifest.json is absent → skip with note "No documentation manifest found"
+
+## YOUR TASK:
+
+Detect which documented modules are affected by the code changes and update their documentation data files.
+
+---
+
+<available_state>
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{task_description}` | What was implemented |
+| `{task_id}` | Full task identifier |
+| `{doc_mode}` | Documentation sync enabled (should be true) |
+| `{economy_mode}` | No subagents if true |
+| `{save_mode}` | Save outputs to disk |
+| `{output_dir}` | Output directory path |
+</available_state>
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Check Documentation Manifest
+
+Read `docs-manifest.json` from project root.
+
+**If absent:**
+```
+Display: "No docs-manifest.json found. Skipping documentation sync."
+Display: "TIP: Run /business-analyse to create documentation for your modules."
+→ Load next step
+```
+
+**If present:** Continue.
+
+### 2. Identify Affected Modules
+
+Get files modified during step-03 (from TodoList or git diff):
+
+```bash
+git diff --name-only HEAD~1
+```
+
+Match modified files against `codeFiles` in each manifest module entry.
+
+**Build affected modules list:**
+
+| Module | Changed Files | Impact |
+|--------|---------------|--------|
+| business/{app}/{module} | [list] | [sections] |
+
+### 3. Map Code Changes to Documentation Sections
+
+For each affected module, classify changes:
+
+| Code Change Pattern | Documentation Section |
+|--------------------|-----------------------|
+| `**/Entities/**` modified | businessRules, features |
+| `**/Controllers/**` modified | apiEndpoints, technicalRef |
+| `**/Permissions*` modified | permissions |
+| `**/Validators/**` modified | businessRules |
+| `**/i18n/**` modified | useCases (labels), faq |
+| `**/Migrations/**` created | technicalRef |
+| `**/DTOs/**` modified | apiEndpoints |
+| `**/Commands/**` modified | useCases, features |
+| `**/Queries/**` modified | useCases, features |
+
+### 4. Read Current Documentation
+
+For each affected module:
+
+**If {economy_mode} = false:**
+- Launch `docs-context-reader` agent for the module
+- Agent returns structured summary of current doc state
+
+**If {economy_mode} = true:**
+- Read `frd-data.ts` directly
+- Read i18n FR file directly
+
+### 5. Update Documentation Data
+
+For each affected module and impacted section:
+
+1. Read current `frd-data.ts`
+2. Compare with actual code state
+3. Update affected fields:
+   - **apiEndpoints**: Scan controller for `[Http*]` attributes
+   - **permissions**: Scan PermissionConfiguration.cs for module
+   - **businessRules**: Scan validators and entity methods
+   - **useCases**: Update if commands/queries changed
+   - **features**: Update if new functionality added
+4. Write updated `frd-data.ts`
+5. Update i18n FR file if label keys changed
+
+### 6. Update Documentation Manifest
+
+For each updated module:
+
+```json
+{
+  "lastDocUpdate": "{current_timestamp}",
+  "gitCommitDoc": "{current_commit_sha}",
+  "status": "synced"
+}
+```
+
+Update `docs-manifest.json` root `lastUpdated`.
+
+### 7. Save Output (if save_mode)
+
+Write `{output_dir}/04b-doc-sync.md` with:
+- Modules checked
+- Modules updated
+- Sections modified
+- Files changed
+
+---
+
+## SUCCESS METRICS:
+
+- All affected modules identified
+- Documentation data files updated for impacted sections
+- docs-manifest.json timestamps updated
+- No new documentation created (only updates)
+
+## FAILURE MODES:
+
+- docs-manifest.json absent → skip gracefully (not a failure)
+- frd-data.ts has unexpected format → report warning, skip module
+- No modules affected → display "No documented modules affected by changes"
+
+---
+
+## NEXT STEP:
+
+```
+IF {test_mode} = true AND step-07 not yet done:
+    → Load steps/step-07-tests.md
+ELSE IF {examine_mode} = true:
+    → Load steps/step-05-examine.md
+ELSE:
+    → Display completion summary
+    → IF {pr_mode} = true: Load steps/step-09-finish.md
+```

package/templates/skills/apex/steps/step-05-examine.md

@@ -75,6 +75,13 @@ Self-review with checklist:
 - [ ] Follows existing patterns
 - [ ] No code duplication
 - [ ] Clear naming
+
+## Documentation Checklist
+- [ ] Documented modules updated (frd-data.ts reflects code changes)
+- [ ] API endpoints reflected in documentation
+- [ ] Documented permissions match code
+- [ ] i18n keys added for new labels
+- [ ] docs-manifest.json timestamps current
 ```
 
 **If `{economy_mode}` = false:**