universal-dev-standards 5.0.0-rc.6 → 5.0.0-rc.9

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

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/core/documentation-structure.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/documentation-structure.md)
 
-**Version**: 1.4.0
-**Last Updated**: 2026-03-04
+**Version**: 1.5.0
+**Last Updated**: 2026-03-17
 **Applicability**: All software projects requiring documentation
 **Scope**: partial
 **Industry Standards**: None (Industry convention)
@@ -17,6 +17,95 @@ This standard defines a consistent documentation structure for software projects
 
 ---
 
+## Documentation Classification (Diátaxis)
+
+All documentation should be classified into one of four types based on the [Diátaxis framework](https://diataxis.fr/). This explicit classification helps readers find the right document and helps writers focus on the correct content.
+
+### The Four Document Types
+
+| Type | Purpose | User Need | Orientation | Example |
+|------|---------|-----------|-------------|---------|
+| **Tutorial** | Learning-oriented | "I want to learn" | Practical steps | Getting started guide, first project walkthrough |
+| **How-to** | Task-oriented | "I want to accomplish X" | Practical steps | Deployment guide, migration checklist |
+| **Reference** | Information-oriented | "I need to look up Y" | Theoretical knowledge | API reference, configuration parameters |
+| **Explanation** | Understanding-oriented | "I want to understand why" | Theoretical knowledge | Architecture overview, ADR, design rationale |
+
+### Document Type Header
+
+Add a `Document Type` field to document headers for explicit classification:
+
+```markdown
+**Document Type**: Tutorial | How-to | Reference | Explanation
+```
+
+### Mapping to Standard Documents
+
+| Standard Document | Diátaxis Type | Rationale |
+|-------------------|---------------|-----------|
+| README.md | Tutorial / How-to | Quick start orientation |
+| getting-started.md | Tutorial | Step-by-step learning |
+| ARCHITECTURE.md | Explanation | Understanding system design |
+| API Reference | Reference | Looking up endpoints |
+| DEPLOYMENT.md | How-to | Task: deploy the system |
+| MIGRATION.md | How-to | Task: migrate the system |
+| ADR/ | Explanation | Understanding decisions |
+| troubleshooting.md | How-to | Task: fix a problem |
+| CHANGELOG.md | Reference | Looking up change history |
+| Flow documentation | Reference / Explanation | Understanding data flows |
+
+---
+
+## LLM Discovery Files
+
+Projects that publish documentation for external consumption should consider providing LLM-optimized discovery files, similar to `robots.txt` for search engines.
+
+### llms.txt Standard
+
+The `llms.txt` file (placed at the project or site root) provides a structured index for LLM-based retrieval systems.
+
+**Format**:
+
+```markdown
+# Project Name
+
+> Brief one-line description of the project.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md): Tutorial for new users
+- [API Reference](docs/api-reference.md): Complete REST API documentation
+- [Architecture](docs/architecture.md): System design and component overview
+
+## Optional
+
+- [CHANGELOG](CHANGELOG.md): Version history
+- [Contributing](CONTRIBUTING.md): Contribution guidelines
+```
+
+### When to Create llms.txt
+
+| Scenario | Create llms.txt? | Rationale |
+|----------|:-----------------:|-----------|
+| Public open source project | ✅ Yes | Helps AI tools discover and index docs |
+| Public API with external consumers | ✅ Yes | Enables AI-assisted API integration |
+| Internal company project | ⚪ Optional | Useful if using internal AI tools |
+| Private/personal project | ❌ No | No external consumers |
+
+### Placement
+
+```
+project-root/
+├── llms.txt                     # LLM discovery file
+├── llms-full.txt                # Optional: full concatenated docs
+├── README.md
+└── docs/
+```
+
+- `llms.txt`: Structured index with links and descriptions
+- `llms-full.txt` (optional): Full documentation concatenated into a single file for complete context ingestion
+
+---
+
 ## Standard Documentation Structure
 
 ```
@@ -1278,6 +1367,62 @@ This matrix extends the Document Requirements Matrix above to include all docume
 
 ---
 
+## Documentation Testing
+
+Documentation should be tested systematically, not just reviewed manually. This section defines testable quality layers.
+
+### Testing Layers
+
+| Layer | What It Tests | Tools | CI Stage |
+|-------|---------------|-------|----------|
+| **Link Validation** | All internal/external links resolve | markdown-link-check, lychee | Pre-commit / PR |
+| **Code Sample Testing** | Code examples compile and run | doctest, mdx-js, custom scripts | PR check |
+| **Structure Validation** | Required sections present, heading hierarchy correct | Custom linter, remark-lint | Pre-commit |
+| **Content Freshness** | Documents updated within retention period | Custom script (check Last Updated date) | Release |
+| **Traceability** | Every feature has documentation, every doc maps to code | Traceability matrix | Release |
+
+### Code Sample Validation
+
+Code examples in documentation should be validated to prevent drift from actual implementation:
+
+```markdown
+<!-- doctest: lang=bash, skip=false -->
+```bash
+npm install your-package
+npm test
+```
+```
+
+**Validation Approaches**:
+
+| Approach | Description | Best For |
+|----------|-------------|----------|
+| **Extract and run** | Extract code blocks, execute in sandbox | CLI examples, scripts |
+| **Import from source** | Include actual source files in docs | API usage examples |
+| **Snapshot comparison** | Compare output against expected | Command output examples |
+
+### Documentation Traceability Matrix
+
+Track the relationship between features, code, and documentation:
+
+```markdown
+| Feature | Code Location | Documentation | Test | Status |
+|---------|---------------|---------------|------|--------|
+| User auth | src/auth/ | docs/api.md#auth | tests/auth.test.js | ✅ Current |
+| Export CSV | src/export/ | docs/api.md#export | tests/export.test.js | ⚠️ Stale |
+| Webhooks | src/webhooks/ | ❌ Missing | tests/webhooks.test.js | ❌ Undocumented |
+```
+
+### CI/CD Integration
+
+| Stage | Checks | Blocking |
+|-------|--------|:--------:|
+| **Pre-commit** | Link check, structure lint | ✅ Yes |
+| **PR check** | Code sample validation, freshness | ✅ Yes |
+| **Release** | Full traceability audit, all layers | ⚠️ Warning |
+
+---
+
 ## Related Standards
 
 - [Documentation Writing Standards](documentation-writing-standards.md)
@@ -1291,6 +1436,7 @@ This matrix extends the Document Requirements Matrix above to include all docume
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.5.0 | 2026-03-17 | Added: Diátaxis documentation classification, LLM Discovery Files (llms.txt), Documentation Testing standards (5-layer testing, traceability matrix, CI/CD integration) |
 | 1.4.0 | 2026-03-04 | Added: Development Artifacts (docs/working/) directory and lifecycle management, Expanded Document Types Matrix |
 | 1.3.0 | 2026-01-24 | Added: Specification documentation standards with specs/ directory structure |
 | 1.2.2 | 2025-12-24 | Added: Related Standards section |