Skip to content

Expansion of spec-kit rules #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 15, 2025
Merged

Expansion of spec-kit rules #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 93 additions & 39 deletions .specify/memory/constitution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
<!--
Sync Impact Report
Version change: 1.3.0 -> 1.4.0
Modified principles: Principle 13 (Branch Naming Consistency expanded to multi-prefix standard)
Added sections: Prefix category definitions table; CI enforcement workflow `.github/workflows/branch-prefix-check.yml`
Version change: 1.5.1 -> 1.6.0
Modified principles: None
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fix incorrect change log entry.

The sync header claims “Modified principles: None,” but this PR revises existing principles (P7, P8, P9, P11–P16) and adds Principle 17. Leaving the entry as-is breaks the governance audit trail. Update the header to enumerate the modified principles so downstream automation and reviewers don’t get a false signal.

🤖 Prompt for AI Agents 
In .specify/memory/constitution.md around line 4, the sync header incorrectly
reads "Modified principles: None" despite changes to existing principles and an
addition; update that header to list the modified principles P7, P8, P9, P11–P16
and note the new Principle 17 (e.g., "Modified principles: P7, P8, P9, P11–P16;
Added: P17") so the audit trail and downstream automation reflect the actual
changes.

Added sections: Principle 17 (Documentation-Derived Rule Synchronization)
Removed sections: None
Templates requiring updates: plan-template.md (✅), spec-template.md (✅), tasks-template.md (✅), DEVELOPER.md (✅), CONTRIBUTING.md (✅), branch-prefix-check.yml (✅)
Deferred TODOs: None
Templates requiring updates: plan-template.md (✅), spec-template.md (✅), tasks-template.md (✅)
Follow-up TODOs: Implement doc rule scan script (regex normative terms) & add CI job; baseline first scan by 2025-11-01.
-->

# Generate Release Notes Action Constitution
Expand Down Expand Up @@ -42,10 +42,16 @@ New placeholders, chapters, or hierarchy features MUST default to non-breaking b
uncertain. Document additions in README + release notes.
Rationale: Incremental evolution without destabilizing existing users.

### Principle 7: Resource-Conscious GitHub API Usage
All mining MUST route through rate limiter abstractions. Disable hierarchy expansion when feature off. Avoid redundant
fetches (cache IDs once retrieved). Performance concerns addressed before merging API-heavy features.
Rationale: Preserves rate limits & improves speed.
### Principle 7: Resource-Conscious GitHub API Usage & Performance Budgeting
All mining MUST route through rate limiter abstractions and remain within a documented soft performance budget.
Rules:
- Disable hierarchy expansion when feature off to avoid unnecessary calls.
- Avoid redundant fetches (cache IDs once retrieved).
- Verbose runs SHOULD (and CI MAY) log: total API requests, elapsed wall-clock seconds, issues processed, PRs processed, remaining rate limit.
- Soft API call target: ≤ 3 * (issues + PRs) for typical release windows; overages require justification & follow-up optimization task.
- If remaining core rate limit <10% before optional hierarchy expansion, skip hierarchy mining with a warning (do not fail build).
- Performance baselines MUST be periodically (at least once per quarter) captured for representative repositories.
Rationale: Preserves rate limits, ensures predictably fast runtime, and prevents hidden performance regressions.

### Principle 8: Lean Python Design
Prefer pure functions; introduce classes ONLY when stateful behavior or polymorphism required. Avoid deep inheritance;
Expand All @@ -64,7 +70,7 @@ Rationale: Prevents confusion & keeps coverage meaningful.

### Principle 11: Focused & Informative Comments
Comments MUST succinctly explain non-obvious logic, constraints, or workaround rationale. Prohibited: stale, narrative,
Speculative, or redundant comments. Maintain or delete on change; never leave outdated intent.
speculative, or redundant comments. Maintain or delete on change; never leave outdated intent.
Rationale: Enhances clarity without noise.

### Principle 12: Test Path Mirroring
Expand Down Expand Up @@ -93,59 +99,107 @@ Rules:
- Descriptor: lowercase kebab-case; hyphens only; no spaces/underscores/trailing slash.
- Optional numeric ID may precede description: `fix/987-label-trim`.
- Avoid vague terms (`update`, `changes`); state intent (`improve-logging`, `relabel-duplicate-detection`).
- Forbidden: mixing categories (e.g., `feature-fix/`), uppercase, camelCase.
- Scope alignment: PR description MUST align with chosen prefix category; reviewers reject mismatches (e.g., docs-only PR on feature/ branch).
Rationale: Enables automated classification, precise audit tooling, clearer commit/PR history semantics, and supports future CI policy enforcement.
- Forbidden: mixing categories, uppercase, camelCase.
- Scope alignment: PR description MUST align with chosen prefix category.
Rationale: Enables automated classification, clearer history semantics, and supports CI policy enforcement.

### Principle 14: Static Typing Discipline
All production modules MUST be fully type-checked with `mypy` (no silent exclusion beyond legacy transitional areas explicitly documented).
Rules:
- New code MAY NOT introduce `# type: ignore` without inline justification.
- Broad `Any` disallowed unless interacting with third-party library lacking stubs (justify in PR).
- Progressive enforcement: expand mypy coverage to tests by 2025-11-01 (create issue if deadline adjustment needed).
Rationale: Early defect detection, self-documenting APIs, safer refactors.

### Principle 15: TODO Debt Governance
Inline `TODO` (or `FIXME`) MUST include an issue reference (`#<id>`). Format: `# TODO(<issue-id>|<tracking-tag>): <action>`.
Rules:
- Missing issue link blocks merge (unless converted immediately to issue during review).
- TODO lifetime max: 2 MINOR releases; aged TODOs trigger escalation issue.
- Deprecated TODO replaced by comment removal OR fixed code in same PR.
Rationale: Prevents silent entropy & ensures planned remediation of technical debt.

### Principle 16: Security & Token Handling
No secrets or token fragments MAY be logged (even at DEBUG). Environment access limited to documented inputs.
Rules:
- Mask potentially sensitive substrings when logging dynamic user inputs.
- Dependencies updated under `chore/` branches; review for supply chain risk (pin versions in requirements files).
- Introduce new external services ONLY with explicit README threat notes (data sent, retention, opt-in flag).
Rationale: Protects consumers using default GITHUB_TOKEN and mitigates leakage risk.

### Principle 17: Documentation‑Derived Rule Synchronization
Normative statements (MUST/SHOULD/SHALL/REQUIRED) introduced or changed in project Markdown docs (e.g., `README.md`,
`CONTRIBUTING.md`, `DEVELOPER.md`, any `docs/**/*.md`) MUST be reconciled with this constitution & templates.
Rules:
- Every PR modifying *.md files that adds/changes normative language MUST include one of:
1. “Aligns with existing Principle X” (explicit reference), OR
2. A Constitution amendment (new/updated principle), OR
3. Justification that wording is purely explanatory (no new rule) using phrase: `NON-NORMATIVE` in PR description.
- If conflict between doc text and a principle arises, the constitution prevails until amended; PR MUST either patch docs or amends principles in same PR.
- Introduced process steps (e.g., ��run script X before commit”) MUST appear in: (a) constitution governance or quality gates section, OR (b) tasks template if feature-scoped.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Resolve garbled characters in Principle 17.

The text shows “��run script X before commit” instead of a readable quoted phrase. This corrupt encoding will confuse readers and could break any automation parsing the sentence. Replace the garbled characters with the intended quotation marks (e.g., “run script X before commit”).

🧰 Tools
🪛 LanguageTool

[grammar] ~139-~139: There might be a mistake here.
Context: ...e PR. - Introduced process steps (e.g., ��run script X before commit”) MUST appear in...

(QB_NEW_EN)

[grammar] ~139-~139: There might be a mistake here.
Context: ...vernance or quality gates section, OR (b) tasks template if feature-scoped. - A D...

(QB_NEW_EN)

[grammar] ~139-~139: There might be a mistake here.
Context: ...OR (b) tasks template if feature-scoped. - A Doc Rule Scan Script (planned) parses ...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
.specify/memory/constitution.md around line 139: Principle 17 contains garbled
characters “��run script X before commit” — replace the corrupted bytes with
proper Unicode quotation marks and the intended phrase so it reads e.g. “run
script X before commit”; ensure file is saved with UTF-8 encoding and run a
quick scan for other non-UTF-8 replacement characters to avoid similar
corruption elsewhere.

- A Doc Rule Scan Script (planned) parses changed Markdown lines for regex: `\b(MUST|SHOULD|SHALL|REQUIRED)\b` and fails CI unless reconciliation note present.
- Template Propagation: When new normative doc rule is adopted, update: plan-template Constitution Check, spec-template alignment bullets, tasks-template path/quality gates.
- Quarterly Audit: Run scan across repo; produce report listing normative statements without principle references; open issues for each orphan.
Rationale: Prevents silent drift between contributor docs and enforceable governance; ensures single source of truth & predictable automation.

## Quality & Testing

- Test Directory Structure:
- tests/unit/: All unit tests (test_<module>.py) — required location.
- tests/integration/: End-to-end tests (integration_test.py to be migrated here when reorganized).
- tests/fixtures/: Optional static data samples.
- tests/helpers/ & tests/utils/: Test-only helpers (utils may merge into helpers).
- Framework: pytest ONLY (no unittest classes).
- Coverage: Enforce threshold ≥80% (existing command uses --cov-fail-under=80). New logic must keep or raise coverage.
- Independence: Tests MUST not depend on run order or mutate shared global state beyond fixture scope.
- tests/helpers/ & tests/utils/: Test-only helpers.
- Framework: pytest ONLY.
- Coverage: Enforce threshold ≥80% (uses --cov-fail-under=80). New logic must keep or raise coverage.
- Independence: Tests MUST not depend on execution order or mutate global state beyond fixture scope.
- Parametrization: Use @pytest.mark.parametrize instead of manual loops.
- Integration tests import public interfaces only (e.g., main entry, generator class).
- Integration tests import public interfaces only.
- Failing tests are written first (Principle 1) for new core logic.
- NEW: Path mirroring (Principle 12) enforced for all new/changed modules.
- Transitional Migration Plan: Add tasks in upcoming PRs to relocate remaining categorized tests.
- Branch Naming Check: Implementation PRs MUST originate from an allowed prefixed branch (`feature/`, `fix/`, `docs/`, `chore/`). (Principle 13)
- Path mirroring (Principle 12) enforced for all new/changed modules.
- Branch naming check enforced (Principle 13).
- Typing coverage gate (Principle 14).
- TODO audit gate (Principle 15).
- Performance summary logged in verbose mode (Principle 7) when enabled.
- Documentation rule sync: PR review checklist confirms Principle 17 compliance for any *.md normative additions.

## Workflow & Quality Gates

Pre-merge local mandatory checkers (from DEVELOPER.md):
1. Formatting: black --check (line length 120 per pyproject.toml).
2. Linting: pylint global score target ≥9.5 (no fatal errors).
3. Typing: mypy (0 blocking errors) — treat Any proliferation as smell (justify if unavoidable).
Pre-merge mandatory local (and CI) gates:
1. Formatting: black --check (line length 120).
2. Linting: pylint global score ≥9.5 (no fatal errors).
3. Typing: mypy (0 blocking errors); justify new ignores.
4. Tests: pytest all green.
5. Coverage: ≥80% overall; justify any temporary dip (must be recovered within next PR).
6. Dead Code: grep for unused utilities; remove or reference usage in same PR.
7. Determinism: (Manual) Validate repeated runs produce identical output for sample dataset.
8. Branch Naming: CI/Review MUST verify allowed prefix (feature|fix|docs|chore). Non-compliant branches BLOCK merge until renamed.
5. Coverage: ≥80% overall; justify any temporary dip.
6. Dead Code: remove or justify.
7. Determinism: repeat test run yields identical sample output.
8. Branch Naming: enforced allowed prefix.
9. TODO Governance: all TODOs issue-linked & within lifetime window.
10. Performance Budget (when verbose/perf job active): API call soft target evaluation (Principle 7).
11. Documentation Rule Sync: normative doc changes reconciled per Principle 17.

Quality Gate Failure Handling:
- Minor failures (formatting, lint) → fix immediately; do not merge with waivers unless urgent hotfix.
- Coverage dip → requires explicit justification + recovery plan (link issue ID).
- Non-deterministic output → BLOCKING until resolved.
- Branch naming violation → BLOCKING until branch renamed; no exception (prefix set: feature|fix|docs|chore).
- Minor failures (formatting, lint) → immediate fix; no waivers unless urgent hotfix.
- Coverage dip → explicit justification + recovery issue.
- Non-deterministic output → BLOCKING.
- Branch naming violation → BLOCKING until renamed.
- TODO governance failure → BLOCKING (fix or link issue).
- Performance overrun → CONDITIONAL (document + follow-up optimization task) unless causing timeouts → BLOCKING.
- Documentation rule sync failure → BLOCKING until reconciliation (add amendment or clarify NON-NORMATIVE).

## Governance

- Constitution supersedes ad-hoc practices; PRs MUST state compliance or list justified exceptions.
- Versioning (this constitution): Semantic (MAJOR.MINOR.PATCH).
- MAJOR: Remove/redefine a principle or backward incompatible process change.
- MINOR: Add new principle/section (current change qualifies here: Branch Naming Consistency).
- PATCH: Clarifications/typos with no semantic effect.
- MINOR: Add new principle/section or materially expand guidance.
- PATCH: Clarifications, numbering/order corrections, non-semantic wording.
- Amendment Flow:
1. Propose change with rationale & impact assessment.
2. Update Sync Impact Report header (include affected templates & TODOs).
3. Bump version according to rule above.
4. Obtain maintainer approval (≥1) — emergency fixes allow retroactive review.
- Compliance Review: PR template SHOULD reference Principles 1, 2, 10, 12, 13 (multi-prefix) + coverage threshold. Reviewers reject if principles violated without justification.
4. Obtain ≥1 maintainer approval (emergency fixes allow post-hoc review).
- Compliance Review: PR template SHOULD reference Principles 1, 2, 7, 10, 12, 13, 14, 15, 17 + coverage threshold.
- Backward Compatibility: Input names & placeholder semantics require MAJOR bump if changed.
- Enforcement: CI pipeline SHOULD automate black, pylint, mypy, pytest, coverage threshold; manual deterministic checks remain. Branch naming can be auto-validated by simple prefix check script.
- Enforcement: CI automates formatting, lint, typing, tests, coverage, branch prefix, TODO lint, and optional performance logging.

**Version**: 1.4.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-14
**Version**: 1.6.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-15
21 changes: 13 additions & 8 deletions .specify/templates/plan-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,20 @@
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

Mandatory alignment items:
- Test‑First Reliability: Provide failing unit test list BEFORE implementation.
- Explicit Configuration Boundaries: All new behavior exposed via action inputs (list any new inputs needed).
- Deterministic Output Formatting: Confirm ordering & placeholders remain stable.
- Lean Python Design: Justify each new class; prefer functions for stateless logic.
- Localized Error Handling: Define how errors are logged instead of cross-module exceptions.
- Dead Code Prohibition: Identify any code to delete made obsolete by this feature.
- Test Path Mirroring: Confirm new unit tests placed in `tests/unit/<source-relative-path>/test_<file>.py`.
- Branch Naming Consistency: Confirm current branch uses allowed prefix (feature|fix|docs|chore):
- Test‑First Reliability (P1): Provide failing unit test list BEFORE implementation.
- Explicit Configuration Boundaries (P2): All new behavior exposed via action inputs (list any new inputs needed).
- Deterministic Output Formatting (P3): Confirm ordering & placeholders remain stable.
- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and fallback behavior if rate limit low.
- Lean Python Design (P8): Justify each new class; prefer functions for stateless logic.
Comment on lines +36 to +37
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify fallback behavior wording

Line 36 drops the verb in “fallback behavior if rate limit low,” which reads awkwardly. Please add the missing verb for clarity.

-- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and fallback behavior if rate limit low.
+- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and define fallback behavior if rate limits are low.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and fallback behavior if rate limit low.
- Lean Python Design (P8): Justify each new class; prefer functions for stateless logic.
- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and define fallback behavior if rate limits are low.
- Lean Python Design (P8): Justify each new class; prefer functions for stateless logic.
🧰 Tools
🪛 LanguageTool

[grammar] ~36-~36: There might be a mistake here.
Context: ...and fallback behavior if rate limit low. - Lean Python Design (P8): Justify each ne...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In .specify/templates/plan-template.md around lines 36 to 37, the phrase
"fallback behavior if rate limit low" is missing a verb and reads awkwardly;
change it to include the verb (e.g., "fallback behavior if the rate limit is
low" or "fallback behavior if rate limits are low") to make the sentence
grammatically correct and clearer.

- Localized Error Handling (P9): Define how errors are logged instead of cross-module exceptions.
- Dead Code Prohibition (P10): Identify any code to delete made obsolete by this feature.
- Test Path Mirroring (P12): Confirm new unit tests placed in `tests/unit/<source-relative-path>/test_<file>.py`.
- Branch Naming Consistency (P13): Confirm current branch uses allowed prefix (feature|fix|docs|chore):
`git rev-parse --abbrev-ref HEAD | grep -E '^(feature|fix|docs|chore)/'`.
- Static Typing Discipline (P14): Public APIs fully typed; list any unavoidable `Any` / `type: ignore` with justification.
- TODO Debt Governance (P15): Any introduced TODO lines MUST carry issue reference; list initial issues here.
- Security & Token Handling (P16): No logging of secrets; describe any new external API interactions & masking strategy.
- Documentation‑Derived Rule Sync (P17): Any new/changed normative doc statements reconciled (reference principle / amendment / NON-NORMATIVE justification).

## Project Structure

Expand Down
5 changes: 5 additions & 0 deletions .specify/templates/spec-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,17 @@ List how this feature will comply with core principles:
- Test‑First (P1): Failing unit tests in `tests/unit/test_<feature>.py` BEFORE implementation.
- Explicit Configuration Boundaries (P2): New behavior exposed only via documented action inputs (list if any needed).
- Deterministic Output (P3): Define ordering / formatting impacts; MUST remain stable across runs.
- Performance Budget & API Usage (P7): Provide expected API call impact, measurement method (verbose logs / baseline script), and mitigation if nearing rate limit.
- Lean Python Design (P8): Prefer functions; justify any new class (state or polymorphism requirement).
- Localized Error Handling (P9): Describe logging + return strategy; no cross-module exception raises.
- Dead Code Prohibition (P10): Identify any functions to remove or refactor; commit with tests.
- Focused Comments (P11): Plan for concise logic/rationale comments; avoid narrative.
- Test Path Mirroring (P12): Place unit tests at `tests/unit/<source-relative>/test_<file>.py`.
- Branch Naming Consistency (P13): Branch MUST start with one of: `feature/`, `fix/`, `docs/`, `chore/`. Use kebab-case descriptor (optional numeric ID). Rename before merge if violated.
- Static Typing Discipline (P14): All new public functions fully typed; list any `Any` / `type: ignore` with justification.
- TODO Debt Governance (P15): Any new TODO includes issue link (format `TODO(<issue-id>):`); enumerate added TODO items.
- Security & Token Handling (P16): Confirm no sensitive values logged; describe any new external service interactions + masking.
- Documentation‑Derived Rule Sync (P17): Normative *.md changes reference principle, create amendment, or are marked NON-NORMATIVE.

## User Scenarios & Testing *(mandatory)*

Expand Down
Loading
Loading