0x0w1/jig/version-rubric

Version Rubric

Use this repository skill to decide and maintain how this project grades patch, minor, and major. The decision lives in a project-owned Markdown file that github-release reads at release time.

Run this skill whenever the rubric needs to be created, reviewed, or changed. It is safe to run repeatedly.

Rubric File

Resolve the rubric path in this order:

1. JIG_VERSION_RUBRIC environment variable (session-only override).
2. git config --local --get jig.versionRubric (repository override; not propagated by clone).
3. .jig/versioning.md (the convention).

• .jig/ is owned by the project, not by jig. The installer and jig-update never write or delete it, and jig-doctor never treats it as drift.
• The file must be committed. git config --local lives in .git/config and is not propagated by clone or CI checkout, so a config-only setup grades differently for different people.
• Never store state such as "the default was adopted" in a config key. That belongs in the file's > Basis: line, which is the single record of the decision.

File Contract

Two required sections, six optional. The section titles are the contract.

# Version Policy
 
> Basis: jig default (human-intervention axis) | project-specific, <date>
 
## Decision Order        (required)
1.<question> → `patch`
2.<question> → `minor`
3.<question> → `major`
 
## Grade Definitions     (required)
| bump | definition |
 
## Hard Rules            (optional) conditions that always escalate
## Interface Paths       (optional) changed paths that set a starting grade
## Hotfix Triggers       (optional) what justifies bypassing the develop queue
## Release Notes         (optional) note section order and titles
## Version Format        (optional) tag pattern, pre-1.0 handling, summary language
## Pre-Release Checks    (optional) commands to run before releasing

• ## Decision Order is asked in order and stops at the first match. A rubric cannot change that meaning.
• An optional section a rubric omits simply does not apply to that project. No ## Hard Rules means no escalation rule, even though the default below ships two.
• The > Basis: line records whether the default was adopted or the rubric was written for the project.
• Sections beyond these are read as context, not ignored. A project may add its own, such as a list of what counts as its public interface.

Interface Paths

## Public Interface, where a rubric has one, is prose: a reader decides whether a change touched it. ## Interface Paths is the machine-readable companion, so the grading skills can compute a starting grade from the diff instead of eyeballing it.

## Interface Paths
 
| path glob | interface | floor |
|---|---|---|
| `src/api/**` | the HTTP surface consumers call | `minor` |
| `docs/**` | internal | `patch` |

• A changed path takes the floor of the first row it matches, so order specific globs above general ones. The path floor for a range is the highest floor any changed path took.
• A path matching no row contributes nothing. A table that lists only the public paths is complete; there is no need to enumerate the internal ones.
• The floor is advisory. Paths say what changed, never how, so a typo fix and a contract break under the same glob match the same row. A grade below the path floor is allowed and must record its reason; a grade above it needs no justification.
• This is the opposite of a recorded task grade, which is a judgement made with the diff in hand and is never lowered. Keep the two apart in the report.
• Write the globs against repository-root-relative paths, matching what git diff --name-only prints.

Hotfix Triggers

hotfix-flow puts a commit on main that develop does not have, which is the one operation the branch model otherwise forbids. Whether a defect deserves that is a judgement, and a judgement made while something is on fire is the least reliable kind.

This section moves the judgement earlier. The project writes, while calm, the question that decides the bypass and the conditions it has already recognised; hotfix-flow then requires the run to answer against them.

## Hotfix Triggers
 
> Does harm keep occurring and accumulating for as long as the released state stands?
 
-The released artifact does not install or start
-Data is lost or corrupted
-A credential or secret is exposed

The leading > line is the anchoring question, and the list is what answering it has produced so far. A closed list is wrong eventually, and a gate people route around is worse than no gate, so the question is what the list is measured against.

• Every item is an observable state, not a feeling. "Urgent" is not a trigger; "the released CLI exits non-zero on startup" is.
• The question is about the world, not about the person asking. "We have a demo tomorrow" and "the release is overdue" describe a schedule; neither says anything keeps happening because the released state stands. That is what makes the question answerable by someone other than the requester.
• When nothing on the list matches, hotfix-flow puts the question instead. A no ends the run and the fix goes to develop-task-flow. A yes does not start the hotfix either: the new condition is added to this section and committed on its own first, so the list grows by decision rather than by exception.
• Omit the section and hotfix-flow falls back to the question and list it ships, exactly as github-release falls back to the default rubric. A project that never wrote this section still grades and still gates.

This section is not written per project type. Domain wording differs — a blank screen, a 5xx, a corrupted state file — but each is the same answer to the same question, so a catalog draft restates rather than decides. Keep the question general and let the project add the two or three conditions it has actually met.

Legacy Section Titles

Rubrics written before this contract switched to English carry Korean titles. They stay valid, and every jig skill that reads a rubric accepts either spelling:

• A rubric may use one spelling or the other. Do not mix them inside one file: a file with ## Decision Order and ## 등급 정의 reads as one required section missing.
• Never rewrite an existing rubric's titles on your own. The file is user-owned content, and a silent retitle is a change to how the project grades releases. Offer the conversion, and convert only when the user says so.
• Write new rubrics with the English titles.

Default Rubric

Offer this as-is. It grades by whether a human has to step in. Scale alone does not survive an AI-paced project: generations turn over fast enough that grading by size inflates major until the number carries no information.

# Version Policy
 
> Basis: jig default (human-intervention axis), adopted <date>
 
## Decision Order
1.Is this a fix inside what the project already does? → `patch`
2.Can people do something new, or did a generation turn over, while everything they already do keeps working? → `minor`
3.Does it break an existing usage contract, or must a human step in to keep using it? → `major`
 
## Grade Definitions
| bump | definition |
|---|---|
| `patch` | A fix inside the existing feature set: bug fixes, wording and documentation changes, internal cleanup |
| `minor` | A compatible capability or generation improvement. Something new is possible and existing supported usages still work |
| `major` | An existing usage contract breaks, or a human must edit config, files, or call sites to keep using it |
 
## Hard Rules
> A silent change is `major` only when it breaks an existing usage contract, changes authorization or data-handling boundaries incompatibly, or requires manual migration. A different response alone does not establish a break.
 
> A compatible skill or prompt enhancement, including improved default responses or additional guidance, is `minor`. Wording-only changes and fixes that restore the documented contract are `patch`.
 
## Version Format
-While the major version is `0`, a `major` grade raises the minor position: `v0.Y.Z` → `v0.(Y+1).0`. Before 1.0, both the value on offer and the call sites may change at any time. Grade exactly as after 1.0 and record the `major` grade in the release report.
-After `v1.0.0`, a `major` grade raises the major position. The grace above ends there.

The default ships ## Hard Rules and ## Version Format alongside the two required sections:

• Judge the contract, not textual output equality. Record the supported usage, the incompatible before/after behavior, and any required user action before assigning major. More useful explanations or a richer learning outline do not by themselves break a contract.
• While the major version is 0, minor and major land on the same position, so the escalation rules cost nothing yet and the > Basis: line says so. They begin to bind at v1.0.0, which is why they are settled before then.
• A project that wants neither section removes them; both are optional by contract.
• The default ships no ## Interface Paths table, because it grades by whether a human must step in and that axis names no paths. After writing it, offer to add one built from the project's own public paths; a project that declines keeps grading exactly as before.

A project whose releases ship documents rather than features usually grades by artifact instead: patch for document add/edit/delete, minor for changes to the tooling that manages the documents, major for a restructure. That rubric and a dozen others are already written; take one from the catalog below instead of drafting it.

Skill grading examples

Existing project-owned rubrics remain authoritative. Updating jig does not rewrite them. If an older rubric escalates every response change to major, explain the difference and use this skill to edit that project policy only when requested. Do not move published tags or reinterpret recorded task grades automatically.

Type Catalog

rubrics/ ships next to this skill and holds one ready draft per project type. Every file in it is a complete rubric: copy it to the resolved rubric path, fill the > Basis: date, and adjust the interface list and the ## Interface Paths globs to what this project actually promises and where it keeps it.

rubrics/
├── INDEX.md            # type list, detection signals, scoring and merge rules
├── _template.md        # skeleton for a type the catalog does not cover yet
├── common.md           # SemVer principles that hold across every type
└── <type>.md           # one draft per project type, all on one level