thachvd-kit 1.0.37 → 1.0.38

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.37",
+    "version": "1.0.38",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/entry.js"
@@ -17,8 +17,8 @@
         "node": ">=16.7"
     },
     "scripts": {
-        "test": "node test/cli.test.js && node test/policy.test.js && node test/matt-skills.test.js && node test/native-skills.test.js && node test/upgrade.test.js && node test/global.test.js",
-        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && node --check bin/matt-skills.js && node --check bin/native-skills.js && node --check bin/upgrade.js && node --check bin/global.js && node --check skills/subagent-driven-development/scripts/sdd-workspace-lib.js && node --check skills/subagent-driven-development/scripts/sdd-workspace.js && node --check skills/subagent-driven-development/scripts/task-brief.js && node --check skills/subagent-driven-development/scripts/review-package.js && npm pack --dry-run",
+        "test": "node test/config.test.js && node test/cli.test.js && node test/spec.test.js && node test/spec-state.test.js && node test/spec-doctor.test.js && node test/spec-recipe.test.js && node test/spec-link.test.js && node test/policy.test.js && node test/matt-skills.test.js && node test/native-skills.test.js && node test/upgrade.test.js && node test/global.test.js",
+        "release:verify": "npm test && node --check bin/cli.js && node --check bin/config.js && node --check bin/entry.js && node --check bin/spec.js && node --check bin/spec-state.js && node --check bin/spec-doctor.js && node --check bin/spec-recipe.js && node --check bin/spec-link.js && node --check bin/policy.js && node --check bin/matt-skills.js && node --check bin/native-skills.js && node --check bin/upgrade.js && node --check bin/global.js && node --check skills/subagent-driven-development/scripts/sdd-workspace-lib.js && node --check skills/subagent-driven-development/scripts/sdd-workspace.js && node --check skills/subagent-driven-development/scripts/task-brief.js && node --check skills/subagent-driven-development/scripts/review-package.js && npm pack --dry-run",
         "preversion": "npm run release:verify",
         "release:patch": "npm version patch",
         "release:dry-run": "npm pack --dry-run",

package/skills/system-discovery/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: system-discovery
+description: Build or refresh the AS-IS system map for a brownfield multi-repository workspace using Codebase Memory MCP as the primary structural source.
+---
+
+# System Discovery
+
+Use this skill only for documentation/discovery. Do not modify product code.
+
+## Preconditions
+
+- `.thachvd/system.json` exists.
+- Repositories in that manifest have been indexed with Codebase Memory MCP.
+- If the index is stale or missing, stop and tell the user to run `thachvd-kit spec index`.
+
+## Goal
+
+Create a reviewed AS-IS map of what the current system does before detailed reverse-engineered specs are generated.
+
+## Analysis profile
+
+Read `profile` from `.thachvd/system.json`.
+
+- `auto`: infer a practical profile for each repository from code/config evidence. A multi-repo system may mix backend, frontend, mobile, and infra repos. Record inferred profiles with evidence.
+- `backend`: emphasize routes/RPC, middleware, auth/policies, services/domain logic, persistence/migrations/transactions, cache, queues/events/jobs/schedulers, external clients, feature flags, retry/idempotency/concurrency and rollback/failure paths.
+- `frontend`: emphasize routes/navigation, page/component composition, state management, API/data clients, forms/validation, auth/session, feature flags, analytics, accessibility, loading/error/empty states, browser storage and build/runtime config.
+- `fullstack`: apply both backend and frontend emphasis and trace client/server boundaries, shared schemas/types, auth/session propagation, BFF/SSR/server actions, and end-to-end failures.
+- `mobile`: emphasize navigation, lifecycle/background work, local storage/cache, offline/sync, permissions, push, deep links, auth refresh, platform-specific code, device integrations and release config.
+- `infra`: emphasize IaC modules/stacks, environments/workspaces, CI/CD, secrets, IAM, networking, state backends, observability, capacity/autoscaling, deployment ordering, rollback/recovery and destructive-change safeguards.
+
+Profile guidance is a checklist, not a source of truth. Never omit real behavior merely because it falls outside the selected profile.
+
+## Documentation language
+
+Read `language` from `.thachvd/system.json`.
+
+- `vi`: write prose, headings, explanations, and summaries in natural Vietnamese.
+- `en`: write prose, headings, explanations, and summaries in English.
+- Always preserve code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors exactly as they appear in source.
+- When writing Vietnamese, retain the original English technical term in parentheses if translating it would reduce precision.
+
+The implementation and tests are the source of truth. Never invent business intent.
+
+## Read first
+
+1. `.thachvd/system.json`
+2. Existing files under the configured `spec_root`
+3. Relevant `AGENTS.md` / `.agent/docs/*` files when present
+
+## Discovery method
+
+Use Codebase Memory MCP first for structural questions: repository inventory, symbols, entry points, callers/callees, data flow, cross-service links, routes, jobs, events, schedulers, queues, clients, and shared persistence. Use direct file reads only to verify or fill gaps.
+
+Inspect all configured repositories. Pay special attention to framework side paths that are often missed by direct call graphs: middleware, observers/hooks, event listeners, background jobs, schedulers, policies/guards, migrations, CLI commands, configuration, and tests.
+
+Do not document dead code as active behavior unless evidence shows it is reachable or intentionally retained.
+
+## Outputs
+
+Write or update these files under `spec_root`:
+
+- `architecture/system-overview.md`
+- `architecture/repo-map.md`
+- `architecture/capability-map.md`
+- `architecture/integrations.md`
+- `glossary.md`
+
+### system-overview.md
+
+Describe:
+- system purpose as observable from code
+- major actors/interfaces
+- major runtime/deployment components
+- major data stores
+- major external systems
+- top-level business capabilities
+- uncertainty / missing evidence
+
+### repo-map.md
+
+For every repository:
+- responsibility
+- primary entry points
+- owned data or services
+- inbound dependencies
+- outbound dependencies
+- events/queues/jobs
+- important source anchors
+
+### capability-map.md
+
+Group by business capability, not repository boundary.
+
+For every capability:
+- short observable purpose
+- participating repositories
+- primary entry points
+- important data/entities
+- integrations/events
+- candidate scope for later reverse engineering
+
+Add a matrix showing capability × repository participation.
+
+### integrations.md
+
+Document cross-repository and external contracts:
+- HTTP/RPC
+- events/messages/queues
+- scheduled/batch interactions
+- shared database/storage access
+- third-party systems
+
+Include direction, producer/caller, consumer/callee, contract location, and evidence.
+
+### glossary.md
+
+Capture domain terms found in code/tests/docs. Mark ambiguous terms instead of guessing.
+
+## Evidence rules
+
+For every important claim, include the strongest available source anchor: repository + file + symbol/function/class; add line ranges when available.
+
+Classify uncertain statements as one of:
+- Confirmed by implementation
+- Confirmed by tests
+- Inferred
+- Unknown / owner confirmation required
+
+Never turn an inference into a requirement or business rationale.
+
+## Human review gate
+
+End by summarizing:
+- proposed capability boundaries
+- ambiguous ownership
+- suspicious cross-repo coupling
+- missing/uncertain business terminology
+- areas that should be split/merged before detailed specs
+
+Do not proceed to detailed PRD/Design reverse engineering until the user/team approves the capability map.

package/skills/system-reverse-engineer/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: system-reverse-engineer
+description: Reverse-engineer an approved brownfield system map into durable AS-IS PRD, design, flow, and contract specifications across one or many repositories.
+---
+
+# System Reverse Engineer
+
+Use this skill after `/system-discovery` has produced a human-reviewed capability map.
+
+This is a documentation workflow. Do not modify product code.
+
+## Goal
+
+Turn the current implementation of the whole system into a durable AS-IS specification set that helps members understand the system and gives future coding agents reliable context.
+
+One invocation should cover the whole approved system. Work capability-by-capability internally so each area can be verified and checkpointed. A named capability in the handoff is only a targeted refresh.
+
+## Analysis profile
+
+Read `profile` from `.thachvd/system.json` and apply the same profile-specific emphasis defined by `/system-discovery`. In `auto` mode, use the repo profiles inferred during discovery. Re-check the evidence if the implementation has changed.
+
+Profile guidance must never suppress behavior outside the selected profile. Source code/tests remain authoritative.
+
+## Documentation language
+
+Read `language` from `.thachvd/system.json`.
+
+- `vi`: write prose, headings, explanations, summaries, PRDs, design docs, flows, and contract explanations in natural Vietnamese.
+- `en`: write those documents in English.
+- Always preserve code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors exactly as they appear in source.
+- When writing Vietnamese, retain the original English technical term in parentheses if translating it would reduce precision.
+
+## Preconditions
+
+Read:
+
+1. `.thachvd/system.json`
+2. the configured `spec_root/architecture/system-overview.md`
+3. `spec_root/architecture/repo-map.md`
+4. `spec_root/architecture/capability-map.md`
+5. `spec_root/architecture/integrations.md`
+6. `spec_root/glossary.md`
+7. `spec_root/_meta/reverse-progress.json`
+
+The capability map must have been reviewed by a human. If it is obviously still draft or ambiguous, stop rather than manufacturing detailed specs.
+
+## Durable checkpoint and resume
+
+`thachvd-kit spec reverse` creates a durable checkpoint. Full-system runs use `spec_root/_meta/reverse-progress.json`; targeted refreshes use `spec_root/_meta/reverse-progress-<capability>.json`. Use the exact checkpoint path declared by the handoff prompt.
+
+Expected shape:
+
+```json
+{
+  "schema_version": 1,
+  "system": "example",
+  "mode": "full",
+  "target": null,
+  "started_at": "<ISO-8601>",
+  "updated_at": "<ISO-8601>",
+  "status": "in_progress",
+  "capabilities": {
+    "booking": {
+      "title": "Booking",
+      "status": "pending",
+      "updated_at": "<ISO-8601>",
+      "source_paths": {}
+    }
+  }
+}
+```
+
+Rules:
+
+1. If `capabilities` is empty, derive the approved capability list from `capability-map.md` and populate it before deep work.
+2. In targeted mode, include/work only the requested capability.
+3. Before working on a capability, set it to `in_progress` and persist the file.
+4. After both PRD/design exist and the capability-level quality checks below pass, set it to `completed`, save its relevant `source_paths` by repo, and persist.
+5. If blocked, set `blocked` with a concise reason and continue with other capabilities when possible.
+6. On a later invocation, resume `pending`, `in_progress`, or retryable `blocked` capabilities. Do not redo `completed` capabilities unless the handoff is a targeted refresh or the user explicitly reset progress.
+7. Mark top-level `status` `completed` only when every intended capability is completed or explicitly blocked.
+8. Update `updated_at` after every state change.
+9. A targeted refresh must never overwrite the full-system checkpoint.
+
+Do not keep progress only in chat memory.
+
+## Sources of truth
+
+Use, in order of evidentiary strength:
+
+- production implementation
+- tests
+- configuration
+- schemas/migrations
+- existing reviewed system docs
+
+Use Codebase Memory MCP as the primary source for structural discovery, cross-repository tracing, callers/callees, routes, jobs, events, queues, schedulers, and data flow. Read source files directly to verify important behavior and fill gaps.
+
+Do not infer undocumented business rationale from implementation.
+
+## Processing model
+
+For each approved capability:
+
+1. Identify every participating repository and coherent implementation scope.
+2. Trace entry points through services, persistence, async work, integrations, and outputs.
+3. Inspect tests that lock down observable behavior.
+4. Explicitly inspect framework side paths that call graphs may miss: middleware, policies/guards, observers/hooks, event listeners, jobs, schedulers, migrations, CLI commands, config and feature flags.
+5. Extract current requirements, invariants, error/failure behavior, state transitions, retries/idempotency, and contracts.
+6. Verify important claims against code/tests.
+7. Write the capability PRD and design doc using the fixed templates below.
+8. Record uncertainty explicitly.
+9. Save stable repository-relative source paths into the progress entry for later drift checking.
+10. Continue to the next incomplete capability.
+
+If Shinpr's `/recipe-reverse-engineer` workflow is installed, it may be used as a high-assurance helper for coherent implementation scopes. It is optional.
+
+## Fixed PRD template
+
+Every `spec_root/capabilities/<capability>/prd.md` must contain these sections in this order:
+
+1. **Purpose**
+2. **Actors**
+3. **Current Behaviors / Use Cases**
+4. **Requirements**
+5. **Business Rules and Invariants**
+6. **Error and Edge Cases**
+7. **Current Limitations**
+8. **Unknown Business Rationale / Owner Confirmation**
+9. **Evidence Summary**
+
+Requirements describe what the current system demonstrably does, not what it should ideally do.
+
+## Fixed design template
+
+Every `spec_root/capabilities/<capability>/design.md` must contain these sections in this order:
+
+1. **Participating Repositories**
+2. **Entry Points**
+3. **Components / Modules**
+4. **End-to-End Execution Flow**
+5. **Data Model and Ownership**
+6. **Persistence**
+7. **State Transitions**
+8. **Events / Queues / Jobs / Schedulers**
+9. **External Integrations**
+10. **Configuration / Feature Flags**
+11. **Failure / Retry / Rollback / Idempotency**
+12. **Tests**
+13. **Source Map**
+14. **Known Ambiguities**
+
+Do not omit a section silently. Use "None observed" or "Unknown / requires confirmation" when evidence does not establish content.
+
+## System-level outputs
+
+Update only when real evidence warrants them:
+
+- `spec_root/flows/*.md` for important end-to-end or cross-repository flows
+- `spec_root/contracts/*.md` for HTTP/RPC, events/messages, queues, shared storage, or other cross-boundary contracts
+
+For cross-repository contracts, verify both producer/caller and consumer/callee when both codebases are available.
+
+Do not create files merely to fill directories.
+
+## Evidence and uncertainty
+
+Attach repository + file + symbol/function/class anchors to important behavior. Add line ranges when reliably available.
+
+Distinguish:
+
+- Confirmed by implementation
+- Confirmed by tests
+- Inferred
+- Unknown / owner confirmation required
+
+Never promote an inference to a requirement without evidence.
+
+## Capability quality gate
+
+Before marking one capability `completed` in progress:
+
+- PRD and design templates are complete
+- PRD and design agree
+- primary entry points were traced
+- relevant tests were inspected
+- async/framework side paths were considered
+- important failure/state-transition behavior is represented
+- material cross-repo contracts are represented
+- major claims have source anchors
+- relevant `source_paths` were recorded in progress
+- no undocumented business rationale was invented
+- dead/unreachable code is not presented as active without evidence
+
+This is an author-side gate only. A later independent `/system-spec-review` decides whether the result is actually verified.
+
+## Final output
+
+Return a concise coverage summary:
+
+- capabilities completed
+- capabilities blocked
+- unresolved ambiguities
+- specs needing owner review
+- cross-repository flows/contracts produced
+- current checkpoint status
+
+Do not claim the specs are independently verified. That happens only after `thachvd-kit spec verify` + `/system-spec-review`.

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.