fix(validate): warn on ambiguous task numbering

[alectimison-maker]

Summary

• warn when a built-in spec-driven task ID is duplicated at full depth, including across resolved task files
• warn when a task's leading number disagrees with its enclosing ## N. group
• ignore numeric-looking task text outside numbered groups and leave custom schemas unchanged until they can opt in
• apply the checks across direct, bulk, and deprecated change validation

Motivation

openspec validate currently never inspects task lists. A duplicate ID makes references such as "task 11.1" ambiguous, while a task filed under a different numbered heading is easy to overlook during long-running changes. Both cases pass even under --strict.

Closes #1520.

Design

The analyzer reuses the existing task-line parser and the same task-file resolution used by progress reporting. It receives all resolved task files in stable path order and shares the first location recorded for each complete task ID, so duplicates cannot hide across files.

Numbering is interpreted only while the parser is inside a ## N. group. Entering an unnumbered level-two section clears that context before task parsing and duplicate tracking, so repeated numeric-looking checkbox text under sections such as ## Notes remains accepted.

The validator resolves the change's effective schema and compares its canonical directory with the packaged spec-driven schema before applying this grammar. Project and user overrides, including an override also named spec-driven, remain untouched until schemas have an explicit opt-in contract.

Findings are warnings, so normal validation remains non-blocking and strict validation fails through the existing warning threshold. Duplicate checks compare the complete ID, preserving distinctions such as 3.2.1 and 3.2.2. Group checks compare only the leading integer. Alphabetic suffixes, numbering gaps, unnumbered tasks, unnumbered sections, and files without any ## N. headings remain accepted.

The check runs only when validation provides a project root. Archive and existing library callers retain their previous behavior.

Testing

• pnpm run build
• pnpm run lint
• focused task-progress, validator, direct/deprecated command, and CLI suites (152 passed, 2 skipped)
• integration tree with PR fix(validate): count every level-4 header as a scenario in the loss guard #1521's scenario-loss fix (30 passed)
• active repository scan (19 changes, 0 task-numbering warnings; unrelated existing strict findings keep the aggregate command non-zero)

The full suite was also attempted on Windows. Seven symlink tests fail with EPERM because the current account cannot create symlinks; no other full-suite failures were observed.

Compatibility

No dependencies, public APIs, schemas, or configuration formats change. Custom schemas retain their current validation behavior. Built-in spec-driven task lists only become strict-validation failures when they contain one of the two ambiguous numbering patterns inside numbered groups.

Summary by CodeRabbit

• New Features

  • Added task-numbering validation for change task files.
  • Detects duplicate task IDs and mismatches between task IDs and numbered groups.
  • Supports multiple task files and schema-defined task file locations.

• Bug Fixes

  • Validation now correctly locates task files relative to the project.
  • Direct, bulk, and deprecated validation commands consistently report numbering issues.
  • Task progress includes all resolved task files, with fallback support for tasks.md.

• Tests

  • Added coverage for strict and non-strict behavior, JSON reports, warnings, numbering gaps, suffixes, and unnumbered sections.

[coderabbitai]

📝 Walkthrough

Walkthrough

Validation now checks resolved task files for duplicate IDs and mismatches between task IDs and numbered groups. The check reports warnings and supports direct, bulk, strict, non-strict, custom-schema, and deprecated validation flows.

Changes

Task numbering validation

Layer / File(s)	Summary
Task numbering parser src/core/validation/task-numbering.ts, test/core/task-numbering.test.ts	Adds detection for duplicate full-depth task IDs and leading-number mismatches. Tests cover gaps, suffixes, nested IDs, CRLF input, and unnumbered sections.
Validator task-file integration src/utils/task-progress.ts, src/core/validation/validator.ts, src/commands/validate.ts, src/commands/change.ts	Resolves tracked task files with a tasks.md fallback. Validation reads those files and adds numbering warnings. CLI callers pass projectRoot.
CLI and end-to-end coverage test/cli-e2e/validate-task-numbering.test.ts	Covers strict and non-strict validation, bulk validation, nested globs, custom schemas, JSON reports, and the deprecated command.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1280: Directly overlaps the project-root plumbing, task-file resolution, and task-numbering validation changes.
• Fission-AI/OpenSpec#1486: Also modifies task-file resolution and getTaskProgressForChange.
• Fission-AI/OpenSpec#1473: Also updates validateChangeDeltaSpecs and passes project/schema-root context.

Suggested reviewers: clay-good, tabishb, alfred-openspec

Sequence Diagram(s)

sequenceDiagram
  participant ValidateCommand
  participant Validator
  participant TaskFileResolver
  participant TaskFiles
  ValidateCommand->>Validator: validate change with projectRoot
  Validator->>TaskFileResolver: resolveTaskFilesForChange
  TaskFileResolver->>TaskFiles: return tracked files or tasks.md
  Validator->>TaskFiles: read task content
  Validator->>Validator: append numbering warnings

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The implementation detects duplicate full-depth task IDs and group mismatches, including strict-mode behavior and schema-aware task-file resolution required by issue #1520.
Out of Scope Changes check	✅ Passed	The code and tests remain focused on task-numbering validation, project-root wiring, schema-aware task-file resolution, and related validation paths.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the validation change that warns about ambiguous task numbering.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/validation/task-numbering.ts`:
- Around line 30-52: Update the task-processing loop before parseTaskLines and
duplicate tracking to return when currentGroup is undefined, so numeric-looking
task IDs in unnumbered sections are ignored. Preserve validation for numbered
groups, and add a mixed-file regression test covering a numbered group followed
by an unnumbered section with repeated numeric task text while keeping
unnumbered tasks and sections accepted.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: b8c4e38f-52c2-4251-bfa8-37bc427d4082

📥 Commits

Reviewing files that changed from the base of the PR and between d578896 and df44f23.

📒 Files selected for processing (7)

• src/commands/change.ts
• src/commands/validate.ts
• src/core/validation/task-numbering.ts
• src/core/validation/validator.ts
• src/utils/task-progress.ts
• test/cli-e2e/validate-task-numbering.test.ts
• test/core/task-numbering.test.ts

[alfred-openspec]

Thanks, this is close, but exact head df44f23 still creates false positives: after ## Notes, two 9.1 checkbox lines are reported as a duplicate and make --strict fail, even though tasks outside numbered groups are documented as ignored. Please fix that mixed-section case, detect duplicate IDs across all resolved task files instead of per file, and avoid applying the built-in numbered-task grammar to arbitrary custom schemas until schemas can opt in.

[alectimison-maker]

Addressed the three review points in 668eaae7:

• task parsing and duplicate tracking now stop outside numbered ## N. groups, with a regression covering repeated 9.1 checkbox text after ## Notes
• duplicate tracking now shares the first task location across all resolved files and reports the original file and line
• the grammar now runs only when the effective schema resolves to the packaged spec-driven directory; custom schemas and same-name overrides are left unchanged

Validation completed with build, lint, 152 focused/related tests, and a combined tree with #1521 (30 tests). The full Windows suite still has the seven existing symlink-permission failures and no additional failures.

[alfred-openspec]

The follow-up closes the three review gaps: checks stop outside numbered groups, duplicate IDs are tracked across resolved files with stable paths, and only the packaged spec-driven schema gets this grammar. Fresh install/build/lint, 130 focused validation/task tests, and the hosted matrix pass. Approved at 668eaae.

[clay-good]

waiting on github to resolve major outage -> https://www.githubstatus.com/