universal-dev-standards 6.7.5 → 6.9.0

package/bundled/templates/reverse-spec-template.md

@@ -0,0 +1,409 @@
+# [SPEC-XXX] [Feature Name] (Reverse Engineered)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-19
+
+> ⚠️ **This specification was reverse engineered from existing code**
+>
+> - **Analysis Date**: YYYY-MM-DD
+> - **Analyzed Path**: `path/to/code`
+> - **Analyzer**: [AI/Human Name]
+>
+> Sections marked `[Unknown]` require human confirmation before this spec is considered complete.
+
+---
+
+## Human Review Checklist
+
+Before considering this spec complete, verify:
+
+### Accuracy
+- [ ] All `[Confirmed]` items verified against actual code
+- [ ] Source citations (file:line) are correct
+- [ ] No fabricated APIs, configurations, or behaviors
+
+### Inference Validation
+- [ ] All `[Inferred]` items reviewed for accuracy
+- [ ] Incorrect inferences corrected or removed
+- [ ] Reasoning for inferences is sound
+
+### Required Human Input
+- [ ] `Motivation` section completed (why this feature exists)
+- [ ] `Risks` section completed (potential failure modes)
+- [ ] `Out of Scope` section verified (intentional exclusions)
+- [ ] `User Story` / business context added
+
+### Final Sign-off
+- [ ] Original developer reviewed (if available)
+- [ ] Product owner approved business context
+- [ ] All `[Unknown]` labels resolved or acknowledged
+
+---
+
+## Summary
+
+[Confirmed] Brief description of what the code does.
+
+- [Source: Code] `primary_file.ts:start-end`
+
+<!-- Example:
+[Confirmed] This module provides user authentication via JWT tokens, supporting login, logout, and token refresh operations.
+
+- [Source: Code] src/controllers/AuthController.ts:1-150
+- [Source: Code] src/services/AuthService.ts:1-200
+-->
+
+---
+
+## Motivation
+
+[Unknown] **Requires human input**
+
+Answer these questions:
+
+1. **Why was this feature built?**
+   <!-- What problem does it solve? What was the business driver? -->
+
+2. **Who requested this feature?**
+   <!-- Product owner, customer, internal team? -->
+
+3. **What user problem does it address?**
+   <!-- User pain points, workflow improvements -->
+
+4. **What was the original timeline/context?**
+   <!-- When was it built? Any relevant context? -->
+
+---
+
+## User Story
+
+[Unknown] **Requires human input**
+
+```
+As a [user type],
+I want to [action/capability],
+So that [benefit/value].
+```
+
+<!-- Example:
+As a registered user,
+I want to log in with my email and password,
+So that I can access my personal dashboard and data.
+-->
+
+---
+
+## Detailed Design
+
+### Architecture Overview
+
+[Confirmed/Inferred] High-level architecture extracted from code.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Component Diagram                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  [Describe the main components and their relationships]     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- [Source: Code] `src/architecture/` or inferred from imports
+
+### Component Details
+
+#### Component 1: [Name]
+
+[Confirmed] Description of component responsibility.
+
+- **Location**: `path/to/component`
+- **Dependencies**: List of dependencies
+- **Key Methods**:
+  - `methodName()` - Description
+  - `anotherMethod()` - Description
+
+- [Source: Code] `file.ts:lines`
+
+#### Component 2: [Name]
+
+[Confirmed/Inferred] Description.
+
+- [Source: Code] `file.ts:lines`
+
+### Data Models
+
+#### Model: [EntityName]
+
+[Confirmed] Data structure definition.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | Yes | Primary identifier |
+| field1 | type | Yes/No | [Confirmed] Description |
+| field2 | type | Yes/No | [Inferred] Description |
+
+- [Source: Code] `src/models/EntityName.ts:lines`
+
+### API / Interface
+
+#### Endpoint/Method 1
+
+[Confirmed] `METHOD /path/to/endpoint`
+
+**Parameters**:
+| Name | Location | Type | Required | Description |
+|------|----------|------|----------|-------------|
+| param1 | path/query/body | type | Yes/No | Description |
+
+**Request Body** (if applicable):
+```json
+{
+  "field": "value"
+}
+```
+
+**Response**:
+```json
+{
+  "result": "value"
+}
+```
+
+**Error Codes**:
+| Code | Description |
+|------|-------------|
+| 400 | [Inferred] Bad request |
+| 401 | [Confirmed] Unauthorized |
+
+- [Source: Code] `src/controllers/Controller.ts:lines`
+
+### Configuration
+
+[Confirmed] Configuration extracted from code.
+
+| Setting | Default | Description | Source |
+|---------|---------|-------------|--------|
+| SETTING_1 | value | Description | [Source: Code] config.ts:5 |
+| SETTING_2 | value | Description | [Source: Code] .env.example:10 |
+
+---
+
+## E2E Scenarios（必填）
+
+> 定義使用者或呼叫者視角的端對端場景。至少填 1 條 Happy Path。
+> 若確實不需要 E2E，填寫 `e2e_not_required_reason` 並留空 Scenarios 區塊。
+
+**e2e_not_required_reason**（若 Scenarios 為空，此欄必填）：
+<!-- 有效理由：純內部工具函式 | 已被 SPEC-NNN E2E 涵蓋，見 [SPEC-NNN] -->
+<!-- 無效理由：「之後再補」「現在沒空」 -->
+
+### Happy Path: [場景名稱]
+
+```gherkin
+Given [用戶或系統狀態前提]
+When  [觸發動作或 API 呼叫]
+Then  [可觀察的預期結果：HTTP status、資料庫狀態、回應 body]
+```
+
+### Error Path: [場景名稱]（建議：安全相關、Quota、計費功能必填）
+
+```gherkin
+Given [異常前提條件]
+When  [觸發動作]
+Then  [預期錯誤處理：status code、錯誤訊息、無副作用]
+```
+
+---
+
+## Acceptance Criteria
+
+### Extracted from Tests
+
+[Inferred] Acceptance criteria derived from test cases:
+
+#### Feature Area 1
+
+- [ ] [Inferred] Criterion from `test_should_do_something` (test_file.ts:10)
+- [ ] [Inferred] Criterion from `test_should_handle_error` (test_file.ts:25)
+
+#### Feature Area 2
+
+- [ ] [Inferred] Criterion from test analysis
+
+- [Source: Code] `src/tests/feature.test.ts`
+
+### Coverage Gaps
+
+[Unknown] The following areas lack test coverage:
+
+| Area | Risk Level | Recommendation |
+|------|------------|----------------|
+| Error handling | 🟡 Medium | Add tests before modification |
+| Edge cases | 🔴 High | Requires documentation |
+
+---
+
+## Dependencies
+
+### External Dependencies
+
+[Confirmed] Dependencies from package.json/requirements.txt:
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| package1 | ^1.0.0 | Description |
+| package2 | ^2.0.0 | Description |
+
+- [Source: Code] `package.json:lines`
+
+### Internal Dependencies
+
+[Confirmed] Internal module dependencies:
+
+| Module | Depends On | Type |
+|--------|------------|------|
+| AuthService | UserRepository | Runtime |
+| UserController | AuthService, UserService | Runtime |
+
+---
+
+## Risks
+
+[Unknown] **Requires human input**
+
+### Technical Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| <!-- Add technical risks --> | Low/Medium/High | Low/Medium/High | <!-- Mitigation strategy --> |
+
+### Business Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| <!-- Add business risks --> | Low/Medium/High | Low/Medium/High | <!-- Mitigation strategy --> |
+
+### Known Issues / Tech Debt
+
+[Unknown] Document any known issues discovered during analysis:
+
+| Issue | Severity | Notes |
+|-------|----------|-------|
+| <!-- Add issues --> | Low/Medium/High | <!-- Additional context --> |
+
+---
+
+## Assumptions & Open Questions
+
+### Assumptions
+
+| # | Assumption | Impact Scope | Verification Method | Status |
+|---|-----------|--------------|---------------------|--------|
+| A1 | [Assumption] <!-- describe assumption --> | <!-- affected area --> | <!-- how to verify --> | Unverified |
+
+<!-- Example:
+| A1 | [Assumption] Auth middleware validates JWT before reaching controller | AuthController, UserController | Check middleware chain in app.ts | Unverified |
+| A2 | [Assumption] Database indexes exist for all query patterns | Performance | Run EXPLAIN on common queries | Unverified |
+-->
+
+### Open Questions
+
+| # | Question | Affected Area | Owner | Deadline |
+|---|---------|--------------|-------|----------|
+| Q1 | [Need Confirmation] <!-- question --> | <!-- area --> | <!-- who --> | <!-- when --> |
+
+---
+
+## Out of Scope
+
+[Unknown] **Requires human input**
+
+What was intentionally NOT included in this feature?
+
+- [ ] <!-- Item 1 - was this intentionally excluded? -->
+- [ ] <!-- Item 2 -->
+
+---
+
+## Historical Context
+
+[Unknown] **Requires human input**
+
+### Design Decisions
+
+| Decision | Rationale | Date | Decided By |
+|----------|-----------|------|------------|
+| <!-- What was decided --> | <!-- Why --> | <!-- When --> | <!-- Who --> |
+
+### Trade-offs Made
+
+| Trade-off | Chosen Option | Alternative | Reason |
+|-----------|---------------|-------------|--------|
+| <!-- Trade-off description --> | <!-- What was chosen --> | <!-- What was rejected --> | <!-- Why --> |
+
+---
+
+## Related Resources
+
+### Code References
+
+| Resource | Path | Description |
+|----------|------|-------------|
+| Main Implementation | `src/path/to/main` | Primary code location |
+| Tests | `src/tests/path` | Test files |
+| Configuration | `src/config/path` | Config files |
+
+### Documentation
+
+[Unknown] Existing documentation (if any):
+
+- [ ] README: `path/to/readme` (exists/missing)
+- [ ] API Docs: `path/to/docs` (exists/missing)
+- [ ] Architecture: `path/to/arch` (exists/missing)
+
+### Related Specs
+
+- [ ] [SPEC-XXX] Related feature (if any)
+
+---
+
+## Analysis Metadata
+
+| Attribute | Value |
+|-----------|-------|
+| **Analyzed By** | [AI Assistant / Human Name] |
+| **Analysis Date** | YYYY-MM-DD |
+| **Tool/Method** | `/reverse-spec` command |
+| **Code Version** | Git commit hash or version |
+| **Files Analyzed** | N files |
+| **Lines of Code** | N lines |
+
+### Confidence Summary
+
+| Certainty Level | Count | Percentage |
+|-----------------|-------|------------|
+| [Confirmed] | N | X% |
+| [Inferred] | N | X% |
+| [Unknown] | N | X% |
+
+---
+
+## Version History
+
+| Version | Date | Changes | Author |
+|---------|------|---------|--------|
+| 1.0.0 | YYYY-MM-DD | Initial reverse-engineered spec | [Name] |
+
+---
+
+## Appendix: Raw Analysis Data
+
+<details>
+<summary>Click to expand code analysis output</summary>
+
+```
+<!-- Paste raw analysis output here for reference -->
+```
+
+</details>

package/bundled/templates/test-case-template.md

@@ -0,0 +1,74 @@
+# Test Case Template
+
+> Inspired by ISO/IEC/IEEE 29119-3 Test Case Specification.
+
+## Test Case: TC-{NNN}
+
+### Metadata
+
+| Field | Value |
+|-------|-------|
+| **ID** | TC-{NNN} |
+| **Title** | {Descriptive test case title} |
+| **Test Level** | Unit / Integration / System / E2E |
+| **Priority** | High / Medium / Low |
+| **Related Task** | T-{NNN} |
+| **Author** | {name} |
+| **Date** | {date} |
+
+### Preconditions
+
+- {Required state or setup before test execution}
+
+### Test Steps
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| 1 | {action} | {expected} |
+| 2 | {action} | {expected} |
+| 3 | {action} | {expected} |
+
+### Verify Command
+
+```bash
+{command to verify this test case passes}
+```
+
+### Test Data
+
+- {Input data requirements}
+
+### Postconditions
+
+- {Expected state after test execution}
+
+### Notes
+
+- {Additional information, edge cases, or references}
+
+---
+
+## Example
+
+### Test Case: TC-001
+
+| Field | Value |
+|-------|-------|
+| **ID** | TC-001 |
+| **Title** | User login with valid credentials returns JWT token |
+| **Test Level** | Integration |
+| **Priority** | High |
+| **Related Task** | T-003 |
+
+**Preconditions**: Test database seeded with user `test@example.com`
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| 1 | POST /api/login with valid credentials | 200 OK |
+| 2 | Check response body | Contains `token` field |
+| 3 | Decode JWT token | Contains correct user ID |
+
+**Verify Command**:
+```bash
+vitest run src/auth/login.integration.test.ts
+```

package/bundled/templates/test-plan-template.md

@@ -0,0 +1,74 @@
+# Test Plan Template
+
+> Inspired by ISO/IEC/IEEE 29119-3.
+
+## 1. Test Plan Identifier
+
+- **Plan ID**: TP-{project}-{version}
+- **Project**: {project name}
+- **Version**: {version}
+- **Date**: {date}
+
+## 2. Test Scope
+
+### In Scope
+- {Feature/component to test}
+
+### Out of Scope
+- {Explicitly excluded items}
+
+## 3. Test Levels
+
+| Level | Command | Timeout | Scope |
+|-------|---------|---------|-------|
+| Unit (UT) | `{test:unit command}` | 120000ms | Single function/method |
+| Integration (IT) | `{test:integration command}` | 120000ms | Multiple components |
+| System (ST) | `{test:system command}` | 300000ms | Complete subsystem |
+| E2E | `{test:e2e command}` | 600000ms | Full user flows |
+
+## 4. Static Analysis
+
+- **Command**: `{lint/type-check/analysis command}`
+- **Tools**: {ESLint, ruff, mypy, etc.}
+
+## 5. Quality Thresholds
+
+| Setting | Value |
+|---------|-------|
+| Profile | strict / standard / minimal / none |
+| Verify | true/false |
+| Max Retries | {number} |
+
+## 6. Test Completion Criteria
+
+> ISO 29119: Test Completion Criteria / Test Exit Criteria
+> Agile/Scrum: Definition of Done (DoD)
+
+| Check | Command | Required |
+|-------|---------|----------|
+| All tests pass | `{test command}` | Yes |
+| No lint errors | `{lint command}` | Yes |
+| Type check clean | `{typecheck command}` | Yes |
+| Static analysis clean | `{command}` | Yes |
+| Documentation updated | _(manual review)_ | No |
+
+## 7. Test Environment
+
+| Environment | Purpose | Mock Strategy |
+|-------------|---------|---------------|
+| local | UT, fast IT | In-memory mocks |
+| ci | Full suite | Containerized deps |
+| sit | ST | Stubbed external APIs |
+| staging | E2E | No mocks |
+
+## 8. Risks and Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {risk} | {impact} | {mitigation} |
+
+## 9. Approval
+
+- **Author**: {name}
+- **Reviewer**: {name}
+- **Approved**: {date}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.7.5",
+  "version": "6.9.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -56,11 +56,15 @@
     "prepare": "node ../scripts/setup-husky.mjs",
     "test:upgrade": "node scripts/test-upgrade-path.mjs",
     "check:bundle-parity": "node scripts/check-bundle-parity.mjs",
-    "prepack": "node scripts/prepack.mjs"
+    "prepack": "node scripts/prepack.mjs",
+    "check:reachability": "node scripts/check-module-reachability.mjs",
+    "check:command-existence": "node scripts/check-command-existence.mjs",
+    "check:effect-boundary": "node scripts/check-effect-boundary.mjs",
+    "check:effect-boundary:self-test": "node scripts/check-effect-boundary.mjs --self-test"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "chalk": "^5.3.0",
+    "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
     "ora": "^9.4.0",
@@ -69,8 +73,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.1.5",
-    "eslint": "10.7.0",
-    "globals": "17.7.0",
+    "eslint": "10.8.0",
+    "globals": "17.11.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.3",
     "vitest": "^4.1.5"

package/src/commands/audit.js

@@ -14,6 +14,15 @@
 import chalk from 'chalk';
 import { checkbox, input } from '@inquirer/prompts';
 import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import {
+  analyseEffectBoundary,
+  formatReport,
+  parseBaselineTsv,
+  DEFAULT_CONFIG_PATH,
+  DEFAULT_BASELINE_PATH
+} from '../utils/effect-boundary.js';
 import { readManifest, isInitialized } from '../utils/copier.js';
 import { runHealthCheck } from '../utils/health-checker.js';
 import { runHealthScore, saveScoreSnapshot, loadTrend } from '../utils/health-scorer.js';
@@ -59,6 +68,17 @@ export async function auditCommand(options = {}) {
     return handleScoreMode(projectPath, options);
   }
 
+  // Handle --effects mode (XSPEC-383 R8 — static effect boundary gate).
+  //
+  // It is its own mode rather than a fourth layer of the health/patterns/friction
+  // report for one reason: it has a THREE-state exit code (0 clean / 1 findings /
+  // 2 cannot measure), and folding it into a report that always exits 0 would
+  // erase exactly the state it exists to preserve — "we could not measure this"
+  // must not print the same thing as "this is fine".
+  if (options.effects) {
+    return handleEffectsMode(projectPath, options);
+  }
+
   // Determine which layers to run
   const hasLayerFlag = options.health || options.patterns || options.friction;
   const runHealth = hasLayerFlag ? !!options.health : true;
@@ -140,6 +160,68 @@ export async function auditCommand(options = {}) {
   }
 }
 
+/**
+ * XSPEC-383 R8 — static effect boundary gate.
+ *
+ * Shape D: a component that is reachable, is called, runs, reports success, and
+ * does nothing. R3's reachability gate cannot see it — reachability asks who
+ * calls this file (in-edges); shape D lives in the out-edges (what it finally
+ * touches). Opposite direction.
+ *
+ * All judgement lives in utils/effect-boundary.js. This function is one of its
+ * two entry points; the other is scripts/check-effect-boundary.mjs, which CI
+ * and `npm run check:effect-boundary` use. The engine sits in src/ because
+ * `cli/scripts/` ships zero files (measured with `npm pack --dry-run`), so an
+ * engine living only there would not be on an adopter's disk at all.
+ *
+ * @param {string} projectPath
+ * @param {Object} options
+ */
+function handleEffectsMode(projectPath, options) {
+  const configPath = resolvePath(projectPath, options.effectsConfig || DEFAULT_CONFIG_PATH);
+
+  if (!existsSync(configPath)) {
+    console.error(chalk.red('[effect-boundary] FATAL: no effect-family config at ') + configPath);
+    console.error('  This gate asks whether each implementation of an effect interface reaches');
+    console.error('  anything outside this process. It cannot answer that without being told');
+    console.error('  which implementations form a family.');
+    console.error('');
+    console.error(`  Declare them by glob in ${DEFAULT_CONFIG_PATH} (or pass --effects-config <path>):`);
+    console.error('    { "families": [ { "name": "deploy-adapters",');
+    console.error('                      "include": ["src/**/adapters/*.adapter.ts"] } ] }');
+    console.error('');
+    console.error('  Declared by glob, not by a list of filenames: a glob keeps matching the');
+    console.error('  adapter nobody has written yet, which is the one this gate exists to catch.');
+    console.error('');
+    console.error(chalk.yellow('  Exiting 2 (cannot measure), not 0. A gate with nothing to check must not print a green tick.'));
+    process.exit(2);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    console.error(chalk.red(`[effect-boundary] FATAL: config exists but does not parse: ${configPath}: ${e.message}`));
+    console.error('  This is "cannot read the config", not "there is no config".');
+    process.exit(2);
+  }
+
+  const baselinePath = resolvePath(projectPath, DEFAULT_BASELINE_PATH);
+  const baseline = existsSync(baselinePath)
+    ? parseBaselineTsv(readFileSync(baselinePath, 'utf8'))
+    : { entries: [], errors: [] };
+
+  const result = analyseEffectBoundary({ projectPath, config });
+  const { lines, exitCode } = formatReport(result, baseline);
+
+  if (options.format === 'json') {
+    console.log(JSON.stringify({ exitCode, report: lines, result }, null, 2));
+  } else {
+    for (const line of lines) console.log(line);
+  }
+  process.exit(exitCode);
+}
+
 /**
  * Output full terminal report
  * @param {Object} auditResult