@ktpartners/dgs-platform 2.7.4 → 2.8.0

package/deliver-great-systems/workflows/init-product.md

@@ -1,12 +1,12 @@
 <purpose>
-Initialize a v2 multi-project product folder. Creates REPOS.md, PROJECTS.md, discovers repos. Handles fresh install, v1 detection, and already-initialized cases. Supports root-mode layout for dedicated planning repos.
+Initialize a v2 multi-project product folder. Creates REPOS.md, PROJECTS.md, discovers repos. Handles fresh install and already-initialized cases.
 </purpose>
 
 <context_tier>lite</context_tier>
 
 <process>
 
-## 0. Load Context and Detect Layout
+## 0. Load Context
 
 Load project context via tier system:
 ```bash
@@ -15,86 +15,6 @@ TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" contex
 
 Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
 
-Run layout detection:
-```bash
-LAYOUT_RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos detect-layout --raw)
-```
-
-Parse the JSON response to get the `suggested` field (`'root'` or `'dotplanning'`).
-
-If the response indicates an existing layout is already configured (e.g., `v1_detected`, `already_initialized`, or existing `.planning/` directory), skip the layout prompt and proceed directly to Step 1 with `LAYOUT_MODE` unset. The v1/v2 handlers in Steps 3-4 will handle those cases.
-
-For fresh repos only, present the layout choice using AskUserQuestion:
-
-```
-AskUserQuestion([{
-  question: "How should DGS organize planning files in this repo?",
-  header: "Repository Layout",
-  multiSelect: false,
-  options: [
-    { label: "Root mode — planning files at repo root", description: "For dedicated planning repos where all files are DGS artifacts" },
-    { label: ".planning/ mode — planning files in subdirectory", description: "For repos that also contain source code" }
-  ]
-}])
-```
-
-Pre-select the option matching `suggested` from the detection result.
-
-If user selects "Root mode": set `LAYOUT_MODE="root"`, proceed to Step 0a (namespace warning).
-If user selects ".planning/ mode": set `LAYOUT_MODE="dotplanning"`, skip Step 0a, proceed to Step 1 (Get Product Name).
-
-## 0a. Namespace Warning (root-mode only)
-
-This step only runs if `LAYOUT_MODE="root"`.
-
-Display warning:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► ROOT MODE WARNING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Warning: Root-mode assumes this entire repo is for DGS.
-Don't use this in a repo with existing source code.
-
-DGS will create the following directories at the repo root:
-  - phases/
-  - ideas/ (pending, rejected, done)
-  - specs/
-  - docs/product/
-  - jobs/ (when needed)
-
-And these files:
-  - PROJECT.md
-  - ROADMAP.md
-  - REPOS.md
-  - PROJECTS.md
-  - dgs.config.json
-  - .gitignore (created or updated)
-```
-
-Use AskUserQuestion for blocking confirmation:
-
-```
-AskUserQuestion([{
-  question: "Proceed with root-mode setup?",
-  header: "Confirm",
-  multiSelect: false,
-  options: [
-    { label: "Yes, proceed", description: "Create DGS planning structure at repo root" },
-    { label: "Cancel", description: "Exit without creating anything" }
-  ]
-}])
-```
-
-If user selects "Cancel":
-```
-Setup cancelled. Run `/dgs:init-product` again to restart.
-```
-Exit.
-
-If user selects "Yes, proceed": continue to Step 1 (Get Product Name).
-
 ## 1. Get Product Name
 
 If `$ARGUMENTS` contains a product name, use it.
@@ -106,350 +26,13 @@ What would you like to name this product? (e.g., "my-saas-app", "mobile-platform
 
 ## 2. Run Init Product
 
-If `LAYOUT_MODE` is `"root"`, pass the `--layout root` flag:
-
 ```bash
-RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos init-product "$PRODUCT_NAME" --layout root --raw)
-```
-
-If `LAYOUT_MODE` is `"dotplanning"` or unset, use the existing command without the flag (unchanged behavior):
-
-```bash
-RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos init-product "$PRODUCT_NAME" --raw)
+RESULT=$(node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs repos init-product "$PRODUCT_NAME" --raw)
 ```
 
 Parse JSON response. Route to the appropriate handler based on the response shape.
 
-## 3. Handle v1 Detected
-
-If response contains `v1_detected: true`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► INIT PRODUCT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Existing v1 DGS setup detected (project: "{project_name}").
-```
-
-Use AskUserQuestion:
-- header: "Migration"
-- question: "Migrate '{project_name}' to v2 multi-project mode? This moves your planning files into a project subfolder. A backup git tag is created before any changes."
-- options:
-  - "Migrate to v2" — Move planning files to project subfolder, enable multi-project
-  - "Keep v1 mode" — No changes, v1 continues working (permanent, won't ask again)
-
-**If "Migrate to v2":**
-
-```bash
-MIGRATE_RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos migrate "{slug}" --raw)
-```
-
-Parse JSON. If `migrated: true`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► MIGRATION COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Project "{project_name}" migrated to v2.
-
-Files moved: {files_moved}
-Backup tag: dgs-pre-v2-migration
-Current project: {slug}
-```
-
-**Configure Base Branch (after migration):**
-
-Prompt the user for their code repo base branch:
-
-```
-AskUserQuestion([{
-  question: "What is the base branch for your code repos? (e.g., main, develop, dev)",
-  header: "Git Configuration",
-  multiSelect: false,
-  freeform: true,
-  placeholder: ""
-}])
-```
-
-Always ask — no auto-detection, no default pre-fill. The user types the branch name explicitly.
-
-After receiving the answer, write to config:
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set git.base_branch "$USER_ANSWER"
-```
-
-If the user provides an empty answer or skips, do NOT write anything — the default `main` from config-ensure-section already provides the fallback.
-
-**Configure Workflow Discipline:**
-
-Read the CLAUDE.md template:
-```bash
-CLAUDE_TEMPLATE=$(cat ~/.claude/deliver-great-systems/templates/claude-md.md)
-```
-
-Use AskUserQuestion:
-```
-AskUserQuestion([{
-  question: "Enable workflow discipline? This adds a CLAUDE.md file that routes code changes through /dgs:* commands for traceability and atomic commits. Read-only operations (searching, tests, git log) stay unrestricted.",
-  header: "Workflow Discipline",
-  multiSelect: false,
-  options: [
-    { label: "Yes (Recommended)", description: "Creates CLAUDE.md with DGS command routing rules" },
-    { label: "No", description: "Skip — no CLAUDE.md created" }
-  ]
-}])
-```
-
-**If "Yes":**
-
-Check if `./CLAUDE.md` already exists in the project root (cwd):
-
-- **If CLAUDE.md does NOT exist:** Create `./CLAUDE.md` with DGS section delimiters wrapping the template content:
-
-```
-<!-- DGS:BEGIN — managed by deliver-great-systems, do not edit this section manually -->
-{CLAUDE_TEMPLATE content}
-<!-- DGS:END -->
-```
-
-- **If CLAUDE.md ALREADY exists:** Read existing content. Check if it already contains `<!-- DGS:BEGIN`.
-  - If DGS section already present: replace everything between `<!-- DGS:BEGIN` and `<!-- DGS:END -->` (inclusive) with the latest template version (idempotent update).
-  - If no DGS section: append to the end of the file, separated by a blank line:
-
-```
-{existing CLAUDE.md content}
-
-<!-- DGS:BEGIN — managed by deliver-great-systems, do not edit this section manually -->
-{CLAUDE_TEMPLATE content}
-<!-- DGS:END -->
-```
-
-Set config:
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline true
-```
-
-Display: `Workflow discipline enabled — CLAUDE.md added.`
-
-Add `CLAUDE.md` to the commit file list for the init commit that follows (the `dgs-tools.cjs commit` call at the end of the flow).
-
-**If "No":**
-
-Set config:
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline false
-```
-
-Display: `Skipped.`
-
-Do NOT create or modify CLAUDE.md. Do NOT add CLAUDE.md to any commit.
-
-**Configure Workflow Preferences (Round 1 — Core settings):**
-
-```
-AskUserQuestion([
-  {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
-  {
-    header: "Depth",
-    question: "How thorough should planning be?",
-    multiSelect: false,
-    options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Git Tracking",
-    question: "Commit planning docs to git?",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
-      { label: "No", description: "Keep planning docs local-only (add to .gitignore)" }
-    ]
-  },
-  {
-    header: "Branching",
-    question: "Git branching strategy?",
-    multiSelect: false,
-    options: [
-      { label: "None (Recommended)", description: "Commit to current branch (fine for single projects)" },
-      { label: "Per Phase", description: "Branch per phase, review before merging" },
-      { label: "Per Milestone", description: "Branch per project, merge all at end (for parallel projects)" }
-    ]
-  }
-])
-```
-
-**Configure Workflow Preferences (Round 2 — Agents):**
-
-```
-AskUserQuestion([
-  {
-    header: "AI Models",
-    question: "Which AI models for planning agents?",
-    multiSelect: false,
-    options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
-    ]
-  },
-  {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  }
-])
-```
-
-**Write config.json** with all values collected above:
-
-```json
-{
-  "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
-  "parallelization": true,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false,
-    "nyquist_validation": true,
-    "auto_advance": false,
-    "discipline": true|false
-  },
-  "git": {
-    "branching_strategy": "none|phase|milestone",
-    "base_branch": "[from earlier question]",
-    "sync_push": "prompt",
-    "sync_pull": "prompt"
-  }
-}
-```
-
-Smart defaults (not asked): `parallelization: true`, `auto_advance: false`, `nyquist_validation: true`.
-
-**If commit_docs = No:** Add the planning root directory to `.gitignore`.
-
-**Commit config:**
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: add product config" --files ${config_path}
-```
-
-**Branch name preview:** If `branching_strategy` is not `"none"`, show:
-```
-Branch names will look like: dgs/{project-slug}/phase-03-auth
-```
-
-**Commit migrated files:**
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: migrate product to v2 multi-project" --files .planning/REPOS.md .planning/PROJECTS.md dgs.config.json CLAUDE.md
-```
-
-Only include CLAUDE.md in the --files list if workflow discipline was enabled (user answered Yes).
-
-```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Create another project** or start working
-
-`/dgs:new-project` — add a second project
-`/dgs:progress` — see current status
-
-<sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-```
-
-If migration fails (error response):
-
-```
-Migration failed: {error_message}
-
-Your v1 setup is unchanged (rollback applied automatically).
-Backup tag 'dgs-pre-v2-migration' was created before the attempt.
-
-To retry: `/dgs:init-product`
-To continue with v1: No action needed — v1 works as before.
-```
-
-Exit.
-
-**If "Keep v1 mode":**
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set v1_decline_migration true
-```
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► INIT PRODUCT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-v1 mode preserved. Your DGS setup continues to work unchanged.
-
-This choice is permanent — you won't be prompted again.
-To continue using DGS, run `/dgs:new-project` as usual.
-```
-
-Exit.
-
-## 3a. Handle v1 Declined (previously declined migration)
-
-If response contains `v1_declined: true`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► INIT PRODUCT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-v1 mode is active (migration was previously declined).
-Your DGS setup continues to work unchanged.
-
-To continue: `/dgs:new-project`
-```
-
-Exit.
-
-## 4. Handle Already Initialized
+## 3. Handle Already Initialized
 
 If response contains an error about already initialized:
 
@@ -466,7 +49,7 @@ To see existing projects: `/dgs:list-projects`
 
 Exit.
 
-## 5. Handle Fresh Install Success
+## 4. Handle Fresh Install Success
 
 If response contains `initialized: true`:
 
@@ -492,7 +75,7 @@ For each repo in `repos` array:
   - {repo.name} ({repo.path})
 ```
 
-If root-mode (`layout: 'root'` in response or `LAYOUT_MODE="root"`), display:
+Display:
 ```
 Created:
   - REPOS.md
@@ -500,25 +83,11 @@ Created:
   - ideas/ (pending, rejected, done)
   - specs/
   - docs/product/
-  - dgs.config.json
+  - config.json
   - review-keys.json
   - .gitignore
 ```
 
-If standard .planning/ mode (existing behavior), display:
-```
-Created:
-  - .planning/REPOS.md
-  - .planning/PROJECTS.md
-  - .planning/ideas/ (pending, rejected, done)
-  - .planning/specs/
-  - .planning/docs/product/
-  - dgs.config.json (updated)
-  - .planning/review-keys.json
-```
-
-If `gitignore_synced` is true in the response (standard mode only), also show: `  - .gitignore (synced)`
-
 **b2. Configure Base Branch:**
 
 Prompt the user for their code repo base branch:
@@ -537,7 +106,7 @@ Always ask — no auto-detection, no default pre-fill. The user types the branch
 
 After receiving the answer, write to config:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set git.base_branch "$USER_ANSWER"
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set git.base_branch "$USER_ANSWER"
 ```
 
 If the user provides an empty answer or skips, do NOT write anything — the default `main` from config-ensure-section already provides the fallback.
@@ -546,7 +115,7 @@ If the user provides an empty answer or skips, do NOT write anything — the def
 
 Read the CLAUDE.md template:
 ```bash
-CLAUDE_TEMPLATE=$(cat ~/.claude/deliver-great-systems/templates/claude-md.md)
+CLAUDE_TEMPLATE=$(cat /Users/adrian/.claude/deliver-great-systems/templates/claude-md.md)
 ```
 
 Use AskUserQuestion:
@@ -588,7 +157,7 @@ Check if `./CLAUDE.md` already exists in the project root (cwd):
 
 Set config:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline true
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline true
 ```
 
 Display: `Workflow discipline enabled — CLAUDE.md added.`
@@ -599,7 +168,7 @@ Add `CLAUDE.md` to the commit file list for the init commit that follows (the `d
 
 Set config:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline false
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs config-set workflow.discipline false
 ```
 
 Display: `Skipped.`
@@ -728,7 +297,7 @@ Smart defaults (not asked): `parallelization: true`, `auto_advance: false`, `nyq
 **Commit config:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: add product config" --files ${config_path}
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: add product config" --files ${config_path}
 ```
 
 **Branch name preview:** If `branching_strategy` is not `"none"`, show:
@@ -738,16 +307,10 @@ Branch names will look like: dgs/{project-slug}/phase-03-auth
 
 **b7. Commit initialized files:**
 
-For root-mode (`LAYOUT_MODE="root"`), use the `files_created` array from the init response to build the commit file list:
-
-```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize product ${product_name} (root layout)" --files REPOS.md PROJECTS.md dgs.config.json .gitignore CLAUDE.md
-```
-
-For standard .planning/ mode, use the existing commit:
+Use the `files_created` array from the init response to build the commit file list:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize product ${product_name}" --files .planning/REPOS.md .planning/PROJECTS.md dgs.config.json CLAUDE.md
+node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize product ${product_name}" --files REPOS.md PROJECTS.md config.json .gitignore CLAUDE.md
 ```
 
 Only include CLAUDE.md in the --files list if workflow discipline was enabled (user answered Yes).

package/deliver-great-systems/workflows/map-codebase.md

@@ -4,6 +4,8 @@ Orchestrate parallel codebase mapper agents to analyze registered repos and prod
 Supports two modes:
 - **Refresh mode** (default): Clears all per-repo subdirectories and unified files, then remaps everything from scratch.
 - **Update mode** (`--only <repo-name>`): Clears only the targeted repo's subdirectory, re-maps it, then regenerates all unified files.
+- **Auto mode** (`--auto`): Checks git history since last map. Skips if no changes, narrows to single repo if only one changed.
+- **Force mode** (`--force`): Bypasses staleness gate, always remaps.
 
 Each agent has fresh context, explores a specific focus area for a specific repo, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
 
@@ -49,6 +51,15 @@ Load planning-tier context files:
 TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
 ```
 
+**Parse workflow-level flags from command arguments:**
+
+These flags are parsed directly from the command arguments (NOT forwarded to the init CLI tool -- they are workflow-level flags):
+
+- `--auto`: Set `auto_mode=true`. Present when invoked by the job orchestrator.
+- `--force`: Set `force_remap=true`. Bypasses staleness gate even in auto mode.
+
+Both default to false if not present in arguments.
+
 **Mode determination:**
 - `mode === "refresh"`: Default. Clear everything, remap all repos.
 - `mode === "update"`: `--only` was used. Clear and remap only the targeted repo, then regenerate unified files.
@@ -83,6 +94,103 @@ No repos registered. Run /dgs:add-repo to register your first repo.
 
 End workflow.
 
+Continue to staleness_check.
+</step>
+
+<step name="staleness_check">
+Determine whether remapping is necessary based on git history since the last map.
+
+**Gate bypass conditions (skip this step entirely, proceed to check_existing):**
+- `force_remap` is true (--force flag was set)
+- `auto_mode` is false (interactive invocation -- always remap)
+
+**Find the last map timestamp:**
+
+Look for the most recent date from existing codebase docs:
+- Per-repo docs: grep for `**Analysis Date:** YYYY-MM-DD` on line 3 of files in `${codebase_dir}/<repo>/`
+- Unified docs: grep for `<!-- Synthesized: YYYY-MM-DD` on line 1 of files in `${codebase_dir}/`
+- If no codebase docs exist at all: proceed normally (first run)
+
+Take the most recent date found across all docs as `last_map_date`.
+
+```bash
+# Find most recent Analysis Date or Synthesized date from codebase docs
+LAST_DATE=""
+
+# Check per-repo docs
+for repo_dir in ${codebase_dir}/*/; do
+  if [ -d "$repo_dir" ]; then
+    for doc in "$repo_dir"*.md; do
+      DATE=$(grep -oP '(?<=\*\*Analysis Date:\*\* )\d{4}-\d{2}-\d{2}' "$doc" 2>/dev/null | head -1)
+      [ -n "$DATE" ] && [ "$DATE" \> "$LAST_DATE" ] && LAST_DATE="$DATE"
+    done
+  fi
+done
+
+# Check unified docs (top-level codebase dir)
+for doc in ${codebase_dir}/*.md; do
+  # Try Synthesized header format
+  DATE=$(grep -oP '(?<=Synthesized: )\d{4}-\d{2}-\d{2}' "$doc" 2>/dev/null | head -1)
+  [ -n "$DATE" ] && [ "$DATE" \> "$LAST_DATE" ] && LAST_DATE="$DATE"
+  # Try Analysis Date format (single-repo projects may have this at top level)
+  DATE=$(grep -oP '(?<=\*\*Analysis Date:\*\* )\d{4}-\d{2}-\d{2}' "$doc" 2>/dev/null | head -1)
+  [ -n "$DATE" ] && [ "$DATE" \> "$LAST_DATE" ] && LAST_DATE="$DATE"
+done
+
+if [ -z "$LAST_DATE" ]; then
+  echo "No existing codebase docs found. Proceeding with full map."
+  # Continue to check_existing
+fi
+```
+
+If `LAST_DATE` is empty, proceed to check_existing (first run).
+
+**Check git history for meaningful changes since last map:**
+
+For each repo in `valid_repos`, run git log to find changed files:
+
+```bash
+CHANGED_REPOS=""
+for repo in ${valid_repos}; do
+  REPO_PATH="${repos[$repo].path}"  # Get repo path from init JSON
+
+  # Get files changed since last map date
+  CHANGED_FILES=$(cd "$REPO_PATH" && git log --oneline --since="$LAST_DATE" --name-only --pretty=format: | sort -u | grep -v '^$')
+
+  # Filter out non-meaningful files
+  MEANINGFUL=$(echo "$CHANGED_FILES" | grep -v -E '(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|\.gitignore|\.gitattributes|STATE\.md|ROADMAP\.md|REQUIREMENTS\.md|PROJECTS\.md|REPOS\.md|PROJECT\.md|config\.json|config\.local\.json)' | grep -v '^$')
+
+  if [ -n "$MEANINGFUL" ]; then
+    CHANGED_REPOS="$CHANGED_REPOS $repo"
+  fi
+done
+
+# Trim leading space
+CHANGED_REPOS=$(echo "$CHANGED_REPOS" | xargs)
+```
+
+**Decision logic:**
+
+Count repos in CHANGED_REPOS:
+
+- **No changed repos (CHANGED_REPOS is empty):** Log skip and exit workflow with SUCCESS:
+  ```
+  [AUTO-RESOLVE] Codebase docs up to date (no meaningful changes since ${LAST_DATE}). Skipping remap.
+  ```
+  End workflow (clean exit, not error).
+
+- **Exactly 1 changed repo:** Auto-narrow to that repo. Update `mode` to "update" and set `only_repo` to the changed repo name. Log:
+  ```
+  [AUTO-RESOLVE] Only ${changed_repo} changed since last map. Narrowing to --only ${changed_repo}.
+  ```
+  Continue to check_existing with updated mode/only_repo.
+
+- **2+ changed repos:** Proceed with full remap (no changes to mode/only_repo). Log:
+  ```
+  [AUTO-RESOLVE] Multiple repos changed since last map. Proceeding with full remap.
+  ```
+  Continue to check_existing.
+
 Continue to check_existing.
 </step>
 
@@ -618,4 +726,5 @@ End workflow.
 - End-of-run summary with success/fail counts
 - Mode-aware cleanup (refresh wipes all, update wipes only target repo)
 - Cross-repo analysis generated for 2+ repos (CROSS-REPO.md)
+- Staleness gate skips remap in --auto mode when no meaningful changes since last map
 </success_criteria>

package/deliver-great-systems/workflows/new-project.md

@@ -419,7 +419,6 @@ Do not compress. Capture everything gathered.
 **Commit PROJECT.md:**
 
 ```bash
-mkdir -p .planning
 node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --push --files ${project_path}
 ```