eslint-plugin-traceability 1.7.0 → 1.8.0

package/docs/decisions/010-implements-annotation-for-multi-story-requirements.proposed.md

@@ -0,0 +1,184 @@
+---
+status: "proposed"
+date: 2025-12-03
+decision-makers: [Development Team]
+consulted: [dry-aged-deps codebase patterns, JSDoc conventions]
+informed: [Plugin Users, Project Contributors]
+---
+
+# Introduce @implements Annotation for Multi-Story Requirements
+
+## Context and Problem Statement
+
+The current traceability annotation system uses `@story` to reference a story file and `@req` to reference requirement IDs within that story. This works well for functions that implement a single story, but breaks down for integration functions that combine functionality from multiple stories. For example, `apply-filters.js` calls both `filterByAge()` (from story 003) and `filterBySecurity()` (from story 004), needing to reference requirements from both stories.
+
+The current `valid-req-reference` rule only validates `@req` annotations against the **first** `@story` annotation, causing false-positive linting errors when a function legitimately implements requirements from multiple stories. This blocks code quality validation and forces developers to either suppress linting or remove valid traceability annotations.
+
+## Decision Drivers
+
+- Integration functions naturally combine functionality from multiple stories
+- Current single-story validation prevents legitimate multi-story traceability
+- Need backwards compatibility with existing `@story` + `@req` annotations
+- Requirement IDs should be unique only within their story file (scoping)
+- Clear, explicit mapping between requirements and their source stories
+- Minimal disruption to existing codebases
+- Natural semantics that match developer mental models
+
+## Considered Options
+
+1. Multiple `@story` support - Allow multiple `@story` tags, validate `@req` against any
+2. Transitive references - Only reference primary story, infer requirements from called functions
+3. Integration story pattern - Create integration story files that duplicate requirements
+4. Flatten requirements - Remove `@req` validation entirely
+5. Namespaced requirements - Use aliases like `@story ... as alias` / `@req alias:REQ-ID`
+6. Inline story reference - `@req REQ-ID from path/to/story.md`
+7. New `@implements` annotation - `@implements story-path REQ-ID1 REQ-ID2 ...`
+
+## Decision Outcome
+
+Chosen option: "New `@implements` annotation", because it provides clear, explicit mapping between requirements and stories, enables requirement ID scoping, maintains full backwards compatibility with existing annotations, and uses semantically meaningful terminology.
+
+### Consequences
+
+- Good, because `@implements` clearly expresses "this code implements these requirements from this story"
+- Good, because requirement IDs only need to be unique within their story file (scoping)
+- Good, because all requirements from one story can be listed on a single line
+- Good, because completely backwards compatible - existing `@story` + `@req` code continues working
+- Good, because no ambiguity in multi-story scenarios
+- Good, because reduced annotation overhead compared to separate `@story` tags
+- Good, because story paths appear once per story (grouped requirements)
+- Neutral, because introduces a new annotation tag (but semantically clear)
+- Neutral, because both annotation styles can coexist during migration
+- Bad, because requires plugin enhancement to support new annotation
+- Bad, because requires documentation updates and user communication
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- Plugin parses `@implements story-path REQ-ID1 REQ-ID2 ...` format correctly
+- Each requirement ID is validated against its specified story file
+- Existing `@story` + `@req` annotations continue to work unchanged
+- Mixed usage (both styles in same codebase) works correctly
+- Error messages clearly indicate which story was checked for each requirement
+- Tests cover single-story, multi-story, and mixed annotation patterns
+- Documentation includes migration guide and examples
+
+## Pros and Cons of the Options
+
+### New `@implements` annotation
+
+Introduces a new annotation tag that combines story reference with requirement IDs.
+
+- Good, because semantically clear ("implements requirements from story")
+- Good, because explicit story-to-requirement mapping (no inference needed)
+- Good, because requirements grouped by story (readable, organized)
+- Good, because enables requirement ID scoping to story files
+- Good, because backwards compatible (existing code unchanged)
+- Good, because story paths not duplicated per requirement
+- Good, because natural for both single-story and multi-story cases
+- Neutral, because new annotation to learn (but intuitive naming)
+- Bad, because requires plugin changes to support new tag
+- Bad, because migration effort for existing codebases (though optional)
+
+**Example usage:**
+
+```javascript
+/**
+ * Apply age and security filters to rows.
+ * @implements prompts/003.0-DEV-IDENTIFY-OUTDATED.md REQ-AGE-THRESHOLD REQ-OUTPUT
+ * @implements prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-AUDIT-CHECK REQ-SAFE-ONLY
+ */
+export async function applyFilters(rows, options) {
+```
+
+**Legacy format (still supported):**
+
+```javascript
+/**
+ * @story docs/stories/003.0-DEV-EXAMPLE.story.md
+ * @req REQ-FUNCTION-VALIDATION
+ */
+export function legacyFunction() {
+```
+
+### Multiple `@story` support
+
+Allow multiple `@story` annotations, validate `@req` against any referenced story.
+
+- Good, because extends current annotation model incrementally
+- Good, because explicit story listing provides context
+- Neutral, because maintains separation of stories and requirements
+- Bad, because unclear which `@req` maps to which `@story`
+- Bad, because doesn't enable requirement ID scoping
+- Bad, because story paths repeated if requirements intermixed
+
+### Namespaced requirements
+
+Use story aliases like `@story path as alias` / `@req alias:REQ-ID`.
+
+- Good, because clear story-to-requirement mapping via namespace
+- Good, because story paths appear once
+- Neutral, because requires learning namespace syntax
+- Bad, because alias management adds cognitive overhead
+- Bad, because unconventional for JSDoc
+
+### Inline story reference
+
+Format: `@req REQ-ID from path/to/story.md`
+
+- Good, because very explicit per-requirement
+- Good, because no aliasing needed
+- Bad, because verbose (story path repeated per requirement)
+- Bad, because harder to refactor story paths
+- Bad, because doesn't enable requirement ID scoping
+
+### Transitive references
+
+Infer requirements from called functions automatically.
+
+- Good, because minimal annotation overhead
+- Bad, because requires complex static analysis
+- Bad, because fragile (refactoring breaks validation)
+- Bad, because implicit (not backwards compatible)
+
+### Integration story pattern
+
+Create integration story files that duplicate requirements.
+
+- Good, because single `@story` still works
+- Bad, because duplicates requirements across stories
+- Bad, because high maintenance overhead
+- Bad, because doesn't scale
+
+## More Information
+
+This decision addresses the limitation discovered when fixing systematic linting suppression in dry-aged-deps, where 80% of files had `eslint-disable traceability/*` due to multi-story integration functions.
+
+The `@implements` annotation name was chosen because:
+
+- It's semantically accurate - code implements requirements
+- It's familiar from interface implementation in many languages
+- It clearly conveys purpose without abbreviation
+- It differentiates from `@story` (context) vs implementation scope
+
+**Migration strategy:**
+
+1. Plugin supports both `@story`+`@req` and `@implements` simultaneously
+2. Existing code continues working without changes
+3. New code can use either format based on preference
+4. Multi-story code should migrate to `@implements` to fix validation
+5. Single-story code can optionally migrate for consistency
+
+**Validation behavior:**
+
+- `@implements story-path REQ-1 REQ-2`: Validate REQ-1 and REQ-2 exist in story-path
+- `@story path` + `@req REQ-1`: Validate REQ-1 exists in path (legacy)
+- Mixed: Both formats can coexist, validated independently
+
+This decision should be implemented in eslint-plugin-traceability story 011.0-DEV-MULTI-STORY-SUPPORT or similar.
+
+Related resources:
+
+- eslint-plugin-traceability story 010.0-DEV-DEEP-VALIDATION (requirement validation)
+- eslint-plugin-traceability story 003.0-DEV-FUNCTION-ANNOTATIONS (current @req validation)

package/docs/decisions/adr-0001-console-usage-for-cli-guards.md

@@ -0,0 +1,190 @@
+# ADR-0001: Console Usage for CLI Guards, Helpers, and Plugin Bootstrap
+
+## Status
+
+Accepted
+
+## Date
+
+2025-11-22
+
+## Context
+
+This project includes:
+
+- Command-line interface (CLI) entry points
+- Helper scripts invoked in CI (e.g., validation, formatting, pre-publish checks)
+- Plugin/bootstrap code that wires rules, schemas, and configuration into host environments
+
+These components sometimes need to communicate directly with users or CI logs. At the same time, the core rule logic and runtime validation paths must remain deterministic, testable, and free of incidental logging side effects.
+
+Unrestricted use of `console.*` makes it harder to:
+
+- Keep CI logs focused and readable
+- Distinguish genuine errors from noisy diagnostics
+- Treat the library/rules as embeddable components in other tools
+- Assert on behavior without having to mock or suppress console output
+- Maintain a clear and intentional debugging story
+
+We therefore need a clear policy on where and how console logging is allowed.
+
+## Decision
+
+### 1. Allowed: `console.error` and `console.warn` in CLI/CI/helper/bootstrapping layers
+
+It is acceptable and encouraged to use `console.error` and `console.warn` **only** in the following layers:
+
+1. **CLI entry points / top-level commands**
+   - Example: `bin/*`, `cli.ts`, or similar top-level command handlers.
+   - Purpose:
+     - Report user-facing failures (e.g., invalid flags, failed file operations, configuration errors).
+     - Surface deprecation notices that must be visible to users.
+     - Provide actionable messages when the process will exit with a failing code.
+
+2. **CI/helper scripts**
+   - Example: scripts run in CI pipelines, pre-commit, or release workflows.
+   - Purpose:
+     - Report errors and warnings that should be visible in CI logs.
+     - Indicate misconfiguration, missing environment variables, or unexpected states that require human attention.
+
+3. **Plugin bootstrap / initialization code**
+   - Example: modules that register rules, schemas, or integrations with other tools.
+   - Purpose:
+     - Report misconfiguration, incompatibility, or missing peer dependencies.
+     - Warn about deprecated configuration patterns or features at startup.
+
+Within these layers:
+
+- Prefer `console.error` for conditions that are expected to cause failure or require immediate action.
+- Prefer `console.warn` for non-fatal, but noteworthy, conditions.
+- Ensure messages are:
+  - Concise and actionable.
+  - Clearly identify the originating tool/plugin where possible.
+  - Avoid leaking sensitive information (tokens, file contents, etc.).
+
+### 2. Disallowed by default: Incidental logging in core rule logic and runtime validation
+
+The **core rule logic** and **runtime validation paths** must **not** emit incidental console output:
+
+- **Disallowed by default (unless gated, see §3):**
+  - `console.debug`
+  - `console.info`
+  - `console.log`
+  - `console.warn`
+  - `console.error`
+
+These paths include, but are not limited to:
+
+- Rule implementations and their helpers.
+- Core validation pipelines and evaluators.
+- Schema or configuration validation logic that runs during normal tool operation.
+- Any code intended to be reusable as a library, imported by other tools, or executed repeatedly as part of analysis passes.
+
+Rationale:
+
+- These components are expected to be:
+  - Pure (or side-effect minimal) in normal execution.
+  - Suitable for use in environments where console output is tightly controlled (CI, IDE integrations, language servers, etc.).
+  - Testable without requiring suppression or mocking of the console.
+
+If a rule or validation component must report an exceptional condition, it should do so by:
+
+- Returning structured error objects, diagnostics, or result codes to the caller.
+- Throwing well-typed errors (where appropriate) that are handled and surfaced at higher layers (e.g., CLI, plugin bootstrap), which then decide whether to log via `console.error`/`console.warn`.
+
+### 3. Optional: Debug logging behind an explicit, documented debug flag
+
+Debug logging inside rule logic or validation paths is allowed **only** when all of the following conditions are met:
+
+1. **Explicit opt-in flag**
+   - There is a documented configuration option or environment variable (e.g., `MY_TOOL_DEBUG=true`, `--debug-rules`) that clearly indicates the user is opting into verbose debug output.
+
+2. **Single, centralized control**
+   - Debug logging behavior is routed through a small, centralized abstraction (e.g., `debugLogger.debug(...)`) that:
+     - Checks the flag.
+     - Decides whether to call `console.debug`/`console.info` (or similar).
+   - Rule and validation code must not call `console.*` directly; they call the abstraction instead.
+
+3. **Documented behavior**
+   - The debug option is documented in:
+     - User-facing CLI help (e.g., `--help` output) and/or
+     - Project documentation / README.
+   - The documentation explains:
+     - How to enable it.
+     - What kind of additional output to expect.
+     - That it is intended for development/troubleshooting, not regular operation.
+
+4. **No change to functional semantics**
+   - Enabling or disabling debug logging must not alter:
+     - Rule evaluation semantics.
+     - Validation results.
+     - Exit codes.
+     - Data returned from public APIs.
+   - Only side-effect should be additional console output.
+
+If these requirements cannot be satisfied, then debug logging must **not** be added to core rule or validation logic.
+
+### 4. Current state of the codebase
+
+As of this ADR:
+
+- The **current codebase has no debug logging** (`console.debug`/`console.info`/`console.log`) inside:
+  - Rule implementations.
+  - Core validation logic.
+  - Normal runtime evaluation paths.
+
+Existing console usage is limited to acceptable locations (e.g., CLI helpers, CI scripts, bootstrap code), or will be refactored to conform to this ADR as needed.
+
+### 5. Requirements for future changes
+
+Any future additions or modifications must follow these rules:
+
+1. **New CLI or CI helper behavior**
+   - May use `console.error` and `console.warn` to report user-/operator-facing issues.
+   - Must keep messages focused and actionable.
+
+2. **New plugin/bootstrap code**
+   - May use `console.error` and `console.warn` to report misconfiguration, deprecation, or failure to initialize.
+   - Must not emit continuous noisy logs during normal operation.
+
+3. **New rule or validation logic**
+   - Must **not** introduce direct `console.*` calls.
+   - Any need for surfaced messages must be handled via return values, errors, or diagnostics passed upward.
+
+4. **New debug-logging needs**
+   - Must implement or reuse a centrally controlled debug abstraction, gated behind a documented flag (see §3).
+   - Must keep debug logging off by default.
+   - Must ensure tests remain stable regardless of debug flag state (except tests explicitly verifying debug behavior).
+
+5. **Code review expectations**
+   - Any use of `console.*` in PRs must be reviewed against this ADR.
+   - Reviewers should:
+     - Confirm that console usage is in an allowed layer (CLI/CI/helper/bootstrap) or behind a proper debug abstraction.
+     - Request refactoring if console usage appears in rule logic or runtime validation not gated as per §3.
+
+## Consequences
+
+- **Positive**
+  - Clear separation between user-visible errors/warnings and internal debugging.
+  - Cleaner CI logs and more predictable tool integration behavior.
+  - Easier testing and reasoning about core logic, without noise from incidental console output.
+  - A consistent, documented approach to opt-in debug logging.
+
+- **Negative / Trade-offs**
+  - Slightly more effort to add debug logging, due to the need for a central abstraction and debug flag.
+  - Contributors must understand and respect the separation between CLI/bootstrapping and core logic.
+
+## Alternatives Considered
+
+- **Allow unrestricted `console.*` usage everywhere**
+  - Rejected: leads to noisy logs, poor embeddability, and harder testing.
+
+- **Disallow `console.*` entirely**
+  - Rejected: unhelpful for CLI/CI/bootstrapping components, where direct console output is appropriate and expected.
+
+- **Use a third-party logging framework everywhere**
+  - Rejected for now: adds dependency and complexity; current needs are satisfied by disciplined use of console and an optional light abstraction for debug logging.
+
+## Notes
+
+This ADR governs only JavaScript/TypeScript-style `console.*` usage. Other languages or runtimes used in this project should follow analogous principles (i.e., restrict incidental stdout/stderr usage in core logic; allow explicit logging in top-level tooling and bootstrap code; gate debug logging behind an explicit debug configuration).

package/docs/decisions/adr-accept-dev-dep-risk-glob.md

@@ -0,0 +1,40 @@
+# ADR: Accept residual risk for glob/npm high-severity transitive dev dependency
+
+Status: accepted
+
+## Context
+
+The CI dev dependency audit (ci/npm-audit.json) reports a high-severity advisory for `glob` and `npm` transitively required by `@semantic-release/npm`. Fixes are available upstream but require coordination and may not be immediately possible without an update to semantic-release or npm bundled tooling.
+
+## Decision
+
+We accept the residual risk in development dependencies for the current release while tracking the issue in a scheduled reassessment. This ADR documents the rationale and mitigations.
+
+## Consequences and mitigations
+
+- Owner: DevOps/Release Engineer (team)
+- Reassessment: Weekly during dependency-health scheduled workflow runs
+- Mitigations:
+  - Do not ship production code that depends on vulnerable dev-time tooling
+  - CI pipeline uses `npm ci` and runs production `npm audit` which must pass for releases
+  - `ci-safety-deps.js` now produces a best-effort `dry-aged-deps`-style JSON report even when `dry-aged-deps` is unavailable, falling back to an empty `packages` list while still emitting a syntactically valid report for review
+  - `ci-audit.js` runs `npm audit` in JSON mode and always writes the full result to `ci/npm-audit.json` without failing the build, ensuring advisory visibility without blocking CI
+  - The JSON artifacts generated by `ci-safety-deps.js` and `ci-audit.js` (including `ci/npm-audit.json`) are ignored in `.gitignore` and are only retained as CI artifacts for security review and dependency-health analysis, not committed to the repository
+  - The residual `glob`/`npm` dev dependency risks are covered by these updated CI scripts, which ensure visibility into advisories, plus strict production `npm audit` gates that must pass before a release
+  - Develop a plan to upgrade `@semantic-release/npm` to a version that avoids bundling vulnerable `glob`/`npm` when safe
+
+## References
+
+- Vulnerability details: see ci/npm-audit.json stored in CI artifacts
+
+Created autonomously by voder.ai
+
+## Current Dependency Health (2025-12-03)
+
+`npm audit --omit=dev --audit-level=high` currently reports 0 high-severity (or higher) vulnerabilities for production dependencies, and `npm run deps:maturity -- --format=json` reports `totalOutdated: 0` and `safeUpdates: 0`, indicating that there are no dry-aged-safe upgrade candidates at this time for the dev-time semantic-release toolchain.
+
+## Using dry-aged-deps in this project
+
+Contributors should use `npm run deps:maturity -- --format=json` as the canonical way to invoke dry-aged-deps, both locally and in CI. This command writes its JSON report to stdout. In CI, `npm run safety:deps` additionally persists the latest report to `ci/dry-aged-deps.json` for later inspection as a build artifact.
+
+Run dry-aged-deps before proposing dependency bumps, during scheduled dependency-health reviews, and whenever investigating security or maintenance issues related to packages. Only dependency versions that dry-aged-deps marks as safe and that have been published for at least 7 days should be considered for upgrades, to reduce the risk of adopting unstable or compromised releases.

package/docs/decisions/adr-commit-branch-tests.md

@@ -0,0 +1,54 @@
+# ADR: Add CI lint-plugin check and targeted branch tests
+
+Date: 2025-11-20
+
+Status: Accepted
+
+Context
+
+- CI currently runs a large, monolithic pipeline for every push/PR. This results in long feedback cycles and increased compute cost.
+- Inconsistent commit messages and branch names reduce traceability and can cause problems for automated tooling (release automation, changelogs).
+- Some tests are expensive and only relevant to certain branches (e.g., release or platform-specific branches), while most feature work only needs a smaller, targeted test subset.
+- Contributors and maintainers want faster, reliable feedback on changes without sacrificing quality gates.
+
+Decision
+
+- Add a CI check that runs a lint-plugin against commits/PRs to enforce commit message format and branch naming rules. The lint-plugin will be integrated into the PR pipeline and fail the build on violations.
+- Implement targeted branch tests:
+  - For feature and routine PR branches: run a focused subset of tests (unit tests, fast integration tests, and any tests related to changed files) to provide quick feedback.
+  - For release, main, or explicitly labeled branches (e.g., "release/_", "main", "hotfix/_"): run the full test suite.
+  - Allow explicit overrides (e.g., PR label or commit tag) to trigger full runs when desired.
+- Document the rules that determine which tests run and how to opt into full runs.
+
+Rationale
+
+- Lint-plugin for commits/branches enforces consistency and prevents human errors that complicate downstream automation (releases, changelogs, CI heuristics).
+- Targeted tests reduce median CI turnaround time for everyday contributions, improving developer productivity and reducing wasted compute.
+- Running the full suite only on critical branches preserves confidence for releases while keeping developer feedback loops short.
+- Explicit override mechanism balances automation with developer control when a full run is necessary.
+
+Consequences
+
+- Positive:
+  - Faster PR feedback for most contributions.
+  - Improved commit/branch hygiene and stronger automation compatibility.
+  - Lower CI costs for routine development.
+  - Full confidence preserved for release and critical branches.
+- Negative / Trade-offs:
+  - Additional maintenance: rules for mapping changes to targeted tests must be maintained and updated.
+  - Risk of missed regressions if test selection logic is incorrect or incomplete. Mitigated by defaulting to full runs on protected branches and providing an easy override.
+  - Contributors will need to conform to enforced commit/branch rules; documentation and examples will be required.
+
+Alternatives considered
+
+- Always run full CI on every PR: simple but slow and costly.
+- No lint-plugin enforcement: lower friction but greater chance of inconsistent metadata and automation failures.
+- Run only full suite for releases and minimal checks for everything else without targeted selection: simpler but less efficient in catching relevant regressions early.
+
+Implementation notes (high-level)
+
+- Add lint-plugin step to CI config; fail on violations and provide clear error messages with remediation.
+- Implement test-selection logic using file-change analysis and branch name rules; fall back to a safe default (full run for protected branches).
+- Provide CONTRIBUTING and CI docs detailing commit message format, branch naming conventions, and how to force full CI runs.
+
+This ADR is intended to be revisited after observing CI performance and quality metrics for one quarter post-rollout.

package/docs/decisions/adr-maintenance-cli-interface.md

@@ -0,0 +1,140 @@
+# ADR: Maintenance CLI Interface for Traceability Annotations
+
+## Status
+
+Accepted
+
+## Date
+
+2025-11-23
+
+## Context
+
+Story `docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md` introduces maintenance tools that help keep `@story` and `@req` annotations accurate as story files are moved, renamed, or removed.
+
+We already have programmatic utilities under `src/maintenance/`:
+
+- `detectStaleAnnotations(codebasePath)`
+- `updateAnnotationReferences(codebasePath, oldPath, newPath)`
+- `batchUpdateAnnotations(codebasePath, mappings)`
+- `verifyAnnotations(codebasePath)`
+- `generateMaintenanceReport(codebasePath)`
+
+These are well-tested but only accessible from code. The story's acceptance criteria and implementation notes explicitly call out **CLI tools** and a **clear user experience**:
+
+- Detect and update annotation references when story files are moved or renamed.
+- Provide clear feedback about what changed.
+- Handle edge cases (e.g., permission issues) gracefully.
+
+Without a small, well-defined CLI layer, developers must write ad-hoc scripts to use the maintenance API, which undermines the goal of "helper tools" and makes it harder to adopt maintenance workflows consistently across projects.
+
+## Decision
+
+We will introduce a small Node CLI, published with the plugin, that wraps the existing maintenance utilities with a minimal, safe interface.
+
+### 1. CLI entrypoint
+
+- **Binary name**: `traceability-maint`
+- **Implementation**: TypeScript module `src/maintenance/cli.ts` compiled to `lib/src/maintenance/cli.js`.
+- **Package wiring**:
+  - Add a `bin` entry to `package.json` pointing `traceability-maint` to `lib/src/maintenance/cli.js`.
+  - Keep `files: ["lib", "README.md", "LICENSE"]` so the compiled CLI is included automatically.
+- **Shebang**: `#!/usr/bin/env node` at the top of the compiled script so it is directly executable.
+
+The CLI module will export a `runMaintenanceCli(argv: string[]): number` function for tests, and execute it when invoked as the main module.
+
+### 2. Supported commands (initial scope)
+
+The initial CLI will support the following subcommands:
+
+1. `detect`
+   - Usage: `traceability-maint detect [--root <dir>] [--json]`
+   - Behavior:
+     - Uses `detectStaleAnnotations(root)` to find stale `@story` references.
+     - Prints either:
+       - Plain text: one stale story path per line plus a short summary, or
+       - JSON: `{ "root": "...", "stale": ["..."] }` when `--json` is provided.
+     - **Exit codes**:
+       - `0` when no stale annotations are found.
+       - `1` when one or more stale annotations are found.
+       - `2` for invalid arguments or unexpected errors.
+
+2. `verify`
+   - Usage: `traceability-maint verify [--root <dir>]`
+   - Behavior:
+     - Uses `verifyAnnotations(root)` (and/or `detectStaleAnnotations`) to check overall health.
+     - Prints a short human-readable summary indicating whether annotations are valid.
+     - **Exit codes**:
+       - `0` when all annotations under `root` are valid.
+       - `1` when stale annotations exist.
+       - `2` for invalid arguments or unexpected errors.
+
+3. `report`
+   - Usage: `traceability-maint report [--root <dir>] [--format text|json]`
+   - Behavior (initially):
+     - Uses maintenance detection utilities to produce a **human-readable report** of stale annotations.
+     - At a minimum, lists stale story paths and the workspace root.
+     - In follow-up work (same story), the report will be enhanced to include **file and line** locations for each stale annotation.
+   - **Exit codes**:
+     - `0` on successful report generation (even if stale annotations exist).
+     - `2` for invalid arguments or unexpected errors.
+
+4. `update`
+   - Usage: `traceability-maint update --root <dir> --from <oldPath> --to <newPath> [--dry-run] [--json]`
+   - Behavior (initially):
+     - Uses `updateAnnotationReferences(root, oldPath, newPath)` to update `@story` references.
+     - Prints how many annotations were updated.
+     - When `--dry-run` is passed, it will **plan** changes and report what would be updated without modifying files (implemented via small helpers in `src/maintenance/update.ts`).
+   - **Exit codes**:
+     - `0` when the operation completes successfully.
+     - `2` for invalid arguments or unexpected errors.
+
+The CLI will also support `--help` / `-h` or no subcommand to print usage.
+
+### 3. Safety and error handling
+
+- The CLI will:
+  - Validate arguments and print clear error messages for misuse (e.g., missing `--from` / `--to`).
+  - Catch unexpected errors at the top level, log a concise diagnostic to stderr, and exit with a non-zero code.
+  - Treat normal findings (e.g., stale annotations found) as **controlled outcomes** with predictable exit codes, not unhandled exceptions.
+- Core maintenance utilities (`src/maintenance/*.ts`) will remain free of `console.*` calls; only the CLI layer will write to stdout/stderr, per ADR-0001.
+
+### 4. Defaults and configuration
+
+- `--root` defaults to the current working directory (`.`) when omitted.
+- All paths are treated as workspace-relative to the process CWD, consistent with existing maintenance helpers.
+- No additional configuration files are introduced for the CLI in this story; future enhancements (e.g., a JSON config) would be separate stories.
+
+### 5. Testing strategy
+
+- Add dedicated Jest tests under `tests/maintenance/cli.test.ts` that:
+  - Import and call `runMaintenanceCli([...])` directly (no need to spawn a new Node process).
+  - Use temporary directories under `os.tmpdir()` with cleanup in `afterAll`/`finally` blocks.
+  - Assert on:
+    - Exit codes for `detect`, `verify`, `report`, and `update`.
+    - Key substrings in console output (captured via Jest spies on `console.log` / `console.error`).
+  - Include `@story` / `@req` annotations referencing `docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md`.
+
+## Consequences
+
+### Positive
+
+- Developers gain a simple, documented CLI for common maintenance operations, without needing to write custom scripts.
+- The CLI design keeps safety and reversibility in mind (dry-run support, clear exit codes).
+- The CLI remains thin: it delegates all real work to the existing, tested maintenance utilities.
+- Tests target the CLI behavior directly, while keeping it easy to evolve.
+
+### Negative / Trade-offs
+
+- Adding a CLI introduces a small surface area of user-facing behavior that must be maintained and versioned.
+- The initial `report` and `update --dry-run` implementations will be relatively simple; richer reporting (file/line details, machine-readable change logs) will require incremental enhancements.
+
+## Future Work (within Story 009.0)
+
+The following improvements are planned as part of fully satisfying Story 009.0 but are not required to introduce the CLI itself:
+
+- Enhance maintenance reporting to include **file and line** locations for each stale annotation, both programmatically and in the CLI `report` output.
+- Improve error handling for edge cases such as permission-denied directories by making traversal utilities more resilient and surfacing issues via the CLI in a controlled way.
+- Extend documentation in `user-docs/` and `README.md` to cover the maintenance CLI with examples and safety notes (dry-run, backups).
+
+These changes will be implemented incrementally with dedicated tests and, where appropriate, additional ADRs or updates to this document.