Sync .cursor from suite (autodev orchestrator + monorepo skills)

.cursor/skills/document/workflows/full.md

@@ -142,6 +142,37 @@ Re-entry is seamless: `state.json` tracks exactly which modules are done.
 
 ---
 
+### Step 2.5: Module Layout Derivation
+
+**Role**: Software architect
+**Goal**: Produce `_docs/02_document/module-layout.md` — the authoritative file-ownership map read by `/implement` Step 4, `/code-review` Phase 7, and `/refactor` discovery. Required for any downstream skill that assigns file ownership or checks architectural layering.
+
+This step derives the layout from the **existing** codebase rather than from a plan. Decompose Step 1.5 is the greenfield counterpart and uses the same template; this step uses the same output shape so downstream consumers don't branch on origin.
+
+1. For each component identified in Step 2, resolve its owning directory from module docs (Step 1) and from directory groupings used in Step 2.
+2. For each component, compute:
+   - **Public API**: exported symbols. Language-specific: Python — `__init__.py` re-exports + non-underscore root-level symbols; TypeScript — `index.ts` / barrel exports; C# — `public` types in the namespace root; Rust — `pub` items in `lib.rs` / `mod.rs`; Go — exported (capitalized) identifiers in the package root.
+   - **Internal**: everything else under the component's directory.
+   - **Owns**: the component's directory glob.
+   - **Imports from**: other components whose Public API this one references (parse imports; reuse tooling from Step 0's dependency graph).
+   - **Consumed by**: reverse of Imports from across all components.
+3. Identify `shared/*` directories already present in the code (or infer candidates: modules imported by ≥2 components and owning no domain logic). Create a Shared / Cross-Cutting entry per concern.
+4. Infer the Allowed Dependencies layering table by topologically sorting the import graph built in step 2. Components that import only from `shared/*` go to Layer 1; each successive layer imports only from lower layers.
+5. Write `_docs/02_document/module-layout.md` using `.cursor/skills/decompose/templates/module-layout.md`. At the top of the file add `**Status**: derived-from-code` and a `## Verification Needed` block listing any inference that was not clean (detected cycles, ambiguous ownership, components not cleanly assignable to a layer).
+
+**Self-verification**:
+- [ ] Every component from Step 2 has a Per-Component Mapping entry
+- [ ] Every Public API list is grounded in an actual exported symbol (no guesses)
+- [ ] No component's `Imports from` points at a component in a higher layer
+- [ ] Shared directories detected in code are listed under Shared / Cross-Cutting
+- [ ] Cycles from Step 0 that span components are surfaced in `## Verification Needed`
+
+**Save**: `_docs/02_document/module-layout.md`
+
+**BLOCKING**: Present the layering table and the `## Verification Needed` block to the user. Do NOT proceed until the user confirms (or patches) the derived layout. Downstream skills assume this file is accurate.
+
+---
+
 ### Step 3: System-Level Synthesis
 
 **Role**: Software architect
@@ -358,6 +389,8 @@ Using `.cursor/skills/plan/templates/final-report.md` as structure:
 │    (batched ~5 modules; session break between batches)           │
 │ 2. Component Assembly → group modules, write component specs     │
 │    [BLOCKING: user confirms components]                          │
+│ 2.5 Module Layout    → derive module-layout.md from code         │
+│    [BLOCKING: user confirms layout]                              │
 │ 3. System Synthesis   → architecture, flows, data model, deploy  │
 │ 4. Verification       → compare all docs vs code, fix errors     │
 │    [BLOCKING: user reviews corrections]                          │

.cursor/skills/document/workflows/task.md

@@ -26,6 +26,27 @@ One or more task spec files from `_docs/02_tasks/todo/` or `_docs/02_tasks/done/
 - System-level docs (only if the task changed API endpoints, data models, or external integrations)
 - Problem-level docs (only if the task changed input parameters, acceptance criteria, or restrictions)
 
+### Task Step 0.5: Import-Graph Ripple
+
+A module that changed may be imported by other modules whose docs are now stale even though those other modules themselves were not directly edited. Compute the reverse-dependency set and fold it into the update list.
+
+1. For each source file in the set of changed files from Step 0, build its module-level identifier (Python module path, C# namespace, Rust module path, TS import-specifier, Go package path — depending on the project language).
+2. Search the codebase for files that import from any of those identifiers. Preferred tooling per language:
+   - **Python**: `rg -e "^(from|import) <module>"` then parse with `ast` to confirm actual symbol use.
+   - **TypeScript / JavaScript**: `rg "from ['\"].*<path>"` then resolve via `tsconfig.json` paths / `jsconfig.json` if present.
+   - **C#**: `rg "^using <namespace>"` plus `.csproj` `ProjectReference` graph.
+   - **Rust**: `rg "use <crate>::"` plus `Cargo.toml` workspace members.
+   - **Go**: `rg "\"<module-path>\""` plus `go.mod` requires.
+
+   If a static analyzer is available for the project (e.g., `pydeps`, `madge`, `depcruise`, `NDepend`, `cargo modules`, `go list -deps`), prefer its output — it is more reliable than regex.
+3. For each importing file found, look up the component it belongs to via `_docs/02_document/module-layout.md` (if present) or by directory match against `DOCUMENT_DIR/components/`.
+4. Add every such component and module to the update list, even if it was not in the current cycle's task spec.
+5. Produce `_docs/02_document/ripple_log_cycle<N>.md` (where `<N>` is `state.cycle` from `_docs/_autodev_state.md`, default `1`) listing each downstream doc that was added to the refresh set and the reason (which changed file triggered it). Example line:
+   ```
+   - docs/components/02_ingestor.md — refreshed because src/ingestor/queue.py imports src/shared/serializer.py (changed by AZ-173)
+   ```
+6. When parsing imports fails (missing tooling, unsupported language), log the parse failure in the ripple log and fall back to a directory-proximity heuristic: any component whose source directory contains files matching the changed-file basenames. Note: heuristic mode is explicitly marked in the log so the user can request a manual pass.
+
 ### Task Step 1: Module Doc Updates
 
 For each affected module:
@@ -78,6 +99,7 @@ Present a summary of all docs updated:
  Component docs updated: [count]
  System-level docs updated: [list or "none"]
  Problem-level docs updated: [list or "none"]
+ Ripple-refreshed docs (imports changed indirectly): [count, see ripple_log_cycle<N>.md]
 ══════════════════════════════════════
 ```