@edupia-tutor/spec-driven-docs 0.14.0

package/core/commands/sync.md

@@ -0,0 +1,451 @@
+# /sync — Sync & Refresh Umbrella Project
+
+One command for both **first-time setup** and **daily update** of an umbrella repo with git submodules.
+Safe to run repeatedly — detects what needs to be done automatically.
+
+**Optional argument:** `/sync [spec-branch]` — branch of the spec submodule to pull (e.g. `/sync develop`). If omitted, the branch is resolved automatically (see Step 0-D).
+
+---
+
+## Step 0 — Pre-flight Checks
+
+**A. Git repo check**
+
+Verify current directory is inside a git repo. If not → stop:
+```
+❌ Not a git repository. Open Claude Code from umbrella root and retry.
+```
+
+**B. Read project config early**
+
+Read `.agent/project-context.yaml` before running any git commands. Extract:
+- `setup.spec_source` → path of the spec submodule (e.g., `"my-project-specs"`)
+- `services` → map of domain → `{path, module, ...}` for each service submodule
+
+This is needed to differentiate spec vs service submodules in Step 1.
+
+If `.agent/project-context.yaml` does not exist → warn and set `spec_source = null`, `services = {}`.
+
+**C. Submodule status scan**
+
+Run `git submodule status --recursive` and classify each entry by its first character:
+
+| Char | Meaning | Action |
+|------|---------|--------|
+| `-` | Not initialized | → **Setup mode** |
+| ` ` | Matches recorded pointer | → OK |
+| `+` | Ahead of recorded pointer (local advance uncommitted) | → warn per submodule |
+| `U` | Merge conflict | → **STOP** |
+
+If **any** entry has `U`:
+```
+❌ Merge conflict in submodule: {path}
+   Resolve manually before running /sync:
+     cd {path} && git status
+```
+
+If **any** entry has `+` (checked-out commit differs from the recorded pointer):
+```
+ℹ️ {path} is ahead of the umbrella's recorded pointer.
+   /sync classifies it in Step 1b — if you're on a branch there, it stays untouched.
+```
+Do not act on `+` here — Step 1b decides the right handling per submodule.
+
+Print detected mode: `Mode: Setup (first-time init)` or `Mode: Update (sync latest)`.
+
+---
+
+## Step 1 — Umbrella Pull
+
+Note the current umbrella branch first (this is what `git pull` updates):
+`git rev-parse --abbrev-ref HEAD` → store as `umbrella_branch` and display it.
+
+```bash
+# 1. Pull latest umbrella (includes updated submodule pointer records)
+git pull
+
+# 2. Sync .gitmodules config into local git config
+#    (needed when new submodules were added since last clone)
+git submodule sync --recursive
+
+# 3. Initialize any NOT-yet-cloned submodules ONLY (the '-' entries from Step 0-C).
+#    Do NOT run a blanket `git submodule update --recursive` — that would detach
+#    a submodule you are actively working in. Per-submodule handling is Step 1b.
+git submodule update --init {paths that were '-' in Step 0-C}
+```
+
+If `git pull` exits non-zero → print the error and stop with `❌`.
+
+---
+
+## Step 1b — Classify & Sync Each Submodule
+
+**The key idea:** `/sync` never imposes a branch on a submodule. It **inspects each submodule's current checkout** and respects it. This is how it knows which submodule you are working in vs which are passive dependencies.
+
+For each submodule (use `git submodule foreach` or iterate the paths), read its state:
+
+```bash
+# Inside each submodule:
+git symbolic-ref --short -q HEAD   # → branch name, or empty/non-zero if DETACHED
+git status --porcelain             # → non-empty means uncommitted local changes
+```
+
+Classify into one of four cases and act accordingly:
+
+| Case | Detected state | Action |
+|------|----------------|--------|
+| **Spec submodule** | `path == spec_source` | Advance to `spec_branch` (Step 1c below) |
+| **Active (on a branch)** | HEAD is a branch, not detached | **Do NOT checkout.** This is where you (or a teammate) are coding. Just `git -C {path} fetch` and report branch + ahead/behind. Leave the working tree exactly as-is. |
+| **Passive (detached, clean)** | Detached HEAD, no local changes | Safe to align to the umbrella's recorded pointer: `git submodule update {path}` |
+| **Dirty (uncommitted changes)** | `git status --porcelain` non-empty | **Never touch.** Warn: `⚠️ {path} has uncommitted changes — skipped. Commit or stash before syncing this submodule.` |
+
+> **Why this matters:** A blanket `git submodule update` checks every submodule out to a **detached HEAD** at the recorded pointer. If you have `feature/FEAT-01` checked out inside `user-service/` and are mid-work, that would silently move you off your branch. Classifying first protects your active work.
+
+---
+
+## Step 1c — Advance Spec Submodule *(only if `spec_source` is configured)*
+
+The spec submodule is the one submodule we deliberately advance to a branch HEAD (PO pushes specs continuously).
+
+**Resolve the spec branch** (now that the submodule is initialized), in priority order:
+
+1. **Command argument** — if `$ARGUMENTS` contains a branch name → use it (one-off override)
+2. **`.gitmodules` config** — `git config -f .gitmodules --get submodule.{spec_source}.branch`. If set → use it (team's committed default)
+3. **Remote default** — else the spec repo's default branch: `git -C {spec_source} rev-parse --abbrev-ref origin/HEAD` (strip the `origin/` prefix)
+
+Store as `spec_branch` + `spec_branch_source` (argument | .gitmodules | remote-default). If it fell through to remote-default with nothing pinned, add this hint to the output:
+```
+ℹ️ Spec submodule branch not pinned in .gitmodules — using remote default '{spec_branch}'.
+   To pin it for the whole team:
+     git config -f .gitmodules submodule.{spec_source}.branch {spec_branch}
+     git add .gitmodules && git commit -m "chore: pin spec submodule branch"
+```
+
+Then check it is safe: if the spec submodule has uncommitted changes → warn and skip (devs should treat specs as read-only). Otherwise use an **explicit checkout** (not bare `--remote`) so the branch is unambiguous:
+
+```bash
+cd {spec_source}
+git fetch origin
+git checkout {spec_branch}        # branch resolved in Step 0-D
+git pull origin {spec_branch}
+cd -                              # back to umbrella root
+```
+
+Print: `Spec submodule {spec_source}: pulled branch '{spec_branch}' (source: {spec_branch_source})`
+
+> **Why not `--remote` for service submodules?** Service submodules are version-locked by the umbrella's recorded pointer — this is intentional so all devs work from the same commit. `--remote` would bypass this lock and create uncommitted pointer drift. The spec submodule is the exception: PO pushes continuously, so we advance it to a branch HEAD — but we do it with an explicit `checkout {spec_branch}` rather than `--remote` so it never silently follows the wrong branch.
+
+If `git pull` or `git submodule update` exits non-zero → print the error and stop with `❌`.
+
+Collect from output:
+- Which submodules changed SHA
+- Which were already up to date
+- The spec submodule's `{old_sha}..{new_sha}` (needed by Step 1d)
+
+---
+
+## Step 1d — Surface Tester/QC Feedback *(bug reports / scenario proposals / PRD change requests)*
+
+Tester & QC `/report-bug`, `/propose-scenario` (incl. Case B PRD change requests) commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
+
+- **Dev/tester in umbrella** → feedback came in via the spec submodule advance (Step 1c)
+- **PO working directly in the spec repo** → feedback came in via the umbrella/current-repo `git pull` (Step 1)
+
+Pick the repo + range that pulled the feedback:
+- Umbrella with `spec_source` → `REPO={spec_source}`, range = spec submodule `{old_sha}..{new_sha}`
+- Otherwise (running inside the spec repo itself) → `REPO=.`, range = the `git pull` `{old_sha}..{new_sha}` from Step 1
+
+If `feedback/` does not exist in REPO → skip silently.
+
+```bash
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/ feedback/prd-change-requests/
+```
+
+For each entry, read its title/summary + `State` and report. **Bug reports: surface only `State: Open`** as needing attention; list `Fixed`/`Closed` separately (or omit) so the PO/PM sees what's still pending:
+```
+📥 New feedback (pulled this sync):
+   Bug reports (open):
+     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code · waiting: dev]
+   Bug reports (fixed, awaiting QC re-verify): BUG-20260605-02
+   Scenario proposals:
+     FT-001-trailing-spaces.md  → maps to AC2  (pending review)
+   PRD change requests:
+     FT-001-bulk-export.md  → new requirement, needs an AC  (waiting: PO)
+```
+
+If none changed → print `📥 Feedback: none new this sync`.
+
+If the reader is a PO/Dev, add a one-line nudge:
+`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal via /generate-bdd · or add an AC to the PRD.`
+
+---
+
+## Step 2 — Post-sync State Check
+
+Run `git status --short` and check for modified submodule entries (lines starting with ` M` where the path matches a submodule).
+
+If any submodule pointer changed (typically the spec submodule after `--remote`):
+```
+⚠️ Submodule pointer(s) updated — commit to lock new version into umbrella:
+   git add {spec_source} && git commit -m "chore: sync {spec_source} to latest"
+```
+
+If no changes → `✅ Umbrella state clean — no commit needed`.
+
+---
+
+## Step 3 — Bootstrap Service Configs
+
+*Skip if `services` is empty.*
+
+For each entry in `services[]`:
+
+**A. If `{service.path}/.agent/project-context.yaml` already exists:**
+- Read `conventions.test_command` and `conventions.build_command`
+- Report: `✅ {service.path} — test: {test_command} | build: {build_command}`
+
+**B. If missing — auto-create it:**
+
+1. Determine `module` from umbrella `services[].module` (authoritative). If not set, auto-detect from files in `{service.path}/`:
+
+   | File present | Detected module | test_command | build_command |
+   |---|---|---|---|
+   | `pom.xml` | `java-spring` | `mvn test` | `mvn compile` |
+   | `build.gradle` or `build.gradle.kts` | `java-spring` | `./gradlew test` | `./gradlew build` |
+   | `go.mod` | `golang` | `go test ./...` | `go build ./...` |
+   | `*.csproj` or `*.sln` | `dotnet` | `dotnet test` | `dotnet build` |
+   | `composer.json` | `php-laravel` | `php artisan test` | `composer install` |
+   | `pubspec.yaml` | `flutter` | `flutter test` | `flutter build apk` |
+   | `angular.json` | `angular` | `npx ng test --watch=false` | `npm run build` |
+   | `next.config.*` | `nextjs` | `npx vitest run` | `npm run build` |
+   | `package.json` + `nest-cli.json` | `nestjs` | `npm test` | `npm run build` |
+   | `package.json` (fallback) | `react` | `npx vitest run` | `npm run build` |
+   | `requirements.txt` or `pyproject.toml` | `context-engineering` | `pytest tests/ -v` | `pip install -r requirements.txt` |
+   | *(none matched)* | `unknown` | `{{TEST_COMMAND}}` | `{{BUILD_COMMAND}}` |
+
+2. Create `{service.path}/.agent/` directory if it does not exist.
+
+3. Write `{service.path}/.agent/project-context.yaml`:
+
+   ```yaml
+   # Auto-generated by /sync — review and update as needed
+   tech_stack:
+     language: "{detected or from module}"
+     framework: "{detected or from module}"
+     module: "{module}"
+
+   conventions:
+     test_command: "{test_command}"
+     build_command: "{build_command}"
+
+   paths:
+     trace_dir: ".trace"
+     lessons_file: ".agent/project-lessons.md"   # per-service guardrails (see /learn)
+   ```
+
+4. Report:
+   - If auto-detected: `✅ Created {service.path}/.agent/project-context.yaml (module: {module}, test: {test_command})`
+   - If unknown/placeholder: `⚠️ Created {service.path}/.agent/project-context.yaml — fill in {{TEST_COMMAND}} and {{BUILD_COMMAND}}`
+
+---
+
+## Step 4 — Check `.gitignore`
+
+Check the generated Living Docs mirrors are gitignored:
+- `.trace/` in the current repo's `.gitignore` (or `.git/info/exclude`)
+- `.living-docs/` in the **specs module's** `.gitignore` (when `setup.spec_source` is set)
+
+If either is missing:
+```
+⚠️ Living Docs mirrors not gitignored — they are generated, never commit them:
+   echo ".trace/" >> .gitignore
+   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (if spec_source set)
+```
+
+---
+
+## Step 5 — Refresh Living Docs *(umbrella mode only)*
+
+*Skip if `services` is empty.*
+
+**Resolve the Living Docs home (same rule as `/validate-traces`):**
+- `living_docs_dir` = `{spec_source}/.living-docs` if `setup.spec_source` is set, else `.living-docs` at umbrella root. *(The specs module is mounted inside every service workspace, so the panel resolves it even when a dev opens a single service submodule.)*
+- `panel_mirror` = `./.trace` at the current workspace root.
+
+1. For each service in `services[]`: if `{service.path}/.trace/` has `.tsv` files → copy them to `{living_docs_dir}/{service-name}/` (create dir if needed).
+2. Write merged `{living_docs_dir}/trace-report.json`:
+   - Aggregate each service's `.trace/` TSVs, add `"service"` field per row, recalc summary totals.
+3. **Mirror to the panel location:** copy `{living_docs_dir}/trace-report.json` (+ namespaced TSVs) → `{panel_mirror}/` so the panel in the currently-open repo is non-empty. Skip if `panel_mirror` already equals `living_docs_dir`.
+
+Print sync result:
+```
+Living Docs → {living_docs_dir}/ synced  (canonical, specs module)
+  {service-name}: {N} TSVs
+  trace-report.json: {total} scenarios across {S} services
+Panel mirror → {panel_mirror}/  (current workspace)
+```
+
+If no `.trace/` dirs found → `Living Docs: no trace data yet — run /generate-bdd then /generate-code first.`
+
+---
+
+## Step 6 — Refresh Spec Manifest *(if spec_source present)*
+
+*Skip if `setup.spec_source` is absent.*
+
+If `spec-manifest.yaml` exists OR `setup.spec_source` is configured:
+- Re-scan `{spec_source}/specs/**/prd.md` files
+- Rebuild `spec-manifest.yaml` mapping TICKET-ID → PRD/BDD/tech-doc paths
+- Print: `spec-manifest.yaml refreshed — {N} features indexed`
+
+---
+
+## Output
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
+```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+
+
+```
+/sync — {Setup | Update}
+
+Git
+  ✅ git pull             — umbrella on branch '{umbrella_branch}'
+  ✅ submodule sync       — .gitmodules config refreshed
+
+Submodules (each handled by its current state)
+  ✅ {spec_source}    [spec]            — pulled branch '{spec_branch}' ({spec_branch_source}) → {new-sha}
+  ✋ user-service     [active]          — on 'feature/FEAT-01' — left untouched, fetched (↓2 behind origin)
+  ✅ order-service    [passive]         — aligned to umbrella pointer {sha}
+  ⚠️ payment-service  [dirty]           — uncommitted changes, skipped (commit/stash first)
+
+Umbrella state
+  ⚠️ Pointer changed: git add {spec_source} && git commit -m "chore: sync specs"
+  (or: ✅ Clean — no commit needed)
+
+Tester feedback (pulled this sync)
+  📥 1 bug report:  BUG-20260608-01 FT-001 [Code]
+     1 proposal:    FT-001-trailing-spaces → AC2 (pending review)
+  (or: 📥 none new this sync)
+  → /fix-bug {BUG-ID} · promote proposal into BDD · or update PRD
+
+Service Configs
+  ✅ user-service    — test: mvn test  | build: mvn compile
+  ✅ order-service   — test: mvn test  | build: mvn compile
+  ⚠️ payment-service — .agent/project-context.yaml missing
+                       → create it so /dev-run-test works correctly
+
+.gitignore
+  ✅ .trace/ is gitignored
+  (or: ⚠️ Add .trace/ to .gitignore)
+
+Living Docs
+  ✅ .trace/ synced — {N} TSVs across {S} services
+     (run /validate-traces for full coverage report)
+
+Spec Manifest
+  ✅ spec-manifest.yaml — {N} features indexed
+
+---
+Status : ✅ Complete | ⚠️ Warnings
+Output Artifacts: updated .trace/ (umbrella mirror), spec-manifest.yaml
+Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
+```