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

package/bin/uds.js

@@ -106,6 +106,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/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

package/bundled/core/spec-driven-development.md

@@ -25,8 +25,9 @@ SDD operates at different maturity levels: Spec-first (discard after completion)
 
 | Aspect | Description |
 |--------|-------------|
-| **Core Workflow** | Proposal → Review → Implementation → Verification → Archive |
+| **Core Workflow** | Discuss → Proposal → Review → Implementation → Verification → Archive |
 | **Key Principle** | Spec First, Code Second |
+| **AC Format** | Given/When/Then (GWT) — enables structured BDD derivation |
 | **Test Generation** | Forward Derivation (/derive-bdd, /derive-tdd, /derive-all) |
 | **Maturity Levels** | Spec-first, Spec-anchored, Spec-as-source |
 | **Tools** | OpenSpec, Spec Kit, Manual (file-based) |

package/bundled/core/structured-task-definition.md

@@ -0,0 +1,245 @@
+# Structured Task Definition Standards
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-17
+**Applicability**: All projects using AI-assisted development
+**Scope**: universal
+**Industry Standards**: Inspired by GSD (Get Shit Done) task structure
+**References**: [GSD](https://github.com/gsd-build/get-shit-done)
+
+---
+
+## Summary
+
+Structured Task Definition ensures that every AI task includes the minimum context needed for reliable execution. By requiring four mandatory fields — `read_first`, `action`, `acceptance_criteria`, and `verification` — this standard prevents hallucination, eliminates ambiguity, and ensures every task outcome is objectively verifiable.
+
+---
+
+## Quick Reference
+
+| Aspect | Description |
+|--------|-------------|
+| **Core Principle** | Every task must be grounded, specific, testable, and verifiable |
+| **Required Fields** | `read_first`, `action`, `acceptance_criteria`, `verification` |
+| **Anti-Hallucination** | `read_first` establishes ground truth before execution |
+| **Anti-Ambiguity** | `action` specifies exact files, line numbers, and operations |
+| **Anti-Omission** | `acceptance_criteria` uses GWT format for completeness |
+| **Anti-Subjectivity** | `verification` uses executable commands, not judgment |
+
+---
+
+## The Four Required Fields
+
+### 1. `read_first` — Establish Ground Truth
+
+A list of files that MUST be read before executing the task. This prevents the AI from hallucinating about code structure, API signatures, or project conventions.
+
+**Purpose**: Build accurate mental model from actual code, not assumptions.
+
+**Format**:
+```yaml
+read_first:
+  - path: src/auth/login.js
+    reason: Contains current login implementation
+  - path: tests/auth/login.test.js
+    reason: Existing test patterns to follow
+  - path: docs/specs/SPEC-042.md
+    reason: Approved specification for this change
+```
+
+**Rules**:
+- All listed files must exist (verified before task execution)
+- Include both implementation files and their tests
+- Include the relevant spec document (if SDD is active)
+- Include config files that affect behavior
+
+### 2. `action` — Concrete Steps
+
+A list of specific, unambiguous steps with exact file paths and line references. Eliminates vague instructions like "improve error handling" or "add validation."
+
+**Purpose**: Remove all ambiguity about what to do and where to do it.
+
+**Format**:
+```yaml
+action:
+  - step: 1
+    file: src/auth/login.js
+    operation: modify
+    location: "lines 42-58 (validateCredentials function)"
+    description: Add rate limiting check before credential validation
+    details: |
+      Insert a call to rateLimiter.check(req.ip) before the
+      existing validateCredentials() call. If rate limit exceeded,
+      throw RateLimitError with 429 status.
+  - step: 2
+    file: tests/auth/login.test.js
+    operation: add
+    location: "after line 120 (end of 'validation' describe block)"
+    description: Add rate limiting test cases
+```
+
+**Rules**:
+- Each step specifies a single file and operation
+- Operations are: `add`, `modify`, `delete`, `move`, `rename`
+- Line numbers are approximate (may shift) but provide context
+- No step should be "do whatever seems right"
+
+### 3. `acceptance_criteria` — Measurable Completion Conditions
+
+Criteria in Given/When/Then format that define when the task is complete. Each criterion maps to a verifiable outcome.
+
+**Purpose**: Every condition is testable — no room for "it seems to work."
+
+**Format**:
+```yaml
+acceptance_criteria:
+  - id: AC-1
+    given: A user has made 5 login attempts in the last minute
+    when: They attempt a 6th login
+    then: The system returns HTTP 429 with "Rate limit exceeded" message
+  - id: AC-2
+    given: A user has not exceeded the rate limit
+    when: They attempt login with valid credentials
+    then: Login succeeds as before (no regression)
+```
+
+**Rules**:
+- Use GWT format (aligns with SDD and BDD standards)
+- Each AC must be independently verifiable
+- Include regression criteria (existing behavior preserved)
+- Number criteria for traceability (AC-1, AC-2, etc.)
+
+### 4. `verification` — Executable Checks
+
+Commands or checks that objectively verify the task is complete. Uses `grep`, `test`, `ls`, `npm test`, or similar — never subjective judgment.
+
+**Purpose**: Machine-verifiable outcomes eliminate "I think it looks good."
+
+**Format**:
+```yaml
+verification:
+  - command: "grep -n 'rateLimiter.check' src/auth/login.js"
+    expect: "At least one match found"
+  - command: "npm test -- tests/auth/login.test.js"
+    expect: "All tests pass (exit code 0)"
+  - command: "grep -c 'rate.limit' tests/auth/login.test.js"
+    expect: "At least 2 test cases for rate limiting"
+```
+
+**Rules**:
+- Every AC should have at least one verification command
+- Prefer deterministic checks (grep, test, file existence) over semantic evaluation
+- Include test execution as a verification step
+- Failed verification = task is not complete
+
+---
+
+## Complete Task Example
+
+```yaml
+task:
+  id: TASK-042
+  title: Add rate limiting to login endpoint
+  spec_ref: SPEC-042
+
+  read_first:
+    - path: src/auth/login.js
+      reason: Current login implementation
+    - path: src/middleware/rate-limiter.js
+      reason: Existing rate limiter utility
+    - path: tests/auth/login.test.js
+      reason: Test patterns to follow
+    - path: docs/specs/SPEC-042.md
+      reason: Approved specification
+
+  action:
+    - step: 1
+      file: src/auth/login.js
+      operation: modify
+      location: "validateCredentials function (line ~45)"
+      description: Add rate limit check before credential validation
+    - step: 2
+      file: tests/auth/login.test.js
+      operation: add
+      location: "end of validation describe block"
+      description: Add rate limiting test cases
+
+  acceptance_criteria:
+    - id: AC-1
+      given: A user exceeds 5 login attempts per minute
+      when: They attempt another login
+      then: HTTP 429 returned with rate limit message
+    - id: AC-2
+      given: A user is within rate limits
+      when: They login with valid credentials
+      then: Login succeeds normally (no regression)
+
+  verification:
+    - command: "grep -n 'rateLimiter' src/auth/login.js"
+      expect: "Rate limiter imported and used"
+    - command: "npm test -- tests/auth/login.test.js"
+      expect: "All tests pass"
+```
+
+---
+
+## When to Apply
+
+| Scenario | Apply Full Structure? | Notes |
+|----------|----------------------|-------|
+| New feature (SDD) | Yes | All 4 fields required |
+| Bug fix | Yes | `read_first` includes bug report and affected code |
+| Refactoring | Yes | `acceptance_criteria` focus on no-regression |
+| Trivial changes | No | Typos, formatting — skip structure |
+| Hotfixes | Partial | At minimum `read_first` + `verification` |
+
+---
+
+## Integration with SDD
+
+When used with Spec-Driven Development:
+- `read_first` includes the approved spec document
+- `acceptance_criteria` are derived from the spec's AC section
+- `verification` includes spec compliance checks
+- Tasks are created during the Implementation phase
+
+---
+
+## Best Practices
+
+### Do's
+
+- Include regression criteria in every task
+- Use exact file paths (verified by `read_first`)
+- Keep tasks atomic (one logical change)
+- Reference spec IDs when applicable
+
+### Don'ts
+
+- Don't use vague action descriptions ("improve", "enhance", "refactor")
+- Don't skip `verification` — it's the most important field
+- Don't assume file structure — always verify via `read_first`
+- Don't create tasks without reading the target code first
+
+---
+
+## Related Standards
+
+- [Spec-Driven Development](spec-driven-development.md) — Task structure integrates with SDD workflow
+- [Anti-Hallucination Standards](anti-hallucination.md) — `read_first` implements evidence-based analysis
+- [Testing Standards](testing-standards.md) — `verification` aligns with test pyramid
+- [Check-in Standards](checkin-standards.md) — Tasks produce committable units of work
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-03-17 | Initial standard: 4 required fields (read_first, action, acceptance_criteria, verification) |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).