thachvd-kit 1.0.36 → 1.0.38

package/skills/system-spec-review/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: system-spec-review
+description: Independently verify generated AS-IS system specs against implementation and tests, then write machine-readable verification metadata for drift detection.
+---
+
+# System Spec Review
+
+Review an existing generated system-spec set independently from the agent that wrote it.
+
+Do not modify product code. Do not silently rewrite the source specs during the first review pass.
+
+## Goal
+
+Try to prove the generated specs incomplete, unsupported, stale, or internally inconsistent.
+
+## Analysis profile
+
+Read `profile` from `.thachvd/system.json`. Use it to expand the independent coverage inventory with the same specialized concerns used during discovery/reverse engineering. In `auto` mode, independently check whether the inferred per-repository profiles are supported by code/config evidence.
+
+Do not treat profile compliance as proof of completeness; actively look for behavior outside the expected profile.
+
+The result is not a style review. It is an evidence and coverage review.
+
+## Read first
+
+1. `.thachvd/system.json`
+2. the configured `spec_root/architecture/*`
+3. `spec_root/capabilities/*/{prd.md,design.md}`
+4. `spec_root/flows/*`
+5. `spec_root/contracts/*`
+6. `spec_root/_meta/reverse-progress.json` when present
+
+Read `language` from the manifest and write the human-facing review report in that language. Preserve all code identifiers and source anchors exactly.
+
+## Source of truth
+
+Use:
+- production implementation
+- tests
+- config
+- schemas/migrations
+- Codebase Memory MCP for structural discovery and cross-repository tracing
+
+Do not trust generated specs simply because they contain source anchors. Follow a representative and risk-weighted sample of anchors into code and verify them.
+
+## Independent verification method
+
+If the client supports subagents, run this review in a fresh reviewer subagent that did not author the specs. Otherwise, deliberately reconstruct the implementation inventory from code/MCP before reading each capability's conclusions in detail. Do not rely on the author agent's summary as evidence.
+
+For each approved capability:
+
+1. Build an implementation inventory independently from the capability spec:
+   - entry points/routes/commands
+   - services/modules
+   - state transitions
+   - persistence
+   - jobs/schedulers
+   - events/listeners/queues
+   - middleware/policies/observers/hooks
+   - external clients/integrations
+   - tests
+2. Compare that inventory with PRD and design docs.
+3. Check important claims against implementation/tests.
+4. Look for implementation behavior not represented in the spec.
+5. Look for spec claims with no implementation/test evidence.
+6. Check PRD vs design consistency.
+7. Check cross-repository flows and contracts from both sides of each boundary.
+8. Check whether dead/unreachable code was described as active.
+9. Check ambiguous business rationale remains marked unknown rather than invented.
+
+Prioritize high-risk boundaries: authentication/authorization, money/payment/refund, schema/state changes, async processing, external side effects, retries/idempotency, concurrency, and destructive operations.
+
+## Verification statuses
+
+A capability may be:
+
+- `verified`: no material unsupported claims or coverage gaps found in the performed review.
+- `needs_review`: material gaps, unsupported claims, contradictions, or ambiguous coverage remain.
+- `blocked`: verification could not be completed because required code, tests, repositories, or runtime evidence are unavailable.
+
+Do not use `verified` to mean mathematically complete. The review report must state what was sampled and any residual risk.
+
+## Required outputs
+
+Create/update:
+
+- `spec_root/_meta/review.md`
+- `spec_root/_meta/verification.json`
+
+If the handoff names one capability, perform a targeted re-review:
+- verify only that capability against current code/tests
+- update only that capability entry in `verification.json`
+- preserve other capability entries and their per-capability verified commits
+- append/update the human review report without erasing unrelated findings
+
+### review.md
+
+Include:
+- review scope and date
+- repositories/commits reviewed
+- capability-by-capability status
+- missing behavior
+- unsupported claims
+- broken or weak source anchors
+- PRD/design contradictions
+- flow/contract gaps
+- unresolved ambiguities
+- residual review risk
+- recommended remediation
+
+Do not automatically edit the source spec to hide findings.
+
+### verification.json
+
+Write valid JSON with this shape:
+
+```json
+{
+  "schema_version": 1,
+  "verified_at": "<ISO-8601>",
+  "system": "<manifest name>",
+  "repositories": {
+    "<repo-name>": {
+      "commit": "<git HEAD SHA>"
+    }
+  },
+  "capabilities": {
+    "<capability-slug>": {
+      "title": "<human title>",
+      "status": "verified",
+      "source_paths": {
+        "<repo-name>": [
+          "path/to/module",
+          "path/to/important-file.ext"
+        ]
+      },
+      "verified_commits": {
+        "<repo-name>": "<Git SHA used to verify this capability>"
+      },
+      "evidence": {
+        "implementation_claims_checked": 0,
+        "test_claims_checked": 0,
+        "unsupported_claims": 0,
+        "potential_gaps": 0,
+        "broken_anchors": 0
+      },
+      "notes": []
+    }
+  }
+}
+```
+
+Rules:
+- top-level repository commits MUST be current `git rev-parse HEAD` values for a full-system review; they represent the latest whole-system review snapshot
+- every `verified` capability MUST record `verified_commits` for each repo present in its `source_paths`
+- for targeted re-review, update that capability's `verified_commits` to current HEAD without advancing unrelated capabilities' baselines
+- `source_paths` MUST contain paths actually relevant to the capability; prefer stable module/directory prefixes plus exceptional files
+- do not use wildcards; paths are repository-relative
+- every capability in the approved capability map must appear
+- capabilities that were not fully checked must not be marked `verified`
+- every `verified` capability must have at least one repository-relative `source_paths` entry and matching `verified_commits`
+- for a `verified` capability, `unsupported_claims`, `potential_gaps`, and `broken_anchors` must all be 0; otherwise use `needs_review`
+- all evidence counts must be non-negative integers; use 0 rather than inventing counts
+- source paths must stay inside their repository; never use absolute paths or `../`
+
+## Final gate
+
+Before marking the review complete:
+
+- every approved capability has a verification status
+- every configured repo has a top-level reviewed commit SHA after a full review
+- verified capabilities have source paths and capability-specific verified commits for every repo they materially use
+- no known material gap is hidden under `verified`
+- the JSON parses cleanly
+- the human report and JSON statuses agree
+
+Return a concise summary of verified, needs-review, blocked, and the highest-risk gaps.

package/skills/upstream.json

@@ -0,0 +1,30 @@
+{
+  "obra/superpowers": {
+    "commit": "5bf4e78011075bcfc0dc295f0724994cd123ee71",
+    "files": [
+      "skills/using-git-worktrees/SKILL.md",
+      "skills/subagent-driven-development/SKILL.md",
+      "skills/subagent-driven-development/implementer-prompt.md",
+      "skills/subagent-driven-development/task-reviewer-prompt.md",
+      "skills/subagent-driven-development/re-review-prompt.md",
+      "skills/subagent-driven-development/scripts/review-package",
+      "skills/subagent-driven-development/scripts/sdd-workspace",
+      "skills/subagent-driven-development/scripts/task-brief",
+      "skills/requesting-code-review/code-reviewer.md",
+      "skills/finishing-a-development-branch/SKILL.md"
+    ],
+    "adapted_entrypoints": [
+      "skills/subagent-driven-development/scripts/review-package.js",
+      "skills/subagent-driven-development/scripts/sdd-workspace.js",
+      "skills/subagent-driven-development/scripts/task-brief.js",
+      "skills/subagent-driven-development/scripts/sdd-workspace-lib.js"
+    ],
+    "adapted_files": [
+      "skills/using-git-worktrees/SKILL.md",
+      "skills/subagent-driven-development/SKILL.md",
+      "skills/subagent-driven-development/task-reviewer-prompt.md",
+      "skills/subagent-driven-development/re-review-prompt.md",
+      "skills/finishing-a-development-branch/SKILL.md"
+    ]
+  }
+}

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: using-git-worktrees
+description: Use when the user explicitly wants an isolated workspace, especially for parallel feature development
+---
+
+# Using Git Worktrees
+
+## Overview
+
+When isolation is intended, ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Determine the intended workspace first. Respect an explicit request to stay on the current branch/workspace. If isolation is requested, prefer native tools, then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```text
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git rev-parse --show-toplevel
+git rev-parse --show-superproject-working-tree
+git branch --show-current
+```
+
+**Submodule guard:** differing Git directory results are also possible inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```text
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree
+```
+
+**If `--git-dir` differs from `--git-common-dir` (and this is not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If the values match (or this is a submodule):** You are in a normal repo checkout.
+
+If the user explicitly says to work on the current branch/workspace, stay there. If the user invokes `/using-git-worktrees` or explicitly requests isolation, that is consent to isolate. If intent is unspecified, stay in the current workspace by default. Do not recommend or create a worktree solely because an implementation plan is large, risky, or being executed by SDD. Follow a project-level preference only when it explicitly requires isolation.
+
+Honor any existing declared preference without asking. If isolation is not explicitly requested or required by project policy, skip to Step 2 in the current workspace.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```text
+   PowerShell: Test-Path .worktrees; Test-Path worktrees
+   CMD:        if exist .worktrees echo .worktrees & if exist worktrees echo worktrees
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```text
+git check-ignore .worktrees
+```
+
+If `.worktrees` does not exist, check the directory name you will create:
+
+```text
+git check-ignore worktrees
+```
+
+**If NOT ignored:** Add the appropriate entry to `.gitignore`, show that change clearly, and proceed only after the ignore rule is in place. Do not silently commit unrelated changes.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```text
+# Determine the path using the host shell, then run the portable Git command.
+git worktree list --porcelain
+git branch --list <branch>
+git worktree add "<path>" -b "<branch>"       # new branch
+git worktree add "<path>" "<branch>"          # existing, unattached branch
+```
+
+Never reset, force-checkout, delete, or steal an existing branch attached to another worktree.
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), report that clearly. If isolation was explicitly required, stop rather than silently working on the current branch; otherwise ask whether to continue in the current workspace, then run setup and baseline tests there only with that choice.
+
+## Step 2: Project Setup
+
+Auto-detect and run appropriate setup. Read the repository's `AGENTS.md`, `.agent/docs/tooling.md`, package scripts, and lockfiles first; do not install dependencies that the project workflow does not require:
+
+```text
+package-lock.json -> npm
+pnpm-lock.yaml    -> pnpm
+yarn.lock         -> yarn
+bun.lock*         -> bun
+requirements.txt  -> pip
+uv.lock           -> uv
+Cargo.toml        -> cargo
+go.mod            -> go
+composer.json     -> composer
+```
+
+Use the project's documented bootstrap command after detecting the package manager.
+
+## Step 3: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```text
+# Run the project-appropriate command (one command, not a shell expression):
+npm test
+# or cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |
+| "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |
+| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
+| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
+| "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |