jig-version-rubric

name	jig-version-rubric
description	Use when creating, reviewing, or re-setting this repository's version grading rubric at .jig/versioning.md: adopt the jig default human-intervention rubric, write a project-specific one, edit one grade, or reset to the default. Owns the rubric file; never runs a release.

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, five 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
## 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.

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:

English (canonical)	Korean (legacy)
## Decision Order	## 판정 순서
## Grade Definitions	## 등급 정의
## Hard Rules	## 강경 규칙
## Interface Paths	## 인터페이스 경로
## Release Notes	## 릴리즈 노트
## Version Format	## 버전 형식
## Pre-Release Checks	## 릴리즈 전 검증
> Basis:	> 기준:

• 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. Did the value on offer widen, shrink, or change, 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 capability added, removed, or changed, or a generation replaced. Something new is possible and the old way still works |
| `major` | The value on offer widened, shrank, or changed, or a human must edit config, files, or call sites to keep using it |

## Hard Rules
> A change that raises no error but behaves differently is `major`. Its size does not matter.

> A skill or prompt instruction that changes when the agent speaks is at least `minor`.

## 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:

• The escalation rules exist because the break that matters in an AI project is a quiet one. No test suite confirms that a reworded instruction still fires on the same input, so the version number is the channel left for "a human should look at this."
• 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.

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.

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 to what this project actually promises.

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

• Read INDEX.md first. It is the only file that lists the types, so a draft not indexed there is invisible to the scan.
• Drafts are not grouped into subdirectories. The consumer column in INDEX.md carries the grouping, because a project often serves several kinds of consumer at once and a directory would force it into one.
• Do not read every body. Read INDEX.md, pick the type, read that one file.
• The catalog grades on the SemVer consumer-compatibility axis, not the human-intervention axis the default rubric uses. The two disagree — removing a feature is major in the catalog and minor in the default. Adopt one whole; never merge questions from both into one rubric.
• The catalog is payload: jig-update replaces it. Never edit a catalog file to record a project's decision — the decision lives in the resolved rubric path.

When the project type is not obvious, run rubric-scan (or the installed jig-rubric-scan) first. It scans the repository, scores it against INDEX.md, and hands back a type with the paths that produced it. This skill still owns the write.

Actions

Called without arguments. Determine the current state first, then confirm the user's intent.

Action	When	Result
Review	file exists	Report the current rubric: path, source, kind, the three grades, commit state. Stop.
Create	file missing	Show the default, ask the binary question, write the file.
Adopt a type	the project has a clear type, or rubric-scan handed one over	Write that catalog draft as the rubric, dated and with the interface list adjusted.
Re-set	file exists, user wants a different rubric	Show the current rubric, confirm, then replace it.
Edit one grade	file exists, one grade is wrong	Update that grade's question and definition only; preserve the rest.
Reset to default	file exists, user wants the default back	Replace with the default rubric and update the > Basis: line.
Convert titles	file exists with legacy Korean titles and the user asks	Rename only the section titles to the English spellings; leave every question, definition, and rule word for word.

Procedure

1. Resolve the path and read the file if it exists. Report which of the three sources supplied the path, and note when it came from the environment variable that it is session-only.
2. If the file exists, summarize it and confirm the intent: keep, re-set, edit one grade, or reset to default. Keep ends the run.
3. For create or re-set, show the default rubric and ask one question: use this rubric?
   • Yes → write the default and record adoption in the > Basis: line.
   • No → offer the catalog before drafting from scratch. Read rubrics/INDEX.md, name the types that fit what this repository ships, and let the user pick one; when the type is unclear, run rubric-scan and use its recommendation. A chosen draft is written as-is except for the > Basis: line and the interface list.
   • No catalog type fits → ask, for each of the three grades, which changes in this project belong there. Put the user's own wording into ## Decision Order and ## Grade Definitions.
4. If the user skips the question or does not answer, adopt the default and record it. Do not ask again.
5. Keep the user's vocabulary, including the language they answered in. Only normalize the sentence shape into <question> → \patch`` form. Translating their words into jig terms such as "silent behavior change" makes the next release grade differently than they intended.
6. Write the file, creating .jig/ when missing. Then hand the commit to the repository's flow: if develop-task-flow (or the installed jig-develop-task-flow) exists, follow it with a chore/<slug> branch, a chore: squash commit, and a develop push. Otherwise propose a normal commit on the current branch.
7. Report.

Safety Rules

• Never overwrite an existing rubric without showing its current content and getting explicit confirmation.
• Do not create .bak copies. The file is tracked, so git history is the record. Warn before overwriting when the file is untracked or has uncommitted changes.
• Do not translate or retitle an existing rubric without being asked. The questions are the project's own words.
• Do not grade a release or write release notes; github-release owns that.
• Do not touch branches, branch protection, tags, releases, or GitHub settings.
• Do not write anything outside the resolved rubric path and its parent .jig/ directory.
• Do not modify rubrics/. It is shipped payload that jig-update replaces; a project's decision belongs in the rubric file.
• Do not force a commit. If the user declines, report the uncommitted state.
• Preserve unrelated user changes.

Final Report

Write the report in the language the repository already uses for its own documents, defaulting to English.

## Version Rubric

- Path: <path> (source: environment variable | local config | convention)
- Basis: jig default (human-intervention axis) | catalog <type> | project-specific
- Titles: English | Korean (legacy, still read)
- patch: <question>
- minor: <question>
- major: <question>
- Change: created | re-set | <grade> edited | reset to default | none
- Draft source: none | rubrics/<type>.md
- Commit: done <commit subject> | uncommitted (does not reach clones)
- Next: none | <action>