feat: relax SHALL/MUST validation for international documentation (#243) #284
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ssion-AI#243) Changed SHALL/MUST keyword requirement from ERROR to WARNING level, enabling non-English documentation while maintaining best practice recommendations for English specs. Changes: - Updated src/core/validation/validator.ts: Changed validation level from ERROR to WARNING for ADDED and MODIFIED requirements without SHALL/MUST - Updated error messages to be guidance-focused (RFC 2119 best practice) - Added 3 comprehensive test cases: 1. Requirements without SHALL/MUST pass with WARNING in normal mode 2. --strict mode still enforces the check (treats warnings as errors) 3. Non-English requirements (Chinese example) validate successfully Impact: - International teams can now write specs in their native language - English specs still see helpful RFC 2119 recommendations - Teams wanting strict enforcement can use --strict mode - Zero breaking changes for existing workflows All 3 new tests pass. 267/268 tests passing overall (1 pre-existing Windows-specific failure unrelated to changes). Fixes Fission-AI#243 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Contributor
|
Warning Rate limit exceeded@yha9806 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 22 minutes and 5 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ⛔ Files ignored due to path filters (264)
📒 Files selected for processing (2)
WalkthroughValidation for requirement texts lacking SHALL/MUST is downgraded from ERROR to WARNING (preserved as error in --strict). Tests and docs added/updated to cover non-strict, strict, and non-English scenarios; package install scripts adjusted. Changes
Sequence Diagram(s)sequenceDiagram
participant CLI as CLI (--strict?)
participant Validator as Validator
participant Req as Requirement Text
participant Emitter as IssueEmitter
Note over CLI,Validator: User runs "openspec validate" (with or without --strict)
CLI->>Validator: validate(repo, strictFlag)
Validator->>Req: analyze(requirement)
alt requirement text contains SHALL/MUST
Req-->>Validator: contains_keyword
Validator->>Emitter: no_issue()
Emitter-->>CLI: pass (exit 0)
else missing SHALL/MUST
Req-->>Validator: missing_keyword
Validator->>Emitter: emit WARNING "Recommend RFC 2119 (SHALL/MUST)"
Emitter-->>CLI: report WARNING
alt strictFlag == true
Emitter->>CLI: escalate warnings to ERROR -> exit 1
else
CLI-->>User: pass with warnings -> exit 0
end
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
openspec/changes/relax-shall-must-validation/tasks.md (1)
1-18: Update task completion status.All checkboxes are unchecked, but the PR summary and code changes indicate the implementation and testing are complete. Please mark completed tasks with
- [x]to accurately reflect progress.Based on learnings.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
openspec/changes/relax-shall-must-validation/proposal.md(1 hunks)openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.md(1 hunks)openspec/changes/relax-shall-must-validation/tasks.md(1 hunks)src/core/validation/validator.ts(2 hunks)test/core/validation.test.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (5)
openspec/changes/*/{proposal.md,tasks.md,design.md,specs/**/spec.md}
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold each change with proposal.md, tasks.md, optional design.md, and delta spec files under openspec/changes//specs//spec.md
Files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.md
openspec/changes/*/**
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Choose a unique kebab-case, verb-led change-id (add-, update-, remove-, refactor-) for openspec/changes//
Files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.md
openspec/{specs/**/spec.md,changes/*/specs/**/spec.md}
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/{specs/**/spec.md,changes/*/specs/**/spec.md}: Write requirements using SHALL/MUST for normative wording
Every requirement must include at least one scenario, formatted exactly with a '#### Scenario: ' header (no bullets or bold)
Under ADDED, introduce new capabilities as standalone requirements rather than altering existing ones
Files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.md
openspec/changes/*/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/*/specs/**/spec.md: Use ADDED, MODIFIED, REMOVED, or RENAMED sections when authoring deltas; place changed requirements under the correct operation header
For MODIFIED requirements, paste the full existing requirement block (header through scenarios) and ensure the header text matches exactly (whitespace-insensitive)
Use RENAMED when only the requirement name changes; if behavior changes too, use RENAMED plus MODIFIED referencing the new name
Files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Track implementation steps in tasks.md and mark each completed item with '- [x]' once finished
Files:
openspec/changes/relax-shall-must-validation/tasks.md
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Write requirements using SHALL/MUST for normative wording
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Validate proposals and specs with 'openspec validate <item> --strict' and fix all issues before sharing
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Write requirements using SHALL/MUST for normative wording
Applied to files:
src/core/validation/validator.tsopenspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.mdtest/core/validation.test.ts
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Under ADDED, introduce new capabilities as standalone requirements rather than altering existing ones
Applied to files:
src/core/validation/validator.tsopenspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.mdtest/core/validation.test.ts
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/specs/**/spec.md : For MODIFIED requirements, paste the full existing requirement block (header through scenarios) and ensure the header text matches exactly (whitespace-insensitive)
Applied to files:
src/core/validation/validator.tsopenspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/tasks.mdtest/core/validation.test.ts
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Every requirement must include at least one scenario, formatted exactly with a '#### Scenario: <name>' header (no bullets or bold)
Applied to files:
src/core/validation/validator.tsopenspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/tasks.mdtest/core/validation.test.ts
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/specs/**/spec.md : Use ADDED, MODIFIED, REMOVED, or RENAMED sections when authoring deltas; place changed requirements under the correct operation header
Applied to files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/specs/**/spec.md : Use RENAMED when only the requirement name changes; if behavior changes too, use RENAMED plus MODIFIED referencing the new name
Applied to files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Validate proposals and specs with 'openspec validate <item> --strict' and fix all issues before sharing
Applied to files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.mdopenspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.mdtest/core/validation.test.ts
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/archive/** : Archive completed changes under openspec/changes/archive/YYYY-MM-DD-<name>/ and run 'openspec validate --strict' post-archive; update specs/ if capabilities changed
Applied to files:
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/{proposal.md,tasks.md,design.md,specs/**/spec.md} : Scaffold each change with proposal.md, tasks.md, optional design.md, and delta spec files under openspec/changes/<change-id>/specs/<capability>/spec.md
Applied to files:
openspec/changes/relax-shall-must-validation/proposal.mdopenspec/changes/relax-shall-must-validation/tasks.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/tasks.md : Track implementation steps in tasks.md and mark each completed item with '- [x]' once finished
Applied to files:
openspec/changes/relax-shall-must-validation/tasks.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Prefer modifying existing specs over creating duplicates; if multiple capabilities are affected, create one delta spec.md per capability
Applied to files:
test/core/validation.test.ts
🧬 Code graph analysis (1)
test/core/validation.test.ts (1)
src/core/validation/validator.ts (1)
Validator(15-448)
🔇 Additional comments (7)
src/core/validation/validator.ts (2)
166-166: LGTM: Severity downgrade correctly implements internationalization support.The change from ERROR to WARNING for missing SHALL/MUST in ADDED requirements enables non-English specifications while maintaining guidance for English specs. The updated message clearly indicates this is a best practice recommendation.
187-187: LGTM: Consistent handling for MODIFIED requirements.The WARNING-level treatment matches the ADDED requirements logic, ensuring consistent behavior across delta operations.
openspec/changes/relax-shall-must-validation/proposal.md (1)
1-34: LGTM: Clear and well-structured proposal.The proposal effectively articulates the problem (blocking non-English documentation), the solution (WARNING instead of ERROR), and the impact (no breaking changes). The rationale that RFC 2119 is English-specific is sound, and preserving strict mode enforcement maintains flexibility for teams requiring RFC 2119 compliance.
openspec/changes/relax-shall-must-validation/specs/cli-validate/spec.md (1)
5-32: LGTM: Well-structured requirement with comprehensive scenario coverage.The requirement correctly uses SHALL/MUST keywords and includes four scenarios covering all critical cases (normal mode, strict mode, non-English text, and English with SHALL/MUST). The scenarios properly define expected behavior.
Minor note: Line 10 documents the message format as "Requirement '[name]' should contain..." but the actual implementation in validator.ts prefixes with the operation type ("ADDED" or "MODIFIED") for better clarity. This is an acceptable enhancement.
test/core/validation.test.ts (3)
403-432: LGTM: Test correctly validates non-strict mode behavior.The test properly verifies that missing SHALL/MUST keywords emit a WARNING and validation passes in non-strict mode. The assertion on line 431 confirms both the warning level and message content.
434-462: LGTM: Strict mode enforcement correctly tested.The test verifies that warnings are treated as errors in strict mode, causing validation to fail (valid=false) while still reporting issues at WARNING level. This maintains the strict enforcement option for teams requiring RFC 2119 compliance.
464-493: LGTM: Non-English scenario comprehensively tested.The test uses Chinese text (line 476: "系统必须记录所有事件" containing "必须" = "must") to verify that non-English specifications pass validation with a WARNING. The English-only regex
/\b(SHALL|MUST)\b/correctly doesn't match the Chinese text, demonstrating the intended behavior of providing RFC 2119 guidance without blocking international documentation.
Archived the completed change following OpenSpec workflow: - Moved change to archive/2025-11-05-relax-shall-must-validation/ - Updated cli-validate spec with new requirement: "SHALL/MUST validation as WARNING for internationalization" - Added 4 new scenarios: 1. Requirement without SHALL/MUST in normal mode 2. Requirement without SHALL/MUST in strict mode 3. Non-English requirement text 4. English requirement with SHALL/MUST All specs validate successfully with --strict mode. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
openspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.md (2)
1-18: Mark completed tasks with [x] checkbox to reflect PR completion status.The PR summary states "All 3 new tests pass," "implementation complete," and "manual testing performed with English and non-English content." However, all task checkboxes remain unchecked. Since this change is already archived, tasks should be marked
[x]to document completion per the archive workflow.Apply this diff to mark completed tasks:
## Implementation -- [ ] Update `src/core/validation/validator.ts` line 166: change SHALL/MUST check from ERROR to WARNING for ADDED requirements -- [ ] Update `src/core/validation/validator.ts` line 187: change SHALL/MUST check from ERROR to WARNING for MODIFIED requirements -- [ ] Update error message to be more guidance-focused (recommend rather than require) +- [x] Update `src/core/validation/validator.ts` line 166: change SHALL/MUST check from ERROR to WARNING for ADDED requirements +- [x] Update `src/core/validation/validator.ts` line 187: change SHALL/MUST check from ERROR to WARNING for MODIFIED requirements +- [x] Update error message to be more guidance-focused (recommend rather than require) ## Testing -- [ ] Add test case: requirement without SHALL/MUST passes validation with WARNING -- [ ] Add test case: requirement without SHALL/MUST fails with ERROR in --strict mode -- [ ] Add test case: non-English requirement text (e.g., Chinese "必须") validates successfully with WARNING -- [ ] Run existing test suite to ensure no regressions +- [x] Add test case: requirement without SHALL/MUST passes validation with WARNING +- [x] Add test case: requirement without SHALL/MUST fails with ERROR in --strict mode +- [x] Add test case: non-English requirement text (e.g., Chinese "必须") validates successfully with WARNING +- [x] Run existing test suite to ensure no regressions ## Validation -- [ ] Run `openspec validate relax-shall-must-validation --strict` and resolve all issues -- [ ] Test with English spec (should show WARNING for missing SHALL/MUST) -- [ ] Test with non-English spec (should show WARNING but pass) -- [ ] Test with --strict mode (should fail on WARNING) +- [x] Run `openspec validate relax-shall-must-validation --strict` and resolve all issues +- [x] Test with English spec (should show WARNING for missing SHALL/MUST) +- [x] Test with non-English spec (should show WARNING but pass) +- [x] Test with --strict mode (should fail on WARNING)
10-10: Clarify expected behavior in strict-mode test task.Line 10 states "fails with ERROR in --strict mode" but the behavior is that a WARNING is emitted which then fails validation due to
--stricttreating warnings as errors. Revise to "fails validation in --strict mode because warnings are treated as errors" for clarity, or reference the specification requirement for consistent terminology.-- [x] Add test case: requirement without SHALL/MUST fails with ERROR in --strict mode +- [x] Add test case: requirement without SHALL/MUST fails validation in --strict mode (warnings treated as errors)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
openspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.md(1 hunks)openspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md(1 hunks)openspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.md(1 hunks)openspec/specs/cli-validate/spec.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (4)
openspec/{specs/**/spec.md,changes/*/specs/**/spec.md}
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/{specs/**/spec.md,changes/*/specs/**/spec.md}: Write requirements using SHALL/MUST for normative wording
Every requirement must include at least one scenario, formatted exactly with a '#### Scenario: ' header (no bullets or bold)
Under ADDED, introduce new capabilities as standalone requirements rather than altering existing ones
Files:
openspec/specs/cli-validate/spec.md
openspec/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Keep current, deployed specs in openspec/specs//spec.md (one focused capability per directory)
Files:
openspec/specs/cli-validate/spec.md
openspec/changes/*/**
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Choose a unique kebab-case, verb-led change-id (add-, update-, remove-, refactor-) for openspec/changes//
Files:
openspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
openspec/changes/archive/**
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Archive completed changes under openspec/changes/archive/YYYY-MM-DD-/ and run 'openspec validate --strict' post-archive; update specs/ if capabilities changed
Files:
openspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
🧠 Learnings (11)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Write requirements using SHALL/MUST for normative wording
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Validate proposals and specs with 'openspec validate <item> --strict' and fix all issues before sharing
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Under ADDED, introduce new capabilities as standalone requirements rather than altering existing ones
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Every requirement must include at least one scenario, formatted exactly with a '#### Scenario: <name>' header (no bullets or bold)
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Write requirements using SHALL/MUST for normative wording
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Under ADDED, introduce new capabilities as standalone requirements rather than altering existing ones
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/specs/**/spec.md : Use ADDED, MODIFIED, REMOVED, or RENAMED sections when authoring deltas; place changed requirements under the correct operation header
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/{specs/**/spec.md,changes/*/specs/**/spec.md} : Every requirement must include at least one scenario, formatted exactly with a '#### Scenario: <name>' header (no bullets or bold)
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/specs/**/spec.md : For MODIFIED requirements, paste the full existing requirement block (header through scenarios) and ensure the header text matches exactly (whitespace-insensitive)
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/specs/**/spec.md : Use RENAMED when only the requirement name changes; if behavior changes too, use RENAMED plus MODIFIED referencing the new name
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Validate proposals and specs with 'openspec validate <item> --strict' and fix all issues before sharing
Applied to files:
openspec/specs/cli-validate/spec.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/archive/** : Archive completed changes under openspec/changes/archive/YYYY-MM-DD-<name>/ and run 'openspec validate --strict' post-archive; update specs/ if capabilities changed
Applied to files:
openspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/{proposal.md,tasks.md,design.md,specs/**/spec.md} : Scaffold each change with proposal.md, tasks.md, optional design.md, and delta spec files under openspec/changes/<change-id>/specs/<capability>/spec.md
Applied to files:
openspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.mdopenspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md
📚 Learning: 2025-10-22T06:05:06.615Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.615Z
Learning: Applies to openspec/changes/*/tasks.md : Track implementation steps in tasks.md and mark each completed item with '- [x]' once finished
Applied to files:
openspec/changes/archive/2025-11-05-relax-shall-must-validation/tasks.md
🔇 Additional comments (3)
openspec/changes/archive/2025-11-05-relax-shall-must-validation/proposal.md (1)
1-34: Well-articulated proposal with clear problem statement and solution.The proposal effectively communicates the international accessibility goal and the pragmatic approach of downgrading to WARNING while preserving
--strictenforcement. Structure and rationale are sound.openspec/changes/archive/2025-11-05-relax-shall-must-validation/specs/cli-validate/spec.md (1)
1-32: Requirement is well-structured with comprehensive scenario coverage.The requirement properly uses SHALL for normative wording and all four scenarios have correct
#### Scenario:headers covering the key cases: normal validation, strict mode, non-English text, and English with SHALL/MUST keywords.Per the AI summary, this file contains duplicate scenario sections. Please verify there is no redundant content within this file that should be deduplicated.
openspec/specs/cli-validate/spec.md (1)
219-247: New requirement is correctly formatted and properly positioned in the spec.The requirement uses SHALL for normative wording and all four scenarios follow the correct
#### Scenario:header format. The content appropriately completes the CLI validation specification with guidance for international support.The AI summary mentions this file contains duplicate identical SHALL/MUST validation sections. Please verify there is no unintended duplication of the requirement+scenarios block elsewhere in this file that should be removed for clarity.
The prepare script runs before dependencies are installed, causing build failures when installing from GitHub. Changed to postinstall which runs after pnpm install completes. This allows: npm install -g git+https://github.com/yha9806/OpenSpec.git
Enable direct installation from GitHub by committing built dist files: - Uncommented dist/ in .gitignore to allow tracking build output - Removed prepare script (causes build failures during git install) - Kept prepublishOnly for npm registry releases This allows users to install directly from GitHub: npm install -g git+https://github.com/yha9806/OpenSpec.git Build artifacts are now included so no compilation is needed during install. Fixes npm/pnpm interaction issues on Windows.
TabishB
reviewed
Nov 11, 2025
Contributor
There was a problem hiding this comment.
I'm fine with this change, but like mentioned in the other PR, not too keen in checking in the /dist files.
For example this PR itself has an outdated dist that contains the old ERROR instead of the new WARNING. This will be too confusing to keep doing and very hard to check and review in the PR's itself. It adds a lot of clutter for not enough benefit.
Happy to get this change merged in otherwise though once those changes are removed. i.e reverting the .gitignore so /dist is not tracked anymore as well as reverting the package.json too
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #243: OpenSpec currently requires all requirements to contain SHALL or MUST keywords (RFC 2119), enforced as an ERROR. This blocks users who write specifications in non-English languages.
Changes
Validation Behavior:
--strictmode continues to enforce the check (treats warnings as errors)Code Changes:
src/core/validation/validator.tslines 166 and 187: Changedlevel: 'ERROR'tolevel: 'WARNING'test/core/validation.test.ts:relax-shall-must-validationTesting
✅ All 3 new tests pass
✅ No regressions in existing test suite (267/268 tests passing, 1 pre-existing Windows-specific failure unrelated to changes)
✅ Manually tested with English and non-English content
✅ OpenSpec proposal validated with
--strictmodeImpact
openspec validateResult
After this change:
--strictmodeExample
Before (ERROR):
After (WARNING):
Validation now passes, users can proceed!
🤖 Generated with Claude Code
Summary by CodeRabbit