thachvd-kit 1.0.38 → 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

@@ -213,6 +213,67 @@ 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:
@@ -235,7 +296,8 @@ The bundled `/system-reverse-engineer` skill may use that helper when available,
 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 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.
+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`.
 

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.

package/bin/spec-doctor.js

@@ -74,7 +74,8 @@ function inspectSpecStorage(workspaceRoot, manifest) {
     }
 
     const specRelative = path.relative(gitRoot, specRoot).split(path.sep).join('/') || '.';
-    const status = runGit(gitRoot, ['status', '--porcelain', '--', specRelative]);
+    const generatedSiteRelative = specRelative === '.' ? '_site' : specRelative + '/_site';
+    const status = runGit(gitRoot, ['status', '--porcelain', '--', specRelative, ':(exclude)' + generatedSiteRelative]);
     if (!status.ok) return { ok: false, message: status.error };
 
     if (untracked.length > 0 || status.stdout) {