universal-dev-standards 5.0.0-rc.5 → 5.0.0-rc.8

package/bin/uds.js

@@ -20,7 +20,8 @@ import { auditCommand } from '../src/commands/audit.js';
 import { uninstallCommand } from '../src/commands/uninstall.js';
 import { specCreateCommand, specListCommand, specShowCommand, specConfirmCommand, specArchiveCommand, specDeleteCommand } from '../src/commands/spec.js';
 import { startCommand, missionStatusCommand, missionPauseCommand, missionResumeCommand, missionCancelCommand, missionListCommand } from '../src/commands/start.js';
-import { setLanguage, setLanguageExplicit, detectLanguage } from '../src/i18n/messages.js';
+import { setLanguage, setLanguageExplicit, detectLanguage, t } from '../src/i18n/messages.js';
+import { maybeCheckForUpdates, formatUpdateNotice } from '../src/utils/update-checker.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
@@ -40,6 +41,19 @@ program
       // Explicit setting: mark as explicitly set to prevent override
       setLanguageExplicit(uiLang);
     }
+  })
+  .hook('postAction', async (thisCommand) => {
+    const cmd = thisCommand.name();
+    const notifyCommands = ['init', 'list', 'add', 'config'];
+    if (!notifyCommands.includes(cmd)) return;
+    try {
+      const result = await maybeCheckForUpdates(pkg.version);
+      if (result?.shouldNotify) {
+        console.log(formatUpdateNotice(result, t()));
+      }
+    } catch {
+      // Silent failure — update check should never break CLI
+    }
   });
 
 program
@@ -106,6 +120,7 @@ program
   .option('--restore', 'Restore all modified and missing files')
   .option('--restore-missing', 'Restore only missing files')
   .option('--no-interactive', 'Disable interactive mode')
+  .option('--ci', 'CI mode: disable interactive prompts and set exit code on issues')
   .option('--migrate', 'Migrate legacy manifest to hash-based tracking')
   .option('--offline', 'Skip npm registry check for CLI updates')
   .action(checkCommand);

package/bundled/ai/options/documentation/api-docs.ai.yaml

@@ -4,8 +4,8 @@
 id: api-docs
 meta:
   parent: documentation-structure
-  version: "1.0.0"
-  description: API reference documentation standards
+  version: "1.1.0"
+  description: API reference documentation standards (enhanced automation)
 
 best_for:
   - REST APIs
@@ -145,6 +145,21 @@ example_endpoint_doc: |
   | 400 | Invalid request body |
   | 409 | Email already exists |
 
+automation:
+  validation:
+    - name: Link check
+      tool: markdown-link-check
+      stage: pre-commit
+    - name: OpenAPI lint
+      tool: spectral
+      stage: PR check
+    - name: Example validation
+      tool: Custom script (extract + run code blocks)
+      stage: PR check
+  llm_discovery:
+    description: Include API endpoints in llms.txt for LLM-assisted integration
+    format: "- [Endpoint Group](docs/api.md#section): Description"
+
 tools:
   generators:
     - name: swagger-codegen

package/bundled/ai/standards/context-aware-loading.ai.yaml

@@ -153,6 +153,23 @@ standard:
         /release, /commit → workflow
       priority: required
 
+    - id: version-check-on-uds-operation
+      trigger: "user invokes a UDS slash command or UDS-related operation"
+      instruction: >
+        When the user invokes a UDS-related slash command (/commit, /sdd,
+        /review, /release, /tdd, /bdd, /docs, /changelog, etc.) for the
+        FIRST TIME in the current conversation, check for UDS updates:
+
+        1. Read .standards/manifest.json → extract upstream.version
+        2. Run: npm view universal-dev-standards dist-tags --json
+        3. Compare upstream.version with the "latest" tag from npm
+        4. If a newer version exists, display ONE line before your response:
+           "ℹ UDS v{latest} 已發布（目前 v{current}）— 執行 `uds update` 更新"
+        5. If versions match or npm is unreachable, skip silently
+        6. Only check ONCE per conversation — do not repeat on subsequent
+           UDS operations in the same session
+      priority: optional
+
   architecture:
     classification: always-on-protocol
     note: >

package/bundled/ai/standards/documentation-structure.ai.yaml

@@ -3,10 +3,10 @@
 
 id: documentation-structure
 meta:
-  version: "1.3.0"
-  updated: "2025-12-29"
+  version: "1.4.0"
+  updated: "2026-03-17"
   source: core/documentation-structure.md
-  description: Consistent documentation structure for software projects
+  description: Consistent documentation structure for software projects (Diátaxis classification, LLM discovery, doc testing)
 
 options:
   documentation_style:
@@ -68,7 +68,70 @@ structure:
         purpose: Architecture diagrams
         formats: [".mmd", ".puml", ".drawio"]
 
+diataxis_classification:
+  types:
+    - id: tutorial
+      purpose: Learning-oriented
+      user_need: "I want to learn"
+      examples: [getting-started.md, first-project-walkthrough.md]
+    - id: how-to
+      purpose: Task-oriented
+      user_need: "I want to accomplish X"
+      examples: [deployment.md, migration.md, troubleshooting.md]
+    - id: reference
+      purpose: Information-oriented
+      user_need: "I need to look up Y"
+      examples: [api-reference.md, CHANGELOG.md, configuration.md]
+    - id: explanation
+      purpose: Understanding-oriented
+      user_need: "I want to understand why"
+      examples: [architecture.md, ADR/, design-rationale.md]
+
+llm_discovery:
+  files:
+    - name: llms.txt
+      location: project root
+      purpose: Structured index for LLM retrieval systems
+      when: Public projects or projects using AI tools
+    - name: llms-full.txt
+      location: project root
+      purpose: Full concatenated docs for complete context
+      when: Optional
+
+doc_testing:
+  layers:
+    - name: Link Validation
+      tools: [markdown-link-check, lychee]
+      ci_stage: pre-commit
+    - name: Code Sample Testing
+      tools: [doctest, custom scripts]
+      ci_stage: PR check
+    - name: Structure Validation
+      tools: [remark-lint, custom linter]
+      ci_stage: pre-commit
+    - name: Content Freshness
+      tools: [custom date-check script]
+      ci_stage: release
+    - name: Traceability
+      tools: [traceability matrix]
+      ci_stage: release
+
 rules:
+  - id: diataxis-classify
+    trigger: creating new documentation
+    instruction: Classify document as Tutorial, How-to, Reference, or Explanation and add Document Type header
+    priority: recommended
+
+  - id: llm-discovery
+    trigger: creating public project documentation
+    instruction: Consider adding llms.txt for LLM discoverability
+    priority: recommended
+
+  - id: doc-testing-links
+    trigger: adding documentation
+    instruction: Validate all links before committing
+    priority: required
+
   - id: root-uppercase
     trigger: creating root documentation
     instruction: Use UPPERCASE for root-level docs (README, CONTRIBUTING, CHANGELOG)

package/bundled/ai/standards/documentation-writing-standards.ai.yaml

@@ -3,10 +3,10 @@
 
 id: documentation-writing-standards
 meta:
-  version: "1.0.1"
-  updated: "2025-12-30"
+  version: "1.1.0"
+  updated: "2026-03-17"
   source: core/documentation-writing-standards.md
-  description: Documentation requirements based on project types
+  description: Documentation requirements based on project types (enhanced ADR, LLM writing, quality metrics, translation-friendly)
 
 project_types:
   new_project:
@@ -127,14 +127,85 @@ document_categories:
     naming: "NNN-kebab-case-title.md"
     required_sections:
       - Title
+      - Date (YYYY-MM-DD)
       - Status (proposed/accepted/deprecated/superseded)
+      - Deciders (who participated)
       - Context
       - Decision
       - Consequences
     recommended_sections:
+      - Drivers (key factors)
       - Alternatives Considered
+      - Related ADRs (supersedes/superseded-by)
+    lifecycle: "proposed → accepted → [deprecated | superseded]"
+    decision_matrix:
+      description: "When to write ADR (impact × reversibility)"
+      adr_required: "High impact + Hard to reverse"
+      optional: "High impact + Easy to reverse OR Low impact + Hard to reverse"
+      not_needed: "Low impact + Easy to reverse"
+
+llm_writing:
+  rules:
+    - Short paragraphs (3-5 lines)
+    - Consistent terminology throughout
+    - Always specify language in code blocks
+    - Avoid pronoun ambiguity across paragraphs
+    - Each H2 section should be context-self-sufficient
+    - State explicit negation when distinctions matter
+  chunking:
+    max_h2_size: "4K-8K tokens (~3000 words)"
+    principle: "One topic per H2, front-load summaries"
+  retrieval_metadata: [title, scope, difficulty, tags, last_validated]
+
+translation_friendly:
+  writing_rules:
+    - Complete sentences (avoid fragments)
+    - Avoid idioms and slang
+    - Consistent terminology (follow glossary)
+    - Simple SVO sentence structure
+    - Explicit references (avoid ambiguous pronouns)
+  glossary_file: glossary.md
+  translation_status_fields: [translation_status, source_version, source_hash, translated_by, last_synced]
+
+quality_metrics:
+  leading:
+    - name: Coverage
+      target: "≥90% public APIs documented"
+    - name: Freshness
+      target: "All docs updated within 90 days"
+    - name: Link Health
+      target: "100% valid links"
+    - name: Example Validity
+      target: "100% code examples run"
+    - name: Structure Compliance
+      target: "All docs have required sections"
+  lagging:
+    - Support ticket reduction
+    - Onboarding time
+    - Doc-related PR comments
+  tools: [markdown-link-check, lychee, remark-lint, textstat, vale]
 
 rules:
+  - id: llm-writing
+    trigger: writing documentation
+    instruction: Follow LLM-optimized writing rules (short paragraphs, consistent terms, context self-sufficiency)
+    priority: recommended
+
+  - id: translation-friendly
+    trigger: writing documentation for multilingual projects
+    instruction: Use complete sentences, avoid idioms, follow glossary, use simple sentence structure
+    priority: recommended
+
+  - id: quality-metrics
+    trigger: documentation review
+    instruction: Check documentation quality metrics (coverage, freshness, link health)
+    priority: recommended
+
+  - id: adr-enhanced
+    trigger: creating ADR
+    instruction: Include Date, Deciders, Drivers fields; use decision matrix (impact × reversibility) to decide if ADR is needed
+    priority: required
+
   - id: project-type-docs
     trigger: starting a project
     instruction: Identify project type and create required documents

package/bundled/ai/standards/spec-driven-development.ai.yaml

@@ -10,6 +10,10 @@ meta:
 
 workflow:
   stages:
+    - stage: Discuss
+      description: Capture gray areas, lock scope, establish canonical refs
+      artifacts: read_first list, scope definition, gray area log
+
     - stage: Proposal
       description: Define what to change and why
       artifacts: proposal.md
@@ -41,7 +45,7 @@ principles:
 
   methodology_over_tooling:
     rule: SDD is a methodology, not bound to a single tool
-    universal_flow: Proposal -> Review -> Implementation -> Verification -> Archive
+    universal_flow: Discuss -> Proposal -> Review -> Implementation -> Verification -> Archive
 
   spec_first:
     rule: No functional code changes without approved specification

package/bundled/ai/standards/structured-task-definition.ai.yaml

@@ -0,0 +1,108 @@
+# Structured Task Definition - AI Optimized
+# Source: core/structured-task-definition.md
+
+id: structured-task-definition
+meta:
+  version: "1.0.0"
+  updated: "2026-03-17"
+  source: core/structured-task-definition.md
+  description: Standard structure for AI task definitions with 4 required fields
+
+principles:
+  grounded_execution:
+    rule: Every AI task must read specified files before acting
+    rationale: Prevents hallucination by establishing ground truth from actual code
+
+  concrete_actions:
+    rule: Task actions must specify exact files, locations, and operations
+    rationale: Eliminates vague instructions like "improve" or "enhance"
+
+  measurable_completion:
+    rule: Acceptance criteria must use Given/When/Then format
+    rationale: Every criterion is independently verifiable
+
+  executable_verification:
+    rule: Verification uses commands (grep, test, ls), not subjective judgment
+    rationale: Machine-verifiable outcomes eliminate ambiguity
+
+required_fields:
+  read_first:
+    description: Files that MUST be read before task execution
+    purpose: Establish ground truth, prevent hallucination
+    format: "List of {path, reason} entries"
+    rules:
+      - All listed files must exist
+      - Include implementation files AND their tests
+      - Include relevant spec documents (if SDD active)
+
+  action:
+    description: Concrete steps with exact file paths and operations
+    purpose: Remove all ambiguity about what to do
+    format: "List of {step, file, operation, location, description}"
+    operations: [add, modify, delete, move, rename]
+    rules:
+      - Each step specifies a single file
+      - Line numbers provide context (approximate OK)
+      - No step should be "do whatever seems right"
+
+  acceptance_criteria:
+    description: GWT-format completion conditions
+    purpose: Testable conditions with no room for "it seems to work"
+    format: "List of {id, given, when, then}"
+    rules:
+      - Use Given/When/Then format
+      - Each AC independently verifiable
+      - Include regression criteria
+      - Number for traceability (AC-1, AC-2)
+
+  verification:
+    description: Executable commands that verify completion
+    purpose: Machine-verifiable outcomes
+    format: "List of {command, expect}"
+    rules:
+      - Every AC has at least one verification command
+      - Prefer deterministic checks (grep, test, ls)
+      - Include test execution
+      - Failed verification = task not complete
+
+rules:
+  - id: task-must-have-read-first
+    trigger: creating AI task or sub-task
+    instruction: >
+      Every task must include a read_first field listing files to read
+      before execution. This establishes ground truth and prevents
+      hallucination about code structure or API signatures.
+    priority: required
+
+  - id: task-must-have-concrete-actions
+    trigger: defining task actions
+    instruction: >
+      Task actions must specify exact file paths, line locations,
+      and operations (add/modify/delete/move/rename). Vague instructions
+      like "improve error handling" or "add validation" are not acceptable.
+    priority: required
+
+  - id: task-must-have-verification
+    trigger: completing task definition
+    instruction: >
+      Every task must include verification commands that can objectively
+      confirm completion. Use grep, test commands, file existence checks,
+      or test suite execution — never subjective judgment like "looks good."
+    priority: required
+
+  - id: task-scope-matching
+    trigger: evaluating whether to apply full structure
+    instruction: >
+      Apply full 4-field structure for features, bug fixes, and refactoring.
+      Trivial changes (typos, formatting) may skip. Hotfixes need at minimum
+      read_first + verification.
+    priority: recommended
+
+quick_reference:
+  fields:
+    columns: [Field, Purpose, Anti-Pattern Prevented]
+    rows:
+      - [read_first, Establish ground truth, Anti-hallucination]
+      - [action, Concrete steps, Anti-ambiguity]
+      - [acceptance_criteria, GWT conditions, Anti-omission]
+      - [verification, Executable checks, Anti-subjectivity]

package/bundled/ai/standards/workflow-state-protocol.ai.yaml

@@ -0,0 +1,121 @@
+# Workflow State Protocol - AI Optimized
+# Source: core/workflow-state-protocol.md
+
+id: workflow-state-protocol
+meta:
+  version: "1.0.0"
+  updated: "2026-03-17"
+  source: core/workflow-state-protocol.md
+  description: Protocol for persisting and restoring workflow state across AI sessions
+
+principles:
+  state_persistence:
+    rule: Multi-phase workflows must save state at phase transitions
+    rationale: Enables resumption after session boundaries without state loss
+
+  event_sourcing:
+    rule: Important decisions and transitions are logged in append-only event log
+    rationale: Provides audit trail and enables understanding of workflow history
+
+  session_independence:
+    rule: Each AI session should be able to resume any workflow from saved state
+    rationale: Context window limits make single-session completion unreliable
+
+state_file:
+  location: ".workflow-state/{workflow}-{id}.yaml"
+  required_fields:
+    - workflow      # Workflow type (sdd, feature-dev, etc.)
+    - spec_id       # Spec or task identifier
+    - current_phase # Active phase ID
+    - status        # in-progress | paused | blocked | completed | abandoned
+    - updated       # Last update timestamp (ISO 8601)
+    - phases_completed  # Ordered list of completed phase IDs
+  optional_fields:
+    - title
+    - iteration_count
+    - created
+    - artifacts
+    - progress_summary
+    - completed_steps
+    - next_steps
+    - open_questions
+    - decisions
+
+event_log:
+  location: ".workflow-state/{workflow}-{id}.log.yaml"
+  format: append-only YAML list
+  event_types:
+    - phase_enter    # Workflow enters a new phase
+    - phase_exit     # Workflow exits a phase
+    - checkpoint     # Notable milestone
+    - decision       # Important decision made
+    - error          # Error or failure
+    - interruption   # Workflow paused (HITL or context limit)
+    - resumption     # Workflow resumed from saved state
+  required_event_fields:
+    - timestamp
+    - event_type
+    - phase
+    - summary
+
+rules:
+  - id: state-save-on-phase-transition
+    trigger: workflow phase changes
+    instruction: >
+      When a workflow transitions between phases, update the state file
+      with new current_phase, add the completed phase to phases_completed,
+      and update the timestamp. Also append a phase_exit and phase_enter
+      event to the event log.
+    priority: required
+
+  - id: state-load-on-resume
+    trigger: session start or workflow command invocation
+    instruction: >
+      At session start, check .workflow-state/ for any files with
+      status 'in-progress' or 'paused'. If found, inform the user
+      of active workflows and offer to resume. When a workflow command
+      is invoked (e.g., /sdd implement SPEC-042), check for existing
+      state before starting fresh.
+    priority: required
+
+  - id: state-save-on-session-end
+    trigger: AI session ending with active workflow
+    instruction: >
+      Before ending a session during an active workflow, save current
+      progress to the state file. Update progress_summary, next_steps,
+      and open_questions to enable seamless resumption.
+    priority: required
+
+  - id: event-log-on-decision
+    trigger: important design or scope decision made
+    instruction: >
+      When a significant decision is made during a workflow (design choice,
+      scope change, technology selection), append a 'decision' event to the
+      event log with the decision summary and reasoning.
+    priority: recommended
+
+  - id: state-staleness-warning
+    trigger: loading state file older than 7 days
+    instruction: >
+      If a state file's 'updated' timestamp is more than 7 days old,
+      warn the user that the workflow state may be stale and suggest
+      reviewing it before continuing.
+    priority: recommended
+
+  - id: gitignore-workflow-state
+    trigger: creating .workflow-state/ directory
+    instruction: >
+      Recommend adding .workflow-state/ to .gitignore as workflow state
+      is session-specific. Exception: teams sharing state across developers
+      may version-control it but should clean up completed workflows.
+    priority: recommended
+
+quick_reference:
+  state_lifecycle:
+    columns: [Event, Action]
+    rows:
+      - [Phase transition, Update state file + append event log]
+      - [Important decision, Record in state decisions + event log]
+      - [Session ending, Save progress_summary and next_steps]
+      - [Session starting, Check .workflow-state/ for active workflows]
+      - [Workflow complete, Set status to completed]

package/bundled/core/context-aware-loading.md

@@ -95,23 +95,63 @@ Projects configure domain mappings in `manifest.json`:
 
 ---
 
-## 3. Implementation Guidelines
+## 3. Custom Domains
 
-### 3.1 For Standard Authors
+Projects can define custom domains in `manifest.json` using the `extensions` array. Custom domains are **additive only** — they cannot override built-in domains.
+
+### 3.1 Extension Format
+
+```json
+{
+  "extensions": [
+    {
+      "type": "custom-domain",
+      "domain": "ml-pipeline",
+      "description": "Standards for ML pipeline workflows",
+      "triggers": ["pipeline", "model training", "dataset", "*.pipeline.*"],
+      "standards": ["ai/standards/custom-ml-pipeline.ai.yaml"]
+    }
+  ]
+}
+```
+
+### 3.2 Custom Domain Rules
+
+| Rule | Description |
+|------|-------------|
+| **Additive only** | Custom domains cannot override or shadow built-in domains |
+| **Unique names** | Domain names must not conflict with built-in domain names |
+| **Standard paths** | Referenced standards must exist in the project |
+| **Trigger format** | Same format as built-in domain triggers (keywords, file patterns, commands) |
+
+### 3.3 Hook-Based Enforcement (Optional)
+
+For Claude Code users, a `UserPromptSubmit` hook can automatically inject relevant standards based on the user's prompt. The hook reads the prompt, matches it against manifest domain triggers (both built-in and custom), and outputs matching standard file paths as context.
+
+**Requirements:**
+- Hook execution must complete in < 500ms
+- Hook failures must not block the user's prompt
+- See `scripts/hooks/inject-standards.js` for reference implementation
+
+---
+
+## 4. Implementation Guidelines
+
+### 4.1 For Standard Authors
 
 - Register new standards in `manifest.json` under the appropriate domain
 - Choose `always-on` only for standards that genuinely apply to every interaction
 - Define specific, actionable triggers in the domain configuration (not vague keywords)
 - Assign each standard to exactly one domain
 
-### 3.2 For AI Tool Integrations
+### 4.2 For AI Tool Integrations
 
 - At session start, always load the `always-on` domain
 - Parse user's first message for trigger keywords before loading additional standards
 - When in doubt, load the standard — false positives are better than missing context
 - Cache domain membership for the session duration
 
-### 3.3 Backward Compatibility
+### 4.3 Backward Compatibility
 
 - Existing `manifest.json` without `domains` continues to work (all standards loaded)
 - The `domains` field is additive — it does not remove existing `standards` list behavior