progressive-disclosure refactor of SKILL.md (302 → 159 lines) + scope-comma guard, v1.8.0

.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "progress-tracker",
   "displayName": "Progress Tracker",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Tracks local development progress across scopes with consented, script-gated migration (a whole-document inventory audit, not just an eyeballed active-work section), and safe lifecycle scripts — for any project.",
   "author": {
     "name": "FWcloud916",

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "progress-tracker",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Track local development progress across single- or multi-scope task lifecycles.",
   "author": {
     "name": "FWcloud916",

AGENTS.md

@@ -44,7 +44,7 @@ single-line edits) can skip; do not pre-load all docs.
 | Changing lifecycle update, close-out, or audit behavior | [SKILL.md](skills/progress-tracker/SKILL.md) + [update_progress.py](skills/progress-tracker/scripts/update_progress.py) |
 | Changing the item template or INDEX shape | [PROGRESS.template.md](skills/progress-tracker/references/PROGRESS.template.md) + [INDEX.template.md](skills/progress-tracker/references/INDEX.template.md) |
 | Changing the status lifecycle | [SKILL.md](skills/progress-tracker/SKILL.md) §Status lifecycle + [workflow.md](skills/progress-tracker/references/workflow.md) |
-| Changing migration-inventory/migration-audit behavior or the record shape | [SKILL.md](skills/progress-tracker/SKILL.md) §Before creating anything + [MIGRATION.template.md](skills/progress-tracker/references/MIGRATION.template.md) + [KNOWN-ISSUE.md](KNOWN-ISSUE.md) KI-001 |
+| Changing migration-inventory/migration-audit behavior or the record shape | [migration.md](skills/progress-tracker/references/migration.md) + [MIGRATION.template.md](skills/progress-tracker/references/MIGRATION.template.md) + [KNOWN-ISSUE.md](KNOWN-ISSUE.md) KI-001 |
 | Changing eval scenarios or the trigger matrix | [evals/README.md](evals/README.md) |
 | Changing Codex plugin packaging or installation | [README.md](README.md) §Install + [docs/design-decisions.md](docs/design-decisions.md) Codex packaging decision |
 | Understanding why it's built this way | [docs/design-decisions.md](docs/design-decisions.md) |
@@ -65,6 +65,23 @@ python3 evals/scripts/test_grade_scenarios.py
 - Requirement keywords (MUST/SHOULD/MAY) follow RFC 2119, uppercase.
 - English throughout — templates, field names, and section headings.
 
+## SKILL.md editing checklist
+
+Before committing any change to `skills/progress-tracker/SKILL.md`, ask:
+
+1. **Premature completion** — does any sentence claim behavior that no script
+   or eval enforces yet?
+2. **Duplication** — does the same rule now live in two places? Keep one
+   authoritative copy and point to it (only the gate and lifecycle marker
+   blocks are deliberately duplicated, byte-synced by verify.sh).
+3. **Sediment** — is any sentence a leftover from a superseded design?
+4. **Sprawl** — should single-branch detail move to a `references/` doc
+   behind a read-in-full pointer instead of staying top-level?
+5. **No-op** — does each sentence change behavior relative to the model's
+   default? Delete failing sentences whole.
+6. **Negation** — can a "do not" be restated as the positive target behavior?
+   (Hard guardrails stay negative.)
+
 ## Docs maintenance
 
 When modifying any file under `docs/`, update its `> **Last updated:**

README.md

@@ -12,15 +12,13 @@ several — for any project.
   tracker directory's supporting files.
 - **Migration guard, script-gated** — before first use, inventories existing
   tracking documents and their pointers and asks whether to migrate.
-  `migration-inventory` scans a legacy source **whole-document** (never just
-  an "in progress" section), can scaffold an empty tracker before destination
-  creation, and `migration-audit` is the pre-deletion gate: it
-  fails while any actionable/ambiguous entry lacks a valid `migrated` or
-  `excluded` disposition and destination, migrated Evidence is absent or
-  non-unique, any generated record field changed,
-  any old path/name or changed link is unverified, or the pre-deletion human
-  sign-off checklist is incomplete. `migration-finalize` durably records the
-  user's retain/delete decision without deleting source files.
+  Migration is a two-phase commit: `migration-inventory` scans each legacy
+  source **whole-document** (never just an "in progress" section),
+  `migration-audit` is the prepare-phase gate that must pass before the
+  deletion question may even be asked, and `migration-finalize` durably
+  records the user's retain/delete decision without deleting source files.
+  The full contract lives in
+  [`references/migration.md`](skills/progress-tracker/references/migration.md).
 - **Multi-scope, tool-agnostic** — `--scope name[:branch[:ticket]]` accepts
   any free-form label (a service, a package, a sibling repo — not validated
   against a directory) and any ticket format (serial, `#123`, `JIRA-111`, a
@@ -161,7 +159,7 @@ progress-tracker/
 │   └── progress-tracker/
 │       ├── SKILL.md      # canonical entry point: lifecycle, args, status enum
 │       ├── agents/       # Codex UI metadata (openai.yaml)
-│       ├── references/   # workflow spec + item/index templates + seed READMEs
+│       ├── references/   # workflow spec + migration contract + templates + seed READMEs
 │       └── scripts/      # create/update/check CLIs + their pytest suites
 ├── agents/           # dedicated agent definition (preloads the skill)
 ├── AGENTS.md         # maintainer guide for this repo (CLAUDE.md is a symlink to it)
@@ -181,6 +179,7 @@ progress-tracker/
 | [AGENTS.md](AGENTS.md) | Maintainer guide: hard constraints, the verify gate |
 | [docs/design-decisions.md](docs/design-decisions.md) | Decision log with rationale: generic scope model, script-first eval strategy |
 | [workflow.md](skills/progress-tracker/references/workflow.md) | Full workflow spec: folder structure, field semantics, cleanup policy |
+| [migration.md](skills/progress-tracker/references/migration.md) | The migration contract in full: flow, command reference, Kind/disposition rules |
 | [PROGRESS.template.md](skills/progress-tracker/references/PROGRESS.template.md) | The item template |
 | [INDEX.template.md](skills/progress-tracker/references/INDEX.template.md) | The item-list seed |
 | [evals/README.md](evals/README.md) | Scenario + trigger-matrix strategy and how to run them |

agents/progress-tracker.md

@@ -36,7 +36,8 @@ The preloaded **progress-tracker** skill is your operating manual. Follow it str
   "in progress" section, and defaults every unrecognized heading to blocking
   rather than assuming it is safe to ignore. Copy every actionable entry,
   dispose of every inventory row, update every pointer, and audit all old
-  path/name references afterward.
+  path/name references afterward. A migration was approved → read the skill's
+  `references/migration.md` in full before running any migration command.
 
 <!-- MIGRATION_GATE_START -->
 Migration is script-gated. The deletion question MUST NOT be asked until both

docs/design-decisions.md

@@ -2,13 +2,133 @@
 
 > **Type:** Reference
 > **Audience:** Maintainers, AI agents
-> **Last updated:** 2026-07-27
+> **Last updated:** 2026-07-28
 
 A decision log with rationale, in chronological order. When a design choice
 seems arbitrary, check here before changing it.
 
 ---
 
+## 2026-07-28 — Shared vocabulary lives in domain-models.md, not a repo-root CONTEXT.md
+
+The improvement plan's Phase 4 prescribed a repo-root `CONTEXT.md` for shared domain
+vocabulary (scope, disposition, Kind, tracker-dir, preflight, two-phase commit).
+Implemented instead as `docs/domain-models.md` §0 Shared Vocabulary:
+
+- The terms are structural domain terminology — they sit one section above the
+  entities that define them, so definitions and structure cannot drift apart.
+- `AGENTS.md`'s task→doc table already routes "domain behavior" reads to
+  domain-models.md; a second repo-root file would split the same lookup across two
+  homes for no added recall.
+- doc-architect 2.4.0 ships an opt-in `CONTEXT.md` glossary module; this repo
+  declines the module deliberately — revisit only if the vocabulary outgrows the
+  domain reference or needs rulings that contradict it (`_Avoid_` synonym lists,
+  cross-doc drift tripwires).
+
+## 2026-07-28 — SKILL.md defers argument semantics to the CLI interface
+
+Experiment: can SKILL.md's Key-arguments list and option prose be replaced
+by the scripts' own `--help`, per the interface-design principle (the
+interface teaches through its structure; errors teach at the moment of the
+mistake)? Method: a fact-by-fact coverage matrix — every sentence proposed
+for deletion was checked against live `--help` output and probed error
+messages, keeping the eval philosophy's independent truth source (actual
+CLI behavior, not the docs being edited).
+
+Result: adopted. `--help` fully covers slug format, `--scope` syntax and
+defaults, verbatim tickets, `--plan` resolution, `--dir` containment, and
+`--root` discovery; `choices=` enums expose the status values; and every
+probed mistake (bad slug, bare plan filename, dir escape, optionless
+update, invalid transition, unknown slug) fails with an actionable message
+that names the fix. Those sentences left SKILL.md (180 → 162 lines) behind
+a "read `--help` before first use" pointer.
+
+Two classes of prose stayed, by rule: **behavioral policy** the interface
+cannot express (always pass `--plan` when a plan exists; back-fill `TBD`;
+keep the two Status fields identical; `review` ≠ `done`), and **silent-
+failure traps** the interface cannot catch at the right moment — the one
+found: an unescaped comma in a `--scope` value used to split the entry in
+two with no error. That pre-registered condition has since fired: the parser
+now rejects whitespace-adjacent unescaped commas and empty entries, and both
+CLIs echo the parsed scope in normal mode (see the amended 2026-07-24
+escaping entry), so the escaping sentence moved out of SKILL.md into
+`--help`, leaving `--plan` as the sole interface-untaught rule.
+
+---
+
+## 2026-07-28 — Eval suite is not tautological with SKILL.md
+
+Audited whether the graders judge with the same logic the skill documents —
+which would let a docs change rubber-stamp itself. They do not: every
+scenario runs the real CLIs in a disposable git repo, and
+`grade_scenarios.py` asserts only on the files those runs produce
+(`files_exist` / `files_absent` / `content_contains` / `content_not_contains`
+/ `content_count`); no scenario, grader, or grader-regression test reads
+`SKILL.md` or any `references/` doc. Expected values therefore come from an
+independent truth source (script behavior), so the documentation refactor
+cannot false-green the evals and the evals cannot vouch for prose claims —
+`scripts/verify.sh` remains the gate for doc-level consistency.
+
+---
+
+## 2026-07-28 — Invocation semantics stay single-skill
+
+Reviewed alongside the progressive-disclosure split: `check` (the tracker
+audit) stays model-invoked inside this skill so agents run it before
+review/close-out without a separate activation; migration stays in-skill too,
+loaded only through the read-in-full pointer to `references/migration.md`
+rather than split into a second skill — a split would spend an extra
+description slot in every session's context for a branch most sessions never
+take. With only two skills in this repository, a router skill is likewise
+unjustified. The frontmatter description was rewritten in the same spirit:
+one leading trigger per lifecycle branch (create / update / audit / close out
+/ migrate), front-loaded with the preflight anchor. The activation boundary
+is unchanged — the same prompts trigger and the same prompts do not — so
+`evals/trigger-matrix.json` and its case counts stay as they are.
+
+---
+
+## 2026-07-28 — Progressive disclosure for the migration contract
+
+Migration detail (~110 of SKILL.md's 302 lines) sat top-level in `SKILL.md`
+even though only the migration branch ever needs it, and the same seven-step
+contract was restated nearly in full in `references/workflow.md`. Both copies
+now collapse to the shared preflight rules, the byte-synced
+`MIGRATION_GATE` block, and an imperative pointer ("read
+`references/migration.md` in full before running any migration command");
+`references/migration.md` is the single authoritative migration document —
+discovery/consent, the KI-001 rationale, the merged step-by-step flow, the
+command reference, and the Kind/disposition rules.
+
+Deliberate residuals: the gate block stays byte-identical in `SKILL.md`,
+`workflow.md`, and `agents/progress-tracker.md` (verify.sh check 3b) and is
+**not** duplicated into `migration.md`, which would be a fourth, unchecked
+copy; `agents/progress-tracker.md` keeps its condensed migration paraphrase
+(a subagent definition must be self-contained) plus the same read-in-full
+pointer; and SKILL.md's preflight detection rules remain top-level because
+every create runs them, not just the migration branch. `migration.md` is not
+in verify.sh's scaffold-link map, so it is never copied into user projects —
+the scaffolded seed docs already direct readers back to the installed skill.
+
+External corroboration (added the same day): Anthropic's post ["The new
+rules of context engineering for Claude 5 generation
+models"](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models)
+independently prescribes the same moves this refactor made — progressive
+disclosure over upfront content, focused single-home guidance over
+repetition, and pruning constraint prose in favor of model judgment
+("unhobbling"). Two deliberate divergences stand: the migration gate's
+MUST NOT wording stays, because it is an incident-driven (KI-001),
+script-enforced guardrail — exactly the load-bearing minority of rules the
+post's own framing says to keep; and SKILL.md retains its three CLI
+examples plus the Key-arguments list, because verify.sh check 6 requires
+the command strings and the examples are already one-per-lifecycle-stage
+minimal. The post's "interface design" step — collapsing the Key-arguments list into
+a `--help` pointer — was run as its own experiment and adopted the same day;
+see the next entry for the coverage-matrix method and the one fact the
+interface cannot teach.
+
+---
+
 ## 2026-07-27 — Package Codex directly from the repository root
 
 The repository root is the plugin root: `.codex-plugin/plugin.json` points to
@@ -52,7 +172,10 @@ Allowed transitions reflect normal review rework and explicit termination:
 Scope labels remain free-form and filesystem-independent. The compact legacy
 syntax stays compatible, with backslash escaping added for literal commas,
 colons, and backslashes. The first two unescaped colons delimit fields and an
-unescaped comma delimits scope entries.
+unescaped comma delimits scope entries. Amended 2026-07-28: an unescaped
+comma with adjacent whitespace is rejected as ambiguous and an empty entry
+(trailing, leading, or doubled comma) is rejected — both previously failed
+silently — and both CLIs echo the parsed scope names in normal-mode output.
 
 All CLI values written into Markdown tables are now rendered through shared
 helpers. Pipes and backslashes are escaped, code spans choose a delimiter that

docs/domain-models.md

@@ -2,14 +2,30 @@
 
 > **Type:** Reference
 > **Audience:** Developers, AI assistants, code reviewers
-> **Last updated:** 2026-07-27
+> **Last updated:** 2026-07-28
 
 ---
 
 The project has no database models. Its domain consists of Markdown records, parsed
 in-memory dataclasses, and guarded transitions between filesystem states. The canonical
-workflow contract is [`SKILL.md`](../skills/progress-tracker/SKILL.md); this document
-maps that contract to the implementing functions in the two Python CLIs.
+workflow contract is [`SKILL.md`](../skills/progress-tracker/SKILL.md) (with the
+migration contract in
+[`references/migration.md`](../skills/progress-tracker/references/migration.md)); this
+document maps that contract to the implementing functions in the two Python CLIs.
+
+## 0. Shared Vocabulary
+
+Terms used with a fixed meaning across `SKILL.md`, the `references/` docs,
+and this document:
+
+| Term | Definition |
+|---|---|
+| **scope** | A free-form label for one piece of a task (e.g. `api`, `payments-service`); never validated against any directory. |
+| **tracker-dir** | The tracker's root directory inside the project — `progress/` by default, overridden by `--dir` / `$PROGRESS_TRACKER_DIR` — holding `INDEX.md`, item folders, `_template/`, `_plans/`, and `_migrations/`. |
+| **preflight** | The mandatory pre-creation inspection for an existing tracking mechanism and the documents that point to it (`SKILL.md` §Before creating anything). |
+| **two-phase commit** | The migration deletion model: `migration-audit` is the prepare phase, and deletion may proceed only after it exits 0 and `migration-finalize` records the user's explicit decision (the commit). |
+| **Kind** | A migration-inventory row's generated classification: `actionable` and `ambiguous` block the audit; `done`, `empty`, and `historical` do not. |
+| **disposition** | The reviewer's ruling on an inventory row: `migrated`, `excluded`, or `not-applicable`. |
 
 ## 1. Model Details
 
@@ -295,6 +311,9 @@ Only then does the record enter `deleted`.
 - `require_project_descendant()` resolves paths before accepting them, including paths
   behind existing symlinks.
 - Scope labels are parsed text and never validated as directories.
+- Ambiguous scope input fails closed: an unescaped comma touching whitespace
+  and empty scope entries are rejected at parse time, and both CLIs echo the
+  parsed scope names in normal-mode output.
 - Ticket values are trimmed and defaulted but never prefixed or reformatted.
 - Markdown table values escape pipes and backslashes; inline code chooses a delimiter
   longer than any backtick run in the value.

docs/project-overview.md

@@ -2,7 +2,7 @@
 
 > **Type:** Explanation
 > **Audience:** Developers, AI assistants, and tooling that needs project context
-> **Last updated:** 2026-07-27
+> **Last updated:** 2026-07-28
 >
 > A reusable agent skill and deterministic CLI toolkit for durable, local development-progress tracking. Related docs: [domain-models.md](domain-models.md), [coding-style.md](coding-style.md), and [design-decisions.md](design-decisions.md).
 
@@ -30,7 +30,9 @@ runtime.
 The public behavior is specified in
 [`skills/progress-tracker/SKILL.md`](../skills/progress-tracker/SKILL.md). The longer
 operational rationale and field reference live in
-[`workflow.md`](../skills/progress-tracker/references/workflow.md).
+[`workflow.md`](../skills/progress-tracker/references/workflow.md); the migration
+contract in full lives in
+[`migration.md`](../skills/progress-tracker/references/migration.md).
 
 ### 1.2 Relationship with Other Systems
 
@@ -90,7 +92,7 @@ The repository separates human/agent workflow guidance from deterministic mutati
 User or agent request
         |
         v
-skills/progress-tracker/SKILL.md --------> references/workflow.md
+skills/progress-tracker/SKILL.md --------> references/workflow.md + migration.md
         |                                          |
         | chooses command                          | explains fields and policy
         v                                          v
@@ -143,7 +145,7 @@ progress-tracker/
 └── skills/progress-tracker/
     ├── SKILL.md                  # Canonical agent workflow and public command contract
     ├── agents/openai.yaml        # Codex skill UI metadata
-    ├── references/               # Workflow, templates, and generated tracker seed docs
+    ├── references/               # Workflow, migration contract, templates, and seed docs
     └── scripts/
         ├── new_progress.py       # Scaffold and create CLI
         ├── update_progress.py    # Update, close, audit, and migration CLI