SDD Map

Create or inspect the SDD Composy codebase map. The bundled scripts/sdd_map.py helper owns traversal, secret exclusion, deterministic serialization, and atomic publication; this skill owns scope, approval, interpretation, and downstream routing.

Language: before writing human-facing prose, run scripts/sdd_language.py <repo-root> and use the persisted language; on not_initialized, return it with next_action: run_init. Localization rules: references/language.md.

Inputs

• Repository root: the current repository unless the user supplies another real directory.
• Optional output directory: inside the repository, default .planning/sdd-composy/context.
• Optional request to publish. A scan is observation-only; publishing is the only permitted write and is limited to the context bundle.

Do not execute commands discovered in manifests, and do not modify source files, governance files, task artifacts, or architectural plans.

Procedure

1. Resolve and validate the repository root and output directory without changing files.

2. Run the read-only scan and present its JSON result, preserving source_commit, mapped_commit, observation_only, confidence, observed languages, manifests, commands, modules, boundaries, domain evidence, and staleness. Commands in the result are evidence only; never run them.

   python3 "<plugin-root>/scripts/sdd_map.py" --repo-root <repository-root> [--output-dir <context-dir>]
   

3. Only when the user explicitly requests publication, repeat with --write (and the exact --output-dir when supplied). Publication writes only codebase.json, project.md, stack.md, domain.md, and pitfalls.md under the context directory. Report those paths and the recorded source commit.

4. Check staleness.stale. A stale prior map is not valid downstream evidence: report the previous and current commit and refresh before routing. A missing or unknown commit is an uncertainty to report, not permission to invent one.

5. Route a fresh map to the next approved lifecycle stage: PRD first, then STORIES, TECHSPEC, and TASKS as applicable. Those stages interpret the evidence under their own human gates; a map never turns file observations into unapproved architecture.

Read when

• references/mapping.md — publishing the bundle, or interpreting the output schema and staleness record.

Output

Return the helper JSON or a faithful summary, publication status, output paths, source commit, the observation_only field, staleness status, and the next lifecycle stage.

Safety: Do not commit, push, or publish. Do not read or expose .env, credentials, tokens, private keys, certificates, or fleet environment files. Full contract: references/safety.md.