thachvd-kit 1.0.37 → 1.0.39

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 thachvd
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 thachvd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -27,6 +27,280 @@ thachvd-kit doctor
 
 After the first skill install, run `/setup-matt-pocock-skills` once inside your AI client to configure the issue tracker, triage labels, and generated docs location — thachvd-kit does not simulate that skill.
 
+## Brownfield System Specs
+
+This workflow is **opt-in**. Normal `thachvd-kit init/upgrade -> setup -> development` behavior is unchanged unless you run `thachvd-kit spec init`.
+
+The same happy path works for **one repository or many**:
+
+```bash
+cd your-repo-or-workspace
+
+thachvd-kit spec init --language vi   # optional; omit for English
+thachvd-kit spec index
+thachvd-kit spec discover
+
+# In your AI client:
+# /system-discovery
+
+# Human-review:
+# system-specs/architecture/capability-map.md
+
+thachvd-kit spec reverse
+
+# In your AI client:
+# /system-reverse-engineer
+
+thachvd-kit spec verify
+
+# In your AI client:
+# /system-spec-review
+
+thachvd-kit spec check
+thachvd-kit spec link
+```
+
+### Documentation language
+
+Use `--language vi` when you want human-facing specs in Vietnamese:
+
+```bash
+thachvd-kit spec init --language vi
+```
+
+If Vietnamese is your normal preference across projects, set it once at user level:
+
+```bash
+thachvd-kit config set spec-language vi
+```
+
+Then plain `thachvd-kit spec init` uses Vietnamese by default. A project-level `--language en|vi` always overrides the user default. Use `thachvd-kit config show` to inspect the current setting.
+
+The setting is stored in `.thachvd/system.json` and reused by `/system-discovery`, `/system-reverse-engineer`, and `/system-spec-review`. Only prose/headings/explanations are localized; code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors remain exactly as they appear in source. Default is `en`.
+
+### Analysis profiles
+
+Profiles adjust what discovery/reverse/review should inspect most carefully. They do **not** override code/tests and they do not hide behavior outside the selected profile.
+
+The default is `auto`, so the normal command remains:
+
+```bash
+thachvd-kit spec init
+```
+
+In `auto` mode, the agent infers a practical profile for each repository from code/config evidence. A multi-repo system can therefore contain a backend API, frontend app, worker and infra repo without forcing one profile across all of them.
+
+You can explicitly bias the checklist when a project is known:
+
+```bash
+thachvd-kit spec init --profile backend
+thachvd-kit spec init --profile frontend
+thachvd-kit spec init --profile fullstack
+thachvd-kit spec init --profile mobile
+thachvd-kit spec init --profile infra
+```
+
+Current emphasis:
+
+- `backend`: routes/RPC, auth/policies, services/domain, DB/migrations/transactions, queues/jobs/events/schedulers, retries/idempotency/concurrency, external clients and rollback/failure behavior.
+- `frontend`: routes/navigation, components/pages, state/data clients, forms/validation, auth/session, accessibility, analytics, loading/error states, browser storage and runtime/build config.
+- `fullstack`: both sides plus client/server contracts, shared schemas/types, auth propagation, SSR/BFF/server actions and end-to-end failures.
+- `mobile`: app lifecycle/background work, offline/sync, local storage, permissions, push/deep links, auth refresh, platform/device integrations and release config.
+- `infra`: IaC, environments, CI/CD, secrets/IAM/networking, state backends, observability, scaling, deployment order, rollback/recovery and destructive-change safeguards.
+
+Set a user default if you frequently work on the same class of project:
+
+```bash
+thachvd-kit config set spec-profile backend
+```
+
+Precedence is: explicit `--profile` → user config → `auto`.
+
+### Automatic repository detection
+
+`spec init` does not require `--repo` in the normal case:
+
+- if the current directory is a Git repository, it is treated as a single-repo system;
+- otherwise, direct child Git repositories are detected as a multi-repo system;
+- `--repo` remains available only as an override for unusual directory layouts.
+
+For a single repo, `system-specs/` lives in that repo. For multiple repos, run from the common workspace directory; that workspace owns `.thachvd/system.json` and `system-specs/`.
+
+For team use, make sure the configured `spec_root` is version-controlled. In a single repo this happens naturally. In a multi-repo workspace whose parent directory is not itself a Git worktree, use a dedicated docs/spec Git repository or set `--spec-root` to a location that is committed. `thachvd-kit spec doctor` warns when the spec root is not in a committed Git worktree; the kit does not silently initialize or choose a remote repository for you.
+
+`spec init` also installs the bundled `/system-discovery`, `/system-reverse-engineer`, and `/system-spec-review` skills into the workspace so the flow can run from the common parent directory.
+
+### What the AI phases do
+
+`/system-discovery` builds the coarse AS-IS map first:
+
+- system overview
+- repository responsibilities
+- capability map
+- cross-repository integrations
+- domain glossary
+
+A human reviews the capability boundaries before deep documentation begins.
+
+Then `thachvd-kit spec reverse` writes the handoff for `/system-reverse-engineer`. With **no capability argument**, one invocation processes the entire approved capability map and creates/updates:
+
+- `system-specs/capabilities/<capability>/prd.md`
+- `system-specs/capabilities/<capability>/design.md`
+- real cross-repository flow specs under `system-specs/flows/`
+- real cross-boundary contracts under `system-specs/contracts/`
+
+Internally the agent works capability-by-capability, persists progress to `system-specs/_meta/reverse-progress.json`, and resumes incomplete capabilities on later invocations. The user does **not** need to manually run one command per module.
+
+A capability argument is only a targeted refresh:
+
+```bash
+thachvd-kit spec reverse booking
+```
+
+Use that later when only Booking changed or needs to be re-documented.
+
+### Independent verification and drift detection
+
+After reverse engineering finishes:
+
+```bash
+thachvd-kit spec verify
+# In your AI client: /system-spec-review
+thachvd-kit spec check
+```
+
+`/system-spec-review` independently reconstructs implementation coverage and tries to find missing behavior, unsupported claims, weak/broken source anchors, PRD/design contradictions, and cross-repository contract gaps. It writes:
+
+- `system-specs/_meta/review.md`
+- `system-specs/_meta/verification.json`
+
+The verification JSON stores a full-system repository snapshot plus **capability-specific `verified_commits` and repository-relative `source_paths`**. `spec check` compares each capability against its own baseline, including committed, staged, unstaged, and untracked changes, so re-verifying one capability cannot accidentally make unrelated specs look current.
+
+Use `thachvd-kit spec check --strict` in CI when stale/unknown specs should fail the check.
+
+For an incremental refresh:
+
+```bash
+thachvd-kit spec reverse booking
+# /system-reverse-engineer
+thachvd-kit spec verify booking
+# /system-spec-review
+thachvd-kit spec check
+```
+
+Only Booking's verification baseline advances; unrelated capabilities keep their previous verified commits.
+
+The reverse author is not allowed to call its own output independently verified; only the review phase may mark a capability `verified`.
+
+### Spec health check
+
+`thachvd-kit spec doctor` is read-only and summarizes the documentation system in one place:
+
+- configured repos and Git HEAD availability
+- Codebase Memory availability
+- system-spec skills installed on agent surfaces
+- capability map presence
+- reverse checkpoint progress
+- independent verification/review metadata
+- current drift state
+- whether the spec root is version-controlled
+- AGENTS.md links
+
+```bash
+thachvd-kit spec doctor
+thachvd-kit spec doctor --strict
+```
+
+`--strict` exits non-zero when any WARN/ERROR remains, which is useful for CI or release gates.
+
+### HTML system explorer
+
+Markdown + JSON remain the source of truth. The HTML explorer is a deterministic read-only view generated from those files; `spec build` does not call an AI model.
+
+```bash
+thachvd-kit spec build
+```
+
+Default output:
+
+```text
+system-specs/_site/
+├── index.html
+├── architecture.html
+├── capabilities.html
+├── flows.html
+├── contracts.html
+├── health.html
+├── capability/
+│   └── <capability>.html
+├── assets/
+└── data/system.json
+```
+
+The explorer includes:
+
+- repository and capability counts
+- repo → capability matrix
+- capability PRD/design pages
+- source-path/evidence mapping
+- architecture, flow and contract Markdown rendered as HTML
+- verification/drift health
+- independent review output
+- capability filtering
+- Mermaid code blocks remain readable as source by default; remote JavaScript is never loaded implicitly
+
+Serve it locally:
+
+```bash
+thachvd-kit spec serve
+# http://127.0.0.1:4173
+```
+
+Custom output/host/port:
+
+```bash
+thachvd-kit spec build --output docs/system
+thachvd-kit spec serve --output docs/system --host 0.0.0.0 --port 8080
+```
+
+`spec serve` rebuilds by default; use `--no-build` to serve an existing output. Generated `<spec_root>/_site` files are ignored by `spec doctor` cleanliness checks, so building the explorer does not make reviewed Markdown specs look dirty.
+
+For sensitive/internal system specs, the explorer has **no remote JavaScript by default**. If you explicitly want browser-rendered Mermaid diagrams and accept loading Mermaid from jsDelivr:
+
+```bash
+thachvd-kit spec build --remote-mermaid
+thachvd-kit spec serve --remote-mermaid
+```
+
+Binding `spec serve` to a non-loopback host such as `0.0.0.0` prints a warning because the documentation may become reachable from other machines.
+
+### Optional Shinpr recipe integration
+
+`recipe-reverse-engineer` is no longer part of the required flow. If you use Claude Code and want its extra generate -> verify -> review -> revise loop for individual implementation scopes, install it once:
+
+```bash
+thachvd-kit spec recipe-setup
+```
+
+The bundled `/system-reverse-engineer` skill may use that helper when available, but it still works without it.
+
+### Flow summary
+
+1. `spec init` auto-detects one or many repos and creates the workspace/spec structure.
+2. `spec index` indexes all configured repos with codebase-memory-mcp.
+3. `spec discover` creates the handoff for `/system-discovery`.
+4. Human review confirms the system/capability boundaries.
+5. `spec reverse` creates/resumes the whole-system `/system-reverse-engineer` checkpoint.
+6. The author agent writes AS-IS PRD/design/flow/contract docs using fixed templates.
+7. `spec verify` creates the handoff for independent `/system-spec-review`.
+8. The reviewer writes machine-readable verification/provenance metadata.
+9. `spec check` detects code/spec drift deterministically from Git.
+10. `spec doctor` provides a read-only health summary for the spec system.
+11. `spec build` / `spec serve` provide a deterministic HTML overview for humans without changing the Markdown/JSON source of truth.
+12. `spec link` adds an idempotent managed block to each repo's `AGENTS.md` so future agents discover and check the reviewed system specs. By default it refuses to link when any capability is not independently `verified`; `--allow-unverified` is an explicit escape hatch.
+
+Observed behavior from code/tests and undocumented business rationale must remain distinct. Existing human-edited spec docs are not overwritten by `spec init --yes`.
+
 ## Generated Files
 
 - `AGENTS.md`: shared project instructions.
@@ -141,12 +415,27 @@ Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installe
 thachvd-kit init [--yes]
 thachvd-kit upgrade [--dry-run]
 thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
+thachvd-kit config show
+thachvd-kit config set spec-language en|vi
+thachvd-kit config unset spec-language
+thachvd-kit config set spec-profile auto|backend|frontend|fullstack|mobile|infra
+thachvd-kit config unset spec-profile
 thachvd-kit setup [--no-setup-mcp] [--no-setup-hook] [--no-install-rtk] [--no-index] [--no-install-skills]
 thachvd-kit doctor
 thachvd-kit prompt
 thachvd-kit skills install [--dry-run]
 thachvd-kit skills check
 thachvd-kit skills update [--dry-run]
+thachvd-kit spec init [--name NAME] [--language en|vi] [--profile auto|backend|frontend|fullstack|mobile|infra] [--repo PATH ...] [--spec-root PATH] [--yes]
+thachvd-kit spec index [--repo NAME ...] [--dry-run]
+thachvd-kit spec discover
+thachvd-kit spec reverse [CAPABILITY] [--reset]
+thachvd-kit spec verify [CAPABILITY]
+thachvd-kit spec check [--strict]
+thachvd-kit spec doctor [--strict]
+thachvd-kit spec recipe-setup [--fullstack] [--dry-run]   # optional Claude Code helper
+thachvd-kit spec link [--dry-run] [--allow-unverified]
+thachvd-kit spec status
 thachvd-kit --help
 ```
 
@@ -162,14 +451,17 @@ npm test
 npm run release:verify
 ```
 
-Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
-
-## Native Workflow Skills
-
-The workflow layer combines Matt Pocock's planning and implementation skills with thachvd-kit's bundled native skills. `thachvd-kit setup` and `thachvd-kit skills install` install the native set to both `.agents/skills/` and `.claude/skills/`.
-
-- `/using-git-worktrees` is opt-in workspace isolation; an explicit choice to work on the current branch always wins.
-- `/subagent-driven-development` is an alternative executor to `/implement` for plans with multiple relatively independent tasks. It uses bundled cross-platform Node entrypoints on Windows and falls back to `/implement` when subagent dispatch is unavailable.
-- `/finishing-a-development-branch` verifies and hands off a branch, cleaning only manually managed project-local worktrees safely.
-
-`thachvd-kit skills update` refreshes native skills from bundled repository copies and never fetches Superpowers at runtime. See `THIRD_PARTY_NOTICES.md` for recorded upstream provenance.
+Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
+
+## Native Workflow Skills
+
+The workflow layer combines Matt Pocock's planning and implementation skills with thachvd-kit's bundled native skills. `thachvd-kit setup` and `thachvd-kit skills install` install the native set to both `.agents/skills/` and `.claude/skills/`.
+
+- `/using-git-worktrees` is opt-in workspace isolation; an explicit choice to work on the current branch always wins.
+- `/subagent-driven-development` is an alternative executor to `/implement` for plans with multiple relatively independent tasks. It uses bundled cross-platform Node entrypoints on Windows and falls back to `/implement` when subagent dispatch is unavailable.
+- `/finishing-a-development-branch` verifies and hands off a branch, cleaning only manually managed project-local worktrees safely.
+- `/system-discovery` builds the reviewed AS-IS repo/capability/integration map for a brownfield system with one or many repositories, using Codebase Memory MCP as the primary structural source.
+- `/system-reverse-engineer` turns the approved map into PRD/design/flow/contract specs for the whole system, using a durable checkpoint so large systems can resume safely; a named capability is only a targeted refresh.
+- `/system-spec-review` independently verifies coverage/evidence and writes commit/source-path provenance used by `spec check` for drift detection.
+
+`thachvd-kit skills update` refreshes native skills from bundled repository copies and never fetches Superpowers at runtime. See `THIRD_PARTY_NOTICES.md` for recorded upstream provenance.

package/THIRD_PARTY_NOTICES.md

@@ -1,49 +1,49 @@
-# Third-Party Notices
-
-## Superpowers
-
-Repository: https://github.com/obra/superpowers
-Upstream commit: `5bf4e78011075bcfc0dc295f0724994cd123ee71`
-
-Portions of the worktree and subagent-driven development workflows are derived from:
-
-- `skills/using-git-worktrees/SKILL.md`
-- `skills/subagent-driven-development/`
-- `skills/requesting-code-review/code-reviewer.md`
-- `skills/finishing-a-development-branch/SKILL.md`
-
-The vendored source is retained for comparison with the recorded upstream commit. Adapted Windows/runtime entrypoints are documented in the native skill directory and do not replace the upstream source scripts.
-
-Copyright (c) 2025 Jesse Vincent
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-### Vendoring maintenance
-
-To refresh these files deliberately:
-
-1. Fetch the latest `obra/superpowers` repository.
-2. Inspect changes to the recorded upstream files and compare them with the recorded SHA.
-3. Port relevant upstream changes and reapply only the minimal thachvd-kit adaptations.
-4. Update `skills/upstream.json` and this notice with the new SHA.
-5. Run the native-skill regression tests and the full release verification.
-
-`thachvd-kit skills update` never fetches Superpowers. Runtime updates use the repository-owned vendored copies.
+# Third-Party Notices
+
+## Superpowers
+
+Repository: https://github.com/obra/superpowers
+Upstream commit: `5bf4e78011075bcfc0dc295f0724994cd123ee71`
+
+Portions of the worktree and subagent-driven development workflows are derived from:
+
+- `skills/using-git-worktrees/SKILL.md`
+- `skills/subagent-driven-development/`
+- `skills/requesting-code-review/code-reviewer.md`
+- `skills/finishing-a-development-branch/SKILL.md`
+
+The vendored source is retained for comparison with the recorded upstream commit. Adapted Windows/runtime entrypoints are documented in the native skill directory and do not replace the upstream source scripts.
+
+Copyright (c) 2025 Jesse Vincent
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### Vendoring maintenance
+
+To refresh these files deliberately:
+
+1. Fetch the latest `obra/superpowers` repository.
+2. Inspect changes to the recorded upstream files and compare them with the recorded SHA.
+3. Port relevant upstream changes and reapply only the minimal thachvd-kit adaptations.
+4. Update `skills/upstream.json` and this notice with the new SHA.
+5. Run the native-skill regression tests and the full release verification.
+
+`thachvd-kit skills update` never fetches Superpowers. Runtime updates use the repository-owned vendored copies.