@anhth2/spec-driven-dev-plugin 0.8.0 → 0.9.1

package/core/commands/smoke-test.md

@@ -180,6 +180,37 @@ If `services` section is present:
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+
+**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
+- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+
+**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
 
 ---
 
@@ -273,6 +304,25 @@ These two variables (`active_module`, `platform_type`) are the canonical source
 
 ---
 
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -288,7 +338,9 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
 Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -548,6 +600,11 @@ Suggest the logical next command based on workflow phase:
 | /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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:
 ```

package/core/commands/sync.md

@@ -0,0 +1,405 @@
+# /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 Feedback *(new bug reports / scenario proposals)*
+
+Tester `/report-bug` and `/propose-scenario` 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/
+```
+
+For each entry, read its title/summary and report:
+```
+📥 New tester feedback (pulled this sync):
+   Bug reports:
+     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code]
+   Scenario proposals:
+     FT-001-trailing-spaces.md  → maps to AC2  (pending review)
+```
+
+If none changed → print `📥 Tester 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 into BDD · or update 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 if `.trace/` appears in the umbrella root's `.gitignore` (or `.git/info/exclude`).
+
+If missing:
+```
+⚠️ .trace/ is not in umbrella .gitignore
+   Add it to prevent accidentally committing generated trace artifacts:
+   echo ".trace/" >> .gitignore
+```
+
+---
+
+## Step 5 — Refresh Living Docs *(umbrella mode only)*
+
+*Skip if `services` is empty.*
+
+For each service in `services[]`:
+1. Check if `{service.path}/.trace/` directory exists and contains `.tsv` files
+2. If yes → copy TSVs to `{umbrella_root}/.trace/{service-name}/` (create dir if needed)
+
+After copying all services, write merged `{umbrella_root}/.trace/trace-report.json`:
+- Aggregate data from each service's `.trace/` TSVs
+- Include `"service"` field per scenario row
+- Recalculate summary totals
+
+Print sync result:
+```
+Living Docs → .trace/ synced
+  {service-name}: {N} TSVs
+  trace-report.json: {total} scenarios across {S} services
+```
+
+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)`.
+
+## 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 |
+| /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 → `/generate-tests {UC-ID}` |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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}
+Next   : {suggested command with example arguments}
+```
+
+
+```
+/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 /run-tests 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)
+```