diff --git a/.claude/settings.json b/.claude/settings.json index 95b5934..7c01091 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -23,7 +23,8 @@ }, "enabledPlugins": { "superpowers@claude-plugins-official": true, - "elements-of-style@superpowers-marketplace": true + "elements-of-style@superpowers-marketplace": true, + "ponytail@ponytail": true }, "extraKnownMarketplaces": { "claude-plugins-official": { @@ -37,6 +38,12 @@ "source": "github", "repo": "obra/superpowers-marketplace" } + }, + "ponytail": { + "source": { + "source": "github", + "repo": "DietrichGebert/ponytail" + } } } } diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 9398ad7..f19d51e 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -11,9 +11,32 @@ artifacts (e.g. `docs/domain/`, `docs/specs/`, `docs/plans/`). Deliberately narrow: configuration directories the process may also create (such as `.claude/rules/` during a project-level rules install) are not Process directories — their install questions are their own, defined where the -install is specified. +install is specified. A ticket root and its ticket directories are not +Process directories either. _Avoid_: artifact folder +**Ticket root**: +The directory under `docs/` that a project names in the `ticket.root` +settings key, which holds the ticket directories. The +process asks no mode question for it and writes no `.gitignore` there; +what the project's own ignore rules exclude inside it, the process +respects and may still use. +_Avoid_: tickets folder, jira directory + +**Ticket directory**: +The directory one level below the ticket root that holds one ticket's +work — its process documents, code-review reports and companion +documents — named `-` by the ticket's key. One ticket has +exactly one. +_Avoid_: ticket folder, ticket workspace + +**Companion document**: +A file in a ticket directory that is not a process document or a review +report — an analysis, a brief, a runbook, a data file. It needs no +process frontmatter, may carry its own, and the process leaves it +untouched. +_Avoid_: supporting document, attachment, ticket document + **First-create question**: The question — ignored mode or tracked mode — asked when a process directory is created for the first time, or exists with no prior @@ -103,7 +126,8 @@ _Avoid_: index check, store check **Review report**: The single persistent document one code-review run writes under -`docs/code-review/` of the reviewed project — one run, one report, +`docs/code-review/` of the reviewed project, or under a ticket +directory's `code-review/` — one run, one report, written by the run's owner. Shape defined by the review-reports rule's contract; a domain plugin's inline fallback is a strict subset of it, never a different shape. @@ -246,9 +270,27 @@ or a technical design, each read next by the plan-writer and the plan-adversary — as against an implementation plan, whose next reader only executes it. The class decides which ceremonies a document owes (ADR 0004), so the lifecycle rule branches on it rather than on a -filename. +filename; a class suffix only detects the class. _Avoid_: design document +**Process document**: +A design spec, technical design or implementation plan — a document the +lifecycle rule governs. Under `docs/` it is recognised by its class +suffix or its class directory, and with `ticket.root` set, together +with a frontmatter `status:`; a file with the suffix alone is not one — +in a ticket directory, it is a companion document. +_Avoid_: lifecycle document, judged document (for a plan) + +**Class suffix**: +The ending of a process document's file name — `-spec`, `-technical-design` +or `-plan` — that detects its class wherever the file lies. +_Avoid_: type suffix, kind suffix + +**Class directory**: +One of `docs/specs/`, `docs/technical-designs/` and `docs/plans/`, the +directory a process document lives in when it has no ticket directory. +_Avoid_: type directory, document folder + **Part**: A unit of a design with a resolvable identity, an explicit responsibility and its exclusions, and a contract that lets its @@ -582,7 +624,7 @@ git-ignored, and NOT a Process directory — a per-checkout store under the `.claude/` config namespace, as Private memory is a per-user one. It survives compaction, the session's end and a branch switch, and no more: that bound is what lets a Relay condense. Never a Review report, the -counted document a code-review run writes under `docs/code-review/`. +counted document one code-review run writes. _Avoid_: dispatch log, transcript file **Session skill**: diff --git a/docs/plans/2026-09-28-process-setup.md b/docs/plans/2026-09-28-process-setup.md index 1577bc0..062e723 100644 --- a/docs/plans/2026-09-28-process-setup.md +++ b/docs/plans/2026-09-28-process-setup.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-09-28 -status: approved +status: implemented adversary: concerns (resolved 2026-09-29) spec: ../specs/2026-09-28-process-setup-design.md branch: feature/process-setup diff --git a/docs/plans/2026-10-27-ticket-directories-plan.md b/docs/plans/2026-10-27-ticket-directories-plan.md new file mode 100644 index 0000000..67b8412 --- /dev/null +++ b/docs/plans/2026-10-27-ticket-directories-plan.md @@ -0,0 +1,507 @@ +--- +ticket: none +date: 2026-10-27 +status: implemented +adversary: concerns (resolved 2026-10-27) +spec: ../specs/2026-10-27-ticket-directories-spec.md +branch: feature/ticket-directories +base: develop +--- + +# Ticket directories Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use +> superpowers:subagent-driven-development (recommended) or +> superpowers:executing-plans to implement this plan task-by-task. Steps +> use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Land `docs/specs/2026-10-27-ticket-directories-spec.md` — the +opt-in `ticket.root` key with a path-valued shape, ticket-directory +placement and lookup, class detection by suffix with the `status:` gate, +the move procedure, the branch-name scheme, and review-report placement +in working-process and both standards plugins. + +**Architecture:** One code change carries a test cycle each: the +settings loader learns a `` value token, and +`decision-coverage.py` learns the `-technical-design.md` suffix. Every +other deliverable is rule, skill, command or agent prose; its test is +the check block the task publishes (a `grep` that fails before the edit +and passes after), plus `claude plugin validate`. A scratch-project +dogfood closes the plan. + +**Tech Stack:** POSIX `sh` and `awk` (`scripts/load-settings.sh`); +Python 3.9+ `unittest` (`tests/working-process/`); Markdown rules, +skills, commands and agent cards; `grep`, `git`, `claude plugin +validate`, and `claude --plugin-dir` for the dogfood. + +**Spec:** `docs/specs/2026-10-27-ticket-directories-spec.md` + +## Global Constraints + +- **The spec is the source.** Where this plan and the spec disagree, + the spec wins. +- **Realizes:** D1 — **A project without `ticket.root` behaves as + today.** Every rule sentence this plan adds opens with, or sits under, + "With `ticket.root` set"; no existing behaviour changes for an unset + key. +- **Realizes:** D18 — **The glossary is already amended** (grilling + session and fix waves, commits on this branch). No task edits + `docs/domain/glossary.md`; every task uses its terms verbatim: ticket + root, ticket directory, process document, companion document, class + suffix, class directory. +- **Realizes:** D7 — **Rules branch on the class, never on a file + pattern.** Prose says "a design spec", "a technical design", "a + plan"; a suffix appears only where detection is described. +- **Key citation.** A file that starts citing `ticket.root` adds itself + to that key's `read-by:` in `SETTINGS_REGISTRY.md` in the same task, + so `test_settings_registry.py` stays green after every task. +- **No version bump.** Each changed plugin gets a line under + `## Unreleased` in its `CHANGELOG.md` (Task 8); versions move only in + the release PR. +- **English, repo hygiene.** No machine paths, no client names; the + client project's directory appears only as `docs/jira/abc-…` examples. +- **Never read a credential's value or write one into a command.** +- **Check blocks** run with `/bin/sh` from `plugins/working-process/`; + a path starting with `plugins/` or `tests/` is relative to the + repository root (`cd "$(git rev-parse --show-toplevel)"` first). One + `grep -q` per file — `grep -q P a b` passes when either file matches — + and no `{a,b}` file expansion. A multi-word phrase is matched on + `tr '\n' ' ' < file`, so a line wrap cannot fail it. +- **The test suite** is `python3 -m unittest discover -s + tests/working-process -p 'test_*.py'`, run from the repository root; + its output must report a test count above zero (`discover -s tests` + finds none). +- **Rule frontmatter is read by hand.** `claude plugin validate` does + not check `rules/`; every task that edits a rule's `paths:` reads the + block back and quotes each glob like the existing entries + (`- "docs/specs/**"`). +- **No `-dev` version for the dogfood.** `claude --plugin-dir` loads + this checkout directly, so the plugin-versioning rule's dogfooding + mint is not owed. +- **Elements-of-style pass.** Every task that changes prose runs the + `elements-of-style:writing-clearly-and-concisely` pass on the changed + text before the task's check block runs, so the pass cannot rewrite a + phrase the block already certified. + +## Review Focus + +1. A `ticket.root` of `docs/specs` or `docs/code-review/x` — the loader + must refuse it (Task 1, cases in `test_load_settings.py`). +2. A lookup run from a subdirectory — the rule must prescribe + `--full-tree` and the top level, or it silently misses (Task 3 check + block greps both). +3. A companion document named `*-spec.md` without `status:` — no rule + may add frontmatter to it (Task 3 gate sentence; Task 9 dogfood). +4. A branch `feature/phase-2-cleanup` in a project with `ticket.root` — + a review asks nothing and creates no directory; a new spec confirms + the ticket first (Tasks 5, 6, 7a; Task 9 dogfood). +5. A move of an uncommitted spec — `git mv` refuses an untracked file; + the procedure must use `mv` and stage nothing (Task 4; Task 9). + +--- + +### Task 1: `ticket.root` — registry entry, path validation, process-setup + +**Realizes:** D1, D2 + +**Files:** +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md` (preamble; new + `## ticket.root` entry after `review.per-round-commit`) +- Modify: `plugins/working-process/scripts/load-settings.sh` (the awk + `valid_value` at :207 and the `do_set` value check at :775-784) +- Modify: `plugins/working-process/skills/process-setup/SKILL.md` +- Test: `tests/working-process/test_settings_registry.py`, + `tests/working-process/test_load_settings.py` + +**Interfaces:** +- Produces: registry entry — + `scope: team` · `values: ` · `default: unset` · + `read-by: working-process/skills/process-setup/SKILL.md` · + `question: Which directory under docs/ holds one directory per ticket, if the project keeps them?` +- Produces: the token `` as the registry's one non-enumerated + value, accepted by the loader when the value starts with `docs/`, has + a segment after it, has no `..` segment and no trailing `/`, and + neither equals nor lies inside `docs/specs`, `docs/technical-designs`, + `docs/plans`, `docs/domain`, `docs/code-review` or `docs/memory` — + "inside" with a `/` boundary, so `docs/specs-archive` is valid — and + holds only `[A-Za-z0-9._/-]`, the settings line grammar's value class + (`load-settings.sh:159`), which `--set` would otherwise bypass. + +- [ ] **Step 1: Write the failing tests.** + In `test_settings_registry.py`: rename `test_fourteen_keys_in_order` + to `test_fifteen_keys_in_order` and append `"ticket.root"`; in + `test_every_entry_is_well_formed`, accept `fields["values"] == ""` + as the one non-enumerated shape (skip the value regex and the + default-in-values check for it). In `test_load_settings.py`, append + `"ticket.root"` to `KEYS` (:23, registry order), and add + `test_ticket_root_path_values`, using `--set ticket.root ` then + reading the block: + - `docs/jira` → exit 0, block line `ticket.root: docs/jira [team]`; + - `docs/tickets/active` and `docs/specs-archive` → exit 0; + - `jira`, `docs`, `docs/`, `docs/jira/`, `docs/../jira`, + `docs/specs`, `docs/code-review/x`, `docs/a*b` → `--set` exits 1 with + ``error: invalid value for `ticket.root` `` on stderr; + - the same invalid values written by hand into `settings.md` → block + shows `ticket.root: unset [invalid in team]` and an `error:` line. +- [ ] **Step 2: Run** `python3 -m unittest tests/working-process/test_settings_registry.py tests/working-process/test_load_settings.py` + — expect failures in `test_fifteen_keys_in_order`, + `test_precedence_and_defaults` (the block still has fourteen keys) + and `test_ticket_root_path_values`, and nowhere else. +- [ ] **Step 3: Implement.** + Registry: add the entry above; in the preamble, say `values:` is + either ` | `-separated values or the token ``, defined there. + Loader: in awk, `valid_value(val, padded)` returns + `valid_path(val)` when `padded == " "`; add + `valid_path(val)` beside it, its first test the character class. In + `do_set`, when the normalised values are ``, call a POSIX shell + `path_value_ok "$s_value"` with the same rules, character class + first, instead of the enumeration loop. The error text stays as + today, with `(allowed: )`. + Skill: where process-setup asks a key's question, a key whose + registry `values:` is `` takes a free-text answer, offered with + "leave unset" first; cite `ticket.root` by name. +- [ ] **Step 4: Run** the two test files — expect all pass; then the + test suite — expect all pass, with a count above zero. Run + `claude plugin validate plugins/working-process` for the skill edit — + expect "Validation passed". +- [ ] **Step 5: Commit** `feat(working-process): ticket.root settings key with a path value`. + +### Task 2: `decision-coverage.py` recognises a technical design by suffix + +**Realizes:** D13 + +**Files:** +- Modify: `plugins/working-process/scripts/decision-coverage.py:556-560` +- Test: `tests/working-process/test_decision_coverage.py` + +**Interfaces:** +- Produces: `is_technical_design(display: str) -> bool` — true when a + parent pair is `docs/technical-designs` **or** the file name ends in + `-technical-design.md`. + +- [ ] **Step 1: Write the failing test** `test_13b_technical_design_in_ticket_directory_produces_no_output`: + the fixture of `test_13`, with the design at + `docs/jira/abc-12-x/abc-12-x-technical-design.md` and `spec: + ../../specs/s.md`; assert exit 0, empty stdout, empty stderr. +- [ ] **Step 2: Run** `python3 -m unittest discover -s tests/working-process -p test_decision_coverage.py -k 13b` + — expect FAIL: the design is audited as a plan and prints hits. +- [ ] **Step 3: Implement** the suffix clause in `is_technical_design`; + update its docstring. +- [ ] **Step 4: Run** the whole file — expect all pass. +- [ ] **Step 5: Commit** `feat(working-process): decision coverage recognises a technical design by its suffix`. + +### Task 3: Rules — suffix globs, placement, lookup, gate, links, modes + +**Realizes:** D3, D4, D5, D6, D7, D8, D10, D12, D22 + +**Files:** +- Modify: `plugins/working-process/rules/spec-plan-lifecycle.md` + (frontmatter `paths:`; the naming paragraph near the top; the + frontmatter-links examples) +- Modify: `plugins/working-process/rules/technical-design.md` + (`paths:`; the "lives in `docs/technical-designs/`" sentence) +- Modify: `plugins/working-process/rules/propagation-duties.md` (`paths:`) +- Modify: `plugins/working-process/rules/process-artifacts.md` + (`paths:`; one sentence on the ticket root) +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md` (`read-by:` of + `ticket.root` gains the files above that cite it) + +**Interfaces:** +- Consumes: `ticket.root` (Task 1). +- Produces: the section *Ticket directories* in + `spec-plan-lifecycle.md`, which Tasks 4, 5 and 7 point to by that + name; it holds placement, the lookup commands and the gate. + +- [ ] **Step 1: Write the check block** and run it — expect every line + to fail: + - for each of `rules/spec-plan-lifecycle.md`, + `rules/propagation-duties.md`, `rules/process-artifacts.md`: + `grep -qF 'docs/**/*-{spec,technical-design,plan}.md' "$f"` + - `grep -qF 'docs/**/*-technical-design.md' rules/technical-design.md` + - `grep -q '^## Ticket directories' rules/spec-plan-lifecycle.md` + - `tr '\n' ' ' < rules/spec-plan-lifecycle.md | grep -q -- '--full-tree -d --name-only'` + - `tr '\n' ' ' < rules/spec-plan-lifecycle.md | grep -q 'git rev-parse --show-toplevel'` + - `sed -n '/^## Ticket directories/,/^## Decision register/p' rules/spec-plan-lifecycle.md | tr '\n' ' ' | grep -q 'is not a process document'` + - `tr '\n' ' ' < rules/process-artifacts.md | grep -q 'ticket root'` +- [ ] **Step 2: Edit.** Add the glob lines per the spec's + *Recognising a process document* table, keeping every directory + glob. In `spec-plan-lifecycle.md`, add `## Ticket directories` + immediately before `## Decision register` (:184) — the naming + paragraph near the top stays and points to it — carrying, in the spec's words: placement under + `/-/` (D3); the case-insensitive `-` + lookup with the trailing hyphen, from the top level and with + `git ls-tree --full-tree -d --name-only /` on the + integration branch, its remote-tracking ref first, no fetch, ask once + where the project's instructions name no branch (D4, D22); new + directory case and topic (D5); several matches or several tickets, + including the no-directory case (D6); the `status:` gate in class + suffixes and class directories alike, worded "… without `status:` … + is not a process document" (D8); "frontmatter links are + relative to the document" with the sibling and `../../specs/` + examples (D12). In `technical-design.md`, replace the location + sentence with one deferring to *Ticket directories* when + `ticket.root` is set. In `process-artifacts.md`, one sentence: the + ticket root and its ticket directories are not Process directories — + tracked, no first-create question, no `.gitignore` written, no + `dir.*` key, project ignores respected, never force-added (D10). +- [ ] **Step 3: Run** the check block — expect every line to pass; run + `python3 -m unittest tests/working-process/test_settings_registry.py` + — expect pass. +- [ ] **Step 4: Read** the four rules' `paths:` blocks back; run + `claude plugin validate plugins/working-process` — expect "Validation + passed". +- [ ] **Step 5: Commit** `feat(working-process): ticket directories in the document rules`. + +### Task 4: The move procedure + +**Realizes:** D15, D16, D17, D21 + +**Files:** +- Modify: `plugins/working-process/rules/spec-plan-lifecycle.md` (new + `### Moving a document into a ticket directory` under *Ticket + directories*) + +**Interfaces:** +- Consumes: *Ticket directories* (Task 3); the hash command + `sed '1,/^---$/d' | shasum | cut -c1-7` already in the rule. + +- [ ] **Step 1: Write the check block** and run it — expect failure. + With `S='/^### Moving a document into a ticket directory/,/^##/p'`, + each of `git mv`, `nothing is staged`, `implemented`, + `listed, never rewritten` and `matched its body before the move` + must pass `sed -n "$S" rules/spec-plan-lifecycle.md | tr '\n' ' ' | grep -q ''`. +- [ ] **Step 2: Edit.** Write the six steps of the spec's *Moving a + document* as the procedure, on the developer's command only (D15): + ticket source; the chain by `spec:`, `technical-design:`, + `revises:`, `**Follows:**`, offered as one move (D16); naming and the + legacy topic rule; `git mv` for tracked, `mv` for untracked, nothing + staged; the rewritten references, the listed ones, the stop before a + body edit to an `implemented` document (D17); the hash recompute only + where it matched before (D21); the report. +- [ ] **Step 3: Run** the check block — expect pass. +- [ ] **Step 4: Commit** `feat(working-process): move a document into a ticket directory`. + +### Task 5: Workflow rule — placement guard and branch scheme + +**Realizes:** D11, D19, D22, D23 + +**Files:** +- Modify: `plugins/working-process/rules/workflow.md` (the + "where documents go" lines in the flow, ~:9 and ~:128; *Branch + naming*, ~:233) +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md` (`read-by:`) + +**Interfaces:** +- Consumes: *Ticket directories* (Task 3). +- Produces: *Branch naming* holds the scheme `[/][-]` + and the session-answer sentence; Tasks 6 and 7 point to it. + +- [ ] **Step 1: Write the check block** and run it — expect failure: + `grep -q '\[/\]\[-\]' rules/workflow.md`; + `tr '\n' ' ' < rules/workflow.md | grep -q 'before creating a ticket directory'`; + `tr '\n' ' ' < rules/workflow.md | grep -q 'fixes the shape and not the spelling'` + (must still pass — the sentence stays). +- [ ] **Step 2: Edit.** The placement clause per the spec's + *Recognising a process document*: with `ticket.root` set and a + ticket, reuse the root's subdirectory starting with `-` + (ignoring case, working tree or integration branch), several to the + developer, a new `/-/` only with none, and + require reading the spec-plan-lifecycle rule before creating a ticket + directory (D11). In *Branch naming*, add under "With `ticket.root` + set": the scheme and key shapes, digits alone only at the key + position, the reconciliation with "fixes the shape and not the + spelling" (D19); the integration branch named by the project's + instructions or asked once (D22); a declined confirmation falling + through to the conversation and `none`, one answer per branch per + session, nothing recorded (D23). +- [ ] **Step 3: Run** the check block — expect pass; registry test — + expect pass. +- [ ] **Step 4: Commit** `feat(working-process): ticket placement and the branch scheme in the workflow rule`. + +### Task 6: Ticket-frontmatter rule + +**Realizes:** D8, D9, D19, D23 + +**Files:** +- Modify: `plugins/working-process/rules/ticket-frontmatter.md` + (*Field sets*; *Sourcing and backfill*, ~:51-60) +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md` (`read-by:`) + +**Interfaces:** +- Consumes: *Branch naming* (Task 5). + +- [ ] **Step 1: Write the check block** and run it — expect failure: + `tr '\n' ' ' < rules/ticket-frontmatter.md | grep -q 'companion document'`; + `grep -q 'Branch naming' rules/ticket-frontmatter.md`; + `grep -q 'confirm' rules/ticket-frontmatter.md`; + `tr '\n' ' ' < rules/ticket-frontmatter.md | grep -q 'class directory'`. +- [ ] **Step 2: Edit.** *Field sets*: the process-document set is + chosen by class (class suffix or class directory), not by + directory; a companion document in a ticket directory is exempt from + `ticket` and `date` and its own frontmatter is left untouched (D9). + *Sourcing and backfill*: with `ticket.root` set, the branch is read by + *Branch naming*'s scheme, and a branch ticket whose ticket directory + does not exist yet is stated and confirmed before the document is + written — the order's one question (D19, D23). The backfill sentence + exempts every file the `status:` gate excludes — a file matching a + class suffix or lying in a class directory without `status:` — and + every companion document in a ticket directory, while every other + document under `docs/` is backfilled as today (D8, D9). +- [ ] **Step 3: Run** the check block and the registry test — expect pass. +- [ ] **Step 4: Commit** `feat(working-process): ticket-frontmatter for ticket directories`. + +### Task 7a: Review-report placement in working-process + +**Realizes:** D14, D19, D20 + +**Files:** +- Modify: `plugins/working-process/rules/review-reports.md` (`paths:`; + location; the `ticket` field line ~:79-81; *Local pocket* ~:230) +- Modify: `plugins/working-process/skills/process-status/SKILL.md` + (`description:`) +- Modify: `plugins/working-process/README.md` (the directories it lists) +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md` (`read-by:` + gains `review-reports.md`) + +**Interfaces:** +- Consumes: *Branch naming* (Task 5), *Ticket directories* (Task 3). +- Produces: the rule's placement section, which Task 7b's commands + follow; the report directory reaches an agent as an absolute path in + its dispatch prompt. + +- [ ] **Step 1: Write the check block** and run it — expect each to fail: + `grep -q 'docs/\*\*/code-review/\*\*' rules/review-reports.md`; + `grep -q 'feature/phase-2-cleanup' rules/review-reports.md`; + `grep -q 'fix-for-ABC-123' rules/review-reports.md`; + `tr '\n' ' ' < skills/process-status/SKILL.md | grep -q 'ticket directories'`. +- [ ] **Step 2: Edit.** The placement rule and table for an + interactive session, the unattended fallback, local-only reports to + `docs/code-review/`, the skipped first-create check and pocket in a + ticket directory, numeric keys as `"#42"`, solo runs through the + Contract probe, standalone installs to `docs/code-review/`; the + `ticket` field line derives as today with the row-3 and session + answers as context, and names the one interactive question as the + exception to "never blocks on a question" (D14, D19, D20). The + process-status `description:` names ticket directories beside the + class directories; the README lists the ticket root. +- [ ] **Step 3: Read** the rule's `paths:` back; run the check block, + the test suite (count above zero) and `claude plugin validate + plugins/working-process` — expect pass. +- [ ] **Step 4: Commit** `feat(working-process): review reports in ticket directories`. + +### Task 7b: Review commands of the standards plugins + +**Realizes:** D20 + +**Files:** +- Modify: `plugins/python-standards/commands/python-review.md`, + `plugins/python-standards/agents/python-code-reviewer.md`, + `plugins/python-standards/skills/python-code-review/SKILL.md` (:104), + `plugins/python-standards/README.md` +- Modify: the salesforce-standards counterparts (command, agent, + `skills/salesforce-code-review/SKILL.md` :165, README) +- Modify: `plugins/working-process/SETTINGS_REGISTRY.md` (`read-by:` + gains the two commands) + +**Interfaces:** +- Consumes: the review-reports placement section (Task 7a). + +- [ ] **Step 1: Write the check block** and run it — expect each to fail: + for each of `plugins/python-standards/commands/python-review.md` and + `plugins/salesforce-standards/commands/salesforce-review.md`: + `grep -q 'ticket.root' "$f"`; and for each of + `plugins/python-standards/agents/python-code-reviewer.md` and + `plugins/salesforce-standards/agents/salesforce-code-reviewer.md`: + `grep -q 'writes the review report to docs/code-review/' "$f"` must + **pass** before and **fail** after (the only-location claim is gone). +- [ ] **Step 2: Edit.** Each command resolves the directory before + dispatch — working tree only, `ticket.root` from the settings block, + per the review-reports rule — and passes it in the prompt; each agent + writes to the directory the prompt names; each code-review skill's + *Location* says "the directory the run resolved: `docs/code-review/`, + or a ticket directory's `code-review/`"; each README follows. +- [ ] **Step 3: Run** the check block, the test suite (count above + zero), and `claude plugin validate` on both standards plugins — + expect pass. +- [ ] **Step 4: Commit** `feat: standards review commands place reports in ticket directories`. + +### Task 8: Changelogs + +**Realizes:** none + +**Files:** `plugins/{working-process,python-standards,salesforce-standards}/CHANGELOG.md` + +- [ ] **Step 1:** Add one line under `## Unreleased` per plugin: the + opt-in `ticket.root` and what it moves (working-process); review + reports in ticket directories (both standards plugins). +- [ ] **Step 2: Commit** `docs: changelog entries for ticket directories`. + +### Task 9: Dogfood + +**Realizes:** none + +**Files:** none in the repo; the record goes to +`.claude/working-process/2d-ticket-directories/dogfood.md`. + +- [ ] **Step 1:** Build a scratch git project (develop as integration + branch, `ticket.root: docs/jira` in `.working-process/settings.md`, + `docs/jira/abc-12-old/` with a `screens-spec.md` lacking `status:`). + Rules load from installed copies, not from the plugin, and a + temporary `CLAUDE_CONFIG_DIR` cannot authenticate an inner session, + so the run uses the real config: + - move the installed rules out of the loaded tree and put the + branch's in their place, from the repository root, `$B` a scratch + directory outside `~/.claude/rules/`: + `mv ~/.claude/rules/working-process "$B/rules-backup"`; + `mkdir ~/.claude/rules/working-process && /bin/cp -f plugins/working-process/rules/*.md ~/.claude/rules/working-process/`; + `ls ~/.claude/rules/` must list the same directories as before; + - `claude plugin disable` the installed working-process, + python-standards and salesforce-standards, and run sessions with + `claude --plugin-dir` on this branch's three plugins; + - before the cases, ask a session to quote the workflow rule's new + *Branch naming* sentence on `ticket.root`; no quote, no dogfood. + The spec-plan-lifecycle rule is probed after the first spec write, + since it loads on a matching file. +- [ ] **Step 2:** On each review branch of the cases below + (`feature/ABC-12-x`, `bugfix/ABC-12-y`, `ABC-12`, + `feature/phase-2-cleanup`, `fix-for-ABC-12`), commit one changed + `*.py` file, so `/python-review` has a diff. Run every case of the + spec's *Verification* dogfood + bullet, and the Review Focus items 3–5; record each prompt, the + resulting tree (`find docs -type f`) and pass or fail. +- [ ] **Step 3:** Repeat the ticketless flow in a project without + `ticket.root`: documents land in the class directories. +- [ ] **Step 4:** Restore: `rm -r ~/.claude/rules/working-process && + mv "$B/rules-backup" ~/.claude/rules/working-process`, then + `claude plugin enable` the three plugins; confirm with + `ls -a ~/.claude/rules/working-process/` (the installed files and + `.manifest.json`, as before the run) and `claude plugin list` (all + three enabled). +- [ ] **Step 5:** Report failures to the developer before any fix; + a fix is a new task. + +## Review rounds + +### 2026-10-27 — plan-adversary, fable 5.1, blocking (round 1, full-document) + +- fixed 2026-10-27 — [Important] F1: `discover -s tests` runs zero tests; license: the repo's process-setup plan; *Global Constraints* names `discover -s tests/working-process` with a count above zero, Tasks 1, 7a, 7b use it +- fixed 2026-10-27 — [Important] F2: `## Ticket directories` after the naming paragraph swallowed 140 lines and the gate check passed on an existing example; license: spec-plan-lifecycle's structure; Task 3 places the section before `## Decision register` and checks the phrase "is not a process document" +- fixed 2026-10-27 — [Important] F3: `grep -q P a b` passes on one file, brace expansion fails under `sh`, cwd unstated; license: the check blocks' purpose; *Global Constraints* fixes cwd and one grep per file, Tasks 3 and 7b loop per file +- fixed 2026-10-27 — [Important] F4: `path_value_ok` dropped the value-class check, so `--set` could write a line the loader rejects; license: `do_set`'s "nothing is created before both pass"; the class check comes first in shell and awk, with `docs/a*b` and `docs/specs-archive` cases +- fixed 2026-10-27 — [Important] F5: the backfill exemption covered companion documents only, against D8; ruling: 2026-10-27; D8 governs — Task 6 exempts every file the `status:` gate excludes, and the spec's *Companion documents* and *Changes by file* say so +- fixed 2026-10-27 — [Important] F6: a temporary `CLAUDE_CONFIG_DIR` cannot authenticate, and same-name plugins collide; ruling: 2026-10-27; option (a) — Task 9 backs up and replaces the user-level rules, disables the installed plugins, and restores both in its own step +- fixed 2026-10-27 — [Minor] M1: the probe targeted a path-scoped rule; license: the rule's `paths:`; the probe quotes the always-loaded workflow rule +- fixed 2026-10-27 — [Minor] M2: `claude plugin validate` skips `rules/`; license: the plugin-authoring rule; each rule-editing task reads `paths:` back +- fixed 2026-10-27 — [Minor] M3: long phrases fail across a wrap; license: the check blocks' purpose; phrases are matched on `tr '\n' ' '` +- fixed 2026-10-27 — [Minor] M4: the dogfood's version clause was unstated; license: the plugin-versioning rule; *Global Constraints* says `--plugin-dir` owes no `-dev` mint +- fixed 2026-10-27 — [Minor] M5: no task named the elements-of-style pass; license: the repo's elements-of-style rule; *Global Constraints* requires it + +### 2026-10-27 — plan-adversary, fable 5.1, concerns (round 2, diff-scoped) + +- fixed 2026-10-27 — [Important] F7: a backup beside the installed rules still loads, and a copy-then-move restore nests it; ruling: 2026-10-27; the developer approved the four commands — move out of `~/.claude/rules/`, `mkdir` and `/bin/cp -f` in, `ls` before the first case, `rm -r` and move back +- fixed 2026-10-27 — [Minor] M6: `diff -r` had no second operand after the restore, and `cp` is aliased to `cp -i`; license: the restore's purpose; `ls -a` and `claude plugin list` confirm it, the copy is `/bin/cp -f` +- fixed 2026-10-27 — [Minor] M7: four phrase checks grepped raw lines; license: *Global Constraints*; piped through `tr '\n' ' '` +- fixed 2026-10-27 — [Minor] M8: a style pass after the check block could rewrite a certified phrase; license: the check blocks' purpose; the pass runs before the block +- fixed 2026-10-27 — [Minor] M9: the F5 sentence folded D9's exemption into D8's gate; license: D9; spec and Task 6 name the two exemptions separately + +Resolved without a fresh round: F7's commands carry the developer's sign-off, as the reviewer's stop signal allowed; the Minors are wording. diff --git a/docs/specs/2026-09-28-process-setup-design.md b/docs/specs/2026-09-28-process-setup-design.md index fde88d3..1a04bef 100644 --- a/docs/specs/2026-09-28-process-setup-design.md +++ b/docs/specs/2026-09-28-process-setup-design.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-09-28 -status: draft +status: implemented grilled: 2026-09-28 architect: concerns (resolved 2026-09-28) integrity: 2026-09-28 (sha: 901ebf5) diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md new file mode 100644 index 0000000..542eb8b --- /dev/null +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -0,0 +1,615 @@ +--- +ticket: none +date: 2026-10-27 +status: implemented +grilled: 2026-10-27 +architect: concerns (resolved 2026-10-27) +integrity: 2026-10-27 (sha: fcf90fc) +decisions: registered +branch: feature/ticket-directories +base: develop +--- + +# Ticket directories — a ticket's documents in one place + +A project that works ticket by ticket keeps each ticket's material in +one directory: an analysis, a spike and its results, a handoff, a +brief, data files, a runbook. Its design spec, technical design and +plan live elsewhere, in `docs/specs/`, `docs/technical-designs/` and +`docs/plans/`, so they are not at hand when someone opens the ticket. +This spec lets a project opt into a ticket root under `docs/`: a new +document for a ticket goes into that ticket's directory, beside +everything else the ticket has. + +## Problem + +A client project the developer works in keeps `docs/jira/-/` +per ticket, tracked in git, with the key in lower case +(`abc-1489-opportunity-team`). Reviewing a ticket meant opening that +directory and then searching three other directories for the documents +the working process wrote. The developer wants to open the ticket +directory and find everything. + +The working process finds a document's class by its directory: the +three class directories appear 47 times in 13 plugin files — rule +`paths:` globs, process-status, `scripts/decision-coverage.py`, the +`dir.*` settings keys and relative frontmatter links. Since the +document-names convention (`spec-plan-lifecycle.md`, *Judged documents +and plans*), a new document's name carries its class +(`--spec.md`, `-technical-design.md`, `-plan.md`), so +the class no longer needs the directory. + +## Goals, non-goals, anti-goals + +Goals: + +- With the ticket root set, a new design spec, technical design or plan + for a ticket lands in that ticket's directory. +- Code-review reports for a ticket land in the same directory. +- A document written without a ticket can move into a ticket directory + later, on the developer's command, with its chain and its links. +- A project that never sets the ticket root behaves as it does today. + +Non-goals: + +- CI runs. A review run in CI without a readable branch name falls back + to `docs/code-review/`; no CI-specific behaviour is designed until a + real pipeline is observed. +- Ticket references that yield no file prefix (`org/repo#123`): such a + document is treated as having no ticket. +- Moving existing documents without a command. +- Dropping `date:` from process documents. + +Anti-goals — the change fails, even if it works, when: + +- a second directory appears for a ticket that already has one; +- a link between documents breaks; +- the process writes its frontmatter into a document that does not + need it. A companion document may carry its own frontmatter; the + process leaves it alone. + +## Decisions + +- **D1** — One team settings key, `ticket.root`, turns ticket + directories on; unset keeps today's layout. Argued in *The setting*. +- **D2** — The key's value is a path under `docs/`, validated by the + loader; the registry gains a path-valued key shape. Argued in *The + setting*. +- **D3** — A document for a ticket goes to `/-/`, + one level below the root; a document without a usable ticket stays in + its class directory. Argued in *Placement*. +- **D4** — An existing ticket directory is found case-insensitively by + `-` among the root's immediate subdirectories, in the working + tree and on the integration branch's remote-tracking ref (else its + local branch); it is used whatever its topic. Argued in *Placement*. +- **D5** — Ticket directories count among the project's ticket-named + files for the key case: a file prefix and a new directory take the + case the existing ones use, else the tracker's. A new directory takes + the topic of the document that creates it. Argued in *Placement*. +- **D6** — Several matching directories, or a document carrying several + tickets, are put to the developer: a choice among the existing + directories, or, where no listed ticket has one, of the ticket whose + directory is created. Argued in *Placement*. +- **D7** — A process document's class is detected from its class + suffix, or from its class directory for a document named before the + document-names convention; the rules covering design specs, technical + designs and plans load on suffix globs anchored at `docs/`, beside + their directory globs, and still branch on the class, never on a file + pattern. Argued in *Recognising a process document*. +- **D8** — With `ticket.root` set, a file matching a class suffix or + lying in a class directory, but carrying no `status:` in its + frontmatter, is not a process document: the process neither edits nor reports it. Argued + in *Recognising a process document*. +- **D9** — A companion document in a ticket directory needs neither + `ticket:` nor `date:`; process documents keep their full frontmatter. + Argued in *Companion documents*. +- **D10** — The ticket root and its ticket directories are not Process + directories: tracked, with no first-create question, no `.gitignore` + written by the process and no `dir.*` key reaching them; ignores the + project sets inside them are respected. Argued in *Modes*. +- **D11** — The always-loaded workflow rule states where a ticket's + documents go, including the reuse of an existing ticket directory, + since the path-scoped lifecycle rule loads only once the first file + is written. Argued in *Recognising a process document*. +- **D12** — Frontmatter links are relative to the document that holds + them. Argued in *Links*. +- **D13** — `decision-coverage.py` recognises a technical design by the + `-technical-design.md` suffix as well as by its directory. Argued in + *Recognising a process document*. +- **D14** — A code-review report whose ticket the branch name gives, + or the developer names for it (D19), goes to + `/code-review/`, unless it is local-only; + any other report goes to `docs/code-review/`. Argued in *Review + reports*. +- **D19** — With `ticket.root` set, a branch name is read by the + scheme `[/][-]`, `` any one segment and + `` a key shape, defined once in the workflow rule's *Branch + naming*. For a review's placement, a name in the scheme whose ticket + directory exists gives the ticket directory; a letters-hyphen-digits + shape outside the scheme is asked about in an interactive session; + anything else places the report in `docs/code-review/`, while the + report's `ticket:` field derives as today. A review never creates a + ticket directory. For a new document, the ticket-frontmatter rule + reads the same scheme and confirms a ticket whose directory does not + exist yet. Without `ticket.root`, branch sourcing is unchanged. + Argued in *Review reports*. +- **D20** — The review command resolves the report directory from the + working tree before dispatch and hands the agent the path, and a solo + run resolves it the same way before it writes; a run with no + interactive dispatcher, an ambiguity nobody can answer, or a + local-only report writes to `docs/code-review/`. Argued in *Review + reports*. +- **D15** — Moving a document into a ticket directory is a procedure in + the lifecycle rule, run by the session on the developer's command; no + skill. Argued in *Moving a document*. +- **D16** — The move offers the document's whole chain. Argued in + *Moving a document*. +- **D17** — Inside `docs/`, the move rewrites each moved file's + frontmatter links in both directions, the `with:` file of + `integrity:`, `**Follows:**` lines and qualified decision + identifiers; it lists, never rewrites, a path in body prose and any + reference outside `docs/`, and stops for the developer before any + body edit to an `implemented` document. Argued in *Moving a + document*. +- **D21** — The move recomputes the `integrity:` hashes of a document + whose body it rewrote, keeping the audit date, only where they matched + before the move; it asks for no new audit. Argued in *Moving a + document*. +- **D22** — The integration branch for the lookup is the one the + project's instructions name, else the session asks once; the lookup + reads its remote-tracking ref where one exists, else the local + branch, never fetches, and skips a branch that exists nowhere, + saying so. Argued in *Placement*. +- **D23** — A declined confirmation of a branch ticket falls through to + the conversation and then to `none`, never to a second question; one + answer about a branch's ticket serves the review and the + ticket-frontmatter rule for the rest of the session, is not + recorded, and is stated in the workflow rule's *Branch naming*. + Argued in *Review reports*. +- **D18** — The glossary gains *Ticket root*, *Ticket directory*, + *Process document*, *Companion document*, *Class suffix* and *Class + directory*, minted in the grilling session of 2026-10-27; *Process + directory* names the ticket root among its exclusions, and *Review + report* admits a ticket directory's `code-review/`. + Argued in *Modes*. + +## The setting + +`ticket.root` is a team key in `SETTINGS_REGISTRY.md`, read by the +lifecycle, workflow, ticket-frontmatter, review-reports and +process-artifacts rules and by the python-standards and +salesforce-standards review commands, asked by process-setup. Its name +says what it decides; `dir.` is taken by mode keys and `docs.` would read as kin of +`docs-branch.merge`. + +Every key today takes enumerated values, and three places rely on that: +the loader's `valid_value` and `do_set`, the registry test, and +process-setup's choices. The registry gains one non-enumerated token, +`values: `, with `default: unset`. The loader accepts a `` +value when it starts with `docs/`, names at least one segment after it, +contains no `..` segment and no trailing `/`, and neither equals nor +lies inside a Process directory (`docs/specs/`, `docs/code-review/`, +and the rest the process-artifacts rule lists); the settings grammar +already bars spaces and glob characters. The registry test admits the +token, and process-setup asks the question as free text. + +The root lies under `docs/` because every lookup the process runs +already searches `docs/`: process-status's commands, the `ticket:` +sweep, the `revises:` lookup and the ticket-frontmatter rule's +`docs/**` load. A root elsewhere would force a settings path into +published commands. Process-status's commands therefore stay as they +are; only its `description:`, which names the class directories as +where it looks, gains the ticket directories, or the skill would not +trigger for a status pass over a ticket. + +## Placement + +With `ticket.root` set, a new design spec, technical design or plan +whose `ticket:` yields a file prefix goes into the ticket directory +`/-/`, named by the document-names convention. The +prefix rule is that convention's. A ticket value yielding no prefix, +or `none`, leaves the document in its class directory. + +Before creating a directory the session looks for one. It lists the +root's immediate subdirectories whose name starts with `-`, +ignoring case — the trailing hyphen keeps `abc-14-` from matching +`abc-1489-` — in the working tree, listed from the repository's top +level (`git rev-parse --show-toplevel`), and on the integration branch +with `git ls-tree --full-tree -d --name-only /`; without +`--full-tree` the path is read from the current directory, and a run +below the top level prints nothing and exits 0. The integration branch +is the one topic branches are cut from, as the project's instructions +name it; where they do not, the session asks once — a document's +`base:` cannot serve, since the lookup runs before the document +exists. `` is its remote-tracking ref (`origin/develop`) where +one exists, else the local branch; the session never fetches, which +stays with the developer, and a branch that exists nowhere skips the +second lookup and says so. The second lookup exists because a ticket's +directory may exist only on another branch, and git would merge a +second one in silently. + +One match is used whatever its topic. No match: the session creates +the directory, with the topic of the creating document. Ticket +directories count among the project's ticket-named files of the +document-names convention, so a file prefix and a new directory take +the case the existing ones use — in the client project, lower case +(`abc-12-old/abc-12-login-spec.md`) — and with none, the tracker's. +Several matches, or a `ticket:` list of several keys, go to the +developer, who picks one of the existing directories; while one +exists, the question offers no new directory, which anti-goal 1 rules +out. Where no listed ticket has a directory, the developer picks the +ticket whose directory is created. A review command +asks before dispatch, a session before it writes the document. + +## Recognising a process document + +The rules for judged documents and plans load on suffix globs anchored +at `docs/`, beside their directory globs, which stay for documents +named before the document-names convention: + +| rule | added glob | +|---|---| +| `spec-plan-lifecycle.md` | `docs/**/*-{spec,technical-design,plan}.md` | +| `propagation-duties.md` | `docs/**/*-{spec,technical-design,plan}.md` | +| `process-artifacts.md` | `docs/**/*-{spec,technical-design,plan}.md` | +| `technical-design.md` | `docs/**/*-technical-design.md` | + +Anchoring at `docs/` keeps the globs off files elsewhere in the repo. +The cost to every project, opted in or not: a file under `docs/` named +`*-plan.md` now loads these rules when read. + +A ticket directory holds files a developer names freely; the client +project already has a `screens-spec.md` there. The lifecycle rule says: +with `ticket.root` set, a process document opens with frontmatter +carrying `status:`; a file without it — matched by a class suffix or lying in a class directory — +belongs to the developer, and the process neither adds frontmatter to +it nor reports it, as the glossary's *Process document* says. + +Suffix globs fire only on a correctly named file, and the naming rule +itself is path-scoped: the lifecycle rule loads on the first Write of a +matching file, which is the write that creates a new directory. The +lookup that keeps a ticket to one directory must therefore load before +it. The workflow rule, which always loads, already says where +documents go; it gains: with `ticket.root` set and a ticket, in the +root's subdirectory whose name starts with `-`, ignoring case, +in the working tree or on the integration branch — several go to the +developer — and only with none in a new `/-/`, +named by the lifecycle rule — and it ends by requiring the session to +read the spec-plan-lifecycle rule before creating a ticket directory, +since that rule holds the lookup's commands and cannot be counted on to +have loaded yet. The workflow rule already requires the same read of a +plan-writing brief for the same reason. + +`decision-coverage.py` resolves links relative to the document it is +given and finds nothing on its own; its one directory assumption is +`is_technical_design()`, which requires a `docs/technical-designs/` +parent. A technical design in a ticket directory carries `spec:`, so +the script would audit it as a plan. The test also accepts a name +ending in `-technical-design.md`. + +The ticket-frontmatter rule picks a field set by directory; it picks it +by class, read from the name or the class directory. + +## Companion documents + +A companion document — any file in a ticket directory that is neither +a process document nor a review report — needs neither `ticket:` nor +`date:`: the directory names the ticket and git keeps the dates. It may +carry frontmatter of its own; the process leaves it untouched. +Process documents in a ticket directory keep their full frontmatter, +which the process reads. The ticket-frontmatter rule's backfill — the +block it adds to an edited document that has none — skips, with +`ticket.root` set, every file D8's gate excludes and every companion +document (D9); every other +document under `docs/` is backfilled as today. + +## Modes + +The glossary's *Process directory* is deliberately narrow, and the +ticket root joins its exclusions: the root and its ticket directories +are tracked by the definition of `ticket.root`, never asked about, and +no `dir.*` key reaches a document inside them. `dir.docs/specs: +ignored` keeps governing design specs without a ticket. The process +writes no `.gitignore` under the root, and what the project's own +ignore rules exclude there — a `docs/jira/*/test-data/` line, say — it +respects and may still write to; it never force-adds such a file. The +process-artifacts rule says so in one sentence. + +The rules lean on six new terms — *Ticket root*, *Ticket directory*, +*Process document*, *Companion document*, *Class suffix*, *Class +directory* — minted in the glossary by the grilling session of +2026-10-27. The same session sharpened *Judged document*: the lifecycle +rule branches on the class, and a class suffix only detects it. + +## Links + +A frontmatter link is relative to the document that holds it. In a +ticket directory the documents of one chain are siblings +(`spec: ./ABC-123-login-spec.md`); a link from a ticket directory to a +class directory climbs further (`../../specs/…`). The lifecycle rule's +`../specs/.md` examples read as relative links, not as templates. + +## Review reports + +The review-reports rule gains one placement rule. With `ticket.root` +set, a report whose ticket the current branch name gives goes to +`/code-review/`. + +The branch scheme lives in the workflow rule's *Branch naming*, which +always loads and already owns branch names; the review-reports and +ticket-frontmatter rules point to it. With `ticket.root` set, the +process reads a branch name as `[/][-]`: an optional +single segment of any type (`feature/`, `bugfix/`, `hotfix/`), then a +key shape — letters, a hyphen and digits (`ABC-123`), or digits alone +(`42`, which the prefix rule turns into `ticket-42`) — then an optional +slug. `feature/ABC-123-login`, `bugfix/ABC-1-x`, `ABC-123` and +`hotfix/42-crash` all fit. The section's "fixes the shape and not the +spelling" still holds: a project spells its keys as it likes, and the +process reads only the names that take this shape. Without +`ticket.root`, branch sourcing is unchanged. + +In an interactive session a review places its report by this table: + +| the branch name | the report goes to | +|---|---| +| fits the scheme, and the key's ticket directory exists | the ticket directory, no question | +| fits the scheme, no ticket directory (`feature/phase-2-cleanup`) | `docs/code-review/`, no question | +| carries a letters-hyphen-digits shape outside the scheme (`fix-for-ABC-123`, `release-ABC-123`) | asks for the ticket; an existing ticket directory for the answer takes the report, else `docs/code-review/` | +| carries no key shape (`feature/ticket-directories`) | `docs/code-review/`, no question | + +Digits alone count as a key only at the scheme's key position, so +`feature/oauth2-login` or `chore/v1.2-migration` asks nothing. A run +with no interactive dispatcher writes to `docs/code-review/` whatever +the branch (D20). The one question is a named exception to the +review-reports rule's "a review run never blocks on a question", made +only in an interactive session. + +The table decides placement only. The report's `ticket:` field derives +as the review-reports rule derives it today — from context or the +branch, else `none` — with the row-3 answer and the session's answer +about the branch counting as context. A review on `feature/ABC-77-login` +before the ticket's directory exists keeps `ticket: ABC-77` in +`docs/code-review/`; one on `feature/phase-2-cleanup` may carry +`ticket: PHASE-2` there, which creates nothing. A review never creates +a ticket directory: a ticket's directory appears with its first process +document. + +The ticket-frontmatter rule sources a new document's ticket from the +branch name before the conversation, reading it by the same scheme. +With `ticket.root` set, a ticket read from the branch whose ticket +directory does not exist yet is stated and confirmed with the +developer before the document is written — `feature/phase-2-cleanup` +and `release/2026-10-27` fit the scheme and name no ticket. This is the +sourcing order's one question for the unit of work, never a second: a +declined confirmation falls through to the conversation and then to +`none`, never to another question. One answer about a branch's ticket +serves both rules for the rest of the session; nothing is recorded, +and a fresh session or a compaction may ask again. That sentence lives +in *Branch naming* beside the scheme, since the two rules that use the +answer load on different globs. + +The review command resolves the directory before dispatch, as it +already runs the first-create check before dispatch: it looks for the +ticket directory in the working tree only and hands the agent the +report directory's path. A review creates no directory, so the +integration-branch lookup, which exists to prevent a second one, has +nothing to guard; a directory present only on another branch sends the +report to `docs/code-review/`. An interactive solo run resolves the +directory the same way before it writes: resolving a directory is not +generating a file name, so the rule that file-name generation runs no +shell command and asks nothing still holds. Several matching +directories are asked about before dispatch in an interactive session; +a run with no interactive dispatcher writes to `docs/code-review/`, +like a report whose branch names no ticket — a detached HEAD in CI, +among others. Nothing blocks an unattended run. + +`/code-review/` inherits the ticket directory's +tracked mode, so no first-create question is asked, and a review that +writes there skips the `docs/code-review/` first-create check and the +local pocket. A numeric key from a branch fills `ticket:` as the +ticket-frontmatter rule writes it (`"#42"`), while its prefix is +`ticket-42`. A solo run follows the same placement through the +review-reports rule, which its Contract probe reads; a standards +plugin installed without the working-process rules sees no +`ticket.root` and writes to `docs/code-review/`. A local-only +report — one the local pocket would hold — always goes to +`docs/code-review/`, since the pocket works by writing a `.gitignore` +and the process writes none under the ticket root. The rule's `paths:` +gains `docs/**/code-review/**`. The python-standards and +salesforce-standards commands, agents, code-review skills and READMEs +name `docs/code-review/` as the only location; each learns that the +dispatch names the directory. + +## Moving a document + +A document written without a ticket may later belong to one. On the +developer's command the session moves it into the ticket directory; the +procedure lives in the lifecycle rule, since the rule already loads +when the session opens the document. + +1. The ticket is the document's `ticket:` value, or the command's when + that is `none`; several tickets go to the developer. +2. The session finds the chain — the documents the moved one links to + and those that link to it, by `spec:`, `technical-design:`, + `revises:` and `**Follows:**` — and offers to move them together. +3. Each moved file takes the convention's full name in the ticket + directory, keeping its own topic; a file named before the + convention gains its class suffix, and its topic is its name + without a leading date and a trailing `-design`, or its whole stem + where neither is there. A tracked file moves with `git mv`; an + untracked one — uncommitted, or in an ignored class directory — + with `mv`, and nothing is staged, since committing stays with the + developer. +4. The session rewrites these references: inbound and outbound + frontmatter links, the `with:` file in `integrity:`, `**Follows:**` + lines and qualified decision identifiers (`.md#D3`) in bodies. + A body edit an `implemented` document would need stops the move and + goes to the developer; the frontmatter of an `implemented` document + may change, since the `integrity:` hash covers the body only. + A rewritten path changes no content, so the move asks for no new + audit: where a document's `integrity:` hashes — its own `sha:` and + any `with:` hash — matched its body before the move, the session + recomputes them with the lifecycle rule's hash command after the + rewrite and keeps the audit date. A hash that did not match before + the move stays as it was, since recomputing it would stamp edits + nobody audited. +5. References outside `docs/` and paths in body prose are listed, + never rewritten. +6. The session reports every path it rewrote and every reference it + left alone, and names each untracked file that now lies in the + tracked ticket directory. + +## Verification + +- Loader tests cover the `` value: valid, outside `docs/`, `..`, + trailing `/`. +- A `test_decision_coverage.py` case audits a technical design outside + `docs/technical-designs/` as a technical design. +- A dogfood in a scratch project with `ticket.root: docs/jira` and one + existing `abc-12-old/` directory: a spec for `ABC-12` lands in it; a + spec for `ABC-77` creates `abc-77-/`; a `screens-spec.md` + without `status:` stays untouched; a dated spec with `ticket: ABC-77` + moves with its plan and every link resolves, an `integrity:` stamp + that matched before the move matches after it; a review on + `feature/ABC-12-x` writes to `abc-12-old/code-review/`, so does one + on `bugfix/ABC-12-y` and one on `ABC-12`; one on + `feature/phase-2-cleanup` writes to `docs/code-review/` without a + question and creates no directory; one on `fix-for-ABC-12` asks, and + "ABC-12" sends it to `abc-12-old/code-review/`. +- In a project without `ticket.root`, the dogfood's ticketless flow + writes to the class directories as today. + +## Out of scope + +- Nesting ticket directories below the root's first level. +- Changing `ticket.root` moves nothing: new documents go under the new + root, and directories under the old one are moved by hand, outside + the process. +- Detecting broken links after a manual move; the move procedure keeps + links whole instead. +- A skill for the move; it returns only if sessions skip the procedure's + steps in practice. + +## Changes by file + +- `SETTINGS_REGISTRY.md` — the `ticket.root` entry; the `` value + token in the preamble. +- `scripts/load-settings.sh` — `` validation in `valid_value` and + `do_set`. +- `tests/working-process/test_settings_registry.py`, + `test_load_settings.py` — the token, the new key, the path cases. +- `skills/process-setup/SKILL.md` — a free-text question. +- `rules/spec-plan-lifecycle.md` — the suffix glob, placement, the + `status:` gate, relative links, the move procedure. +- `rules/technical-design.md`, `rules/propagation-duties.md`, + `rules/process-artifacts.md` — the suffix globs; process-artifacts + also the ticket-root exclusion; technical-design also its "lives in + `docs/technical-designs/`" sentence, which a ticket directory + overrides. +- `README.md` of working-process — the directories it lists. +- `rules/workflow.md` — where a ticket's documents go; the branch + scheme and the shared session answer in *Branch naming*. +- `rules/ticket-frontmatter.md` — field sets by class; the backfill + skips every file D8's gate excludes and every companion document; + branch sourcing by the D19 scheme. +- `rules/review-reports.md` — ticket placement of reports, the one + interactive question as an exception to "never blocks on a question", + the `docs/**/code-review/**` glob. +- `scripts/decision-coverage.py`, `tests/working-process/test_decision_coverage.py` + — the suffix test. +- `skills/process-status/SKILL.md` — the ticket directories in its + description (*The setting*). +- `docs/domain/glossary.md` — done in the grilling session and its + fix wave: six new terms, the Process directory exclusion, the + *Judged document* sentence, the *Review report* location. +- python-standards and salesforce-standards — the review command + resolves the report directory before dispatch and hands its path to + the agent; the agent, the code-review skill's location line and the + README stop naming `docs/code-review/` as the only location. +- `CHANGELOG.md` of each changed plugin. + +## Calls made by the author + +- D5: ticket directories count among the ticket-named files, so a file + and its directory share the key case; with none yet, the tracker's + case, where the system-designer consultation suggested lower case. +- A ticket value yielding no prefix is treated as no ticket. +- D21 recomputes only hashes that matched before the move, so a move + never stamps unaudited edits. +- D20: an unattended run, or an ambiguity nobody can answer, writes + to `docs/code-review/`, matching the CI non-goal. +- A move stages nothing and names each untracked file that now lies + in the tracked ticket directory. +- The loader refuses a `ticket.root` equal to or inside a Process + directory. +- Several matching directories offer only the existing ones. +- With `ticket.root` set, the `status:` gate holds in class directories too. +- A numeric branch key fills `ticket:` as `"#42"`, with the prefix + `ticket-42`. +- A review writing to a ticket directory skips the `docs/code-review/` + first-create check and the local pocket; a standalone standards + install writes to `docs/code-review/`. +- A legacy file's topic is its name without a leading date and a + trailing `-design`. + +## Review rounds + +### 2026-10-27 — integrity audit, fable, at the consumption gate + +- fixed 2026-10-27 — the plan-adversary's F5 found the backfill exemption narrower than D8's gate; ruling: 2026-10-27; *Companion documents* and *Changes by file* exempt every file the gate excludes, the stamp's hash recomputed without a new audit +- fixed 2026-10-27 — the plan-adversary's M9 found the F5 sentence folding D9's exemption into D8's gate; license: D9; *Companion documents* and *Changes by file* name the two exemptions separately, the stamp's hash recomputed without a new audit + +- fixed 2026-10-27 — closures of the audit's dispositions, found after the stamp: D6 had no outcome for a ticket list none of whose tickets has a directory; D8 lagged the gate's extension to class directories; move steps 4 and 5 lagged D17; three wrapped lines; ruling: 2026-10-27; D6, *Placement*, D8 and steps 4–5 amended, the stamp's hash recomputed without a new audit + +- fixed 2026-10-27 — D19 asked about any key shape outside the scheme, the body only about letters-hyphen-digits; license: R4-3; D19 narrowed +- fixed 2026-10-27 — D19's "gives no ticket" contradicted the report's `ticket:` field; license: R4-2's ruling; D19 speaks of placement and leaves the field to its derivation +- fixed 2026-10-27 — D17 promised every reference, the procedure lists some; license: *Moving a document*; D17 names what is rewritten and what is listed +- fixed 2026-10-27 — the integration-branch lookup read a `base:` of a document not yet written; license: *Recognising a process document* (the lookup precedes the write); the project's instructions or one question +- fixed 2026-10-27 — the integration-branch procedure and the declined-confirmation and session-answer rules had no register entry; license: the register's own rule; D22 and D23 +- fixed 2026-10-27 — the process-status change had no argument; license: *The setting*; the description gains the ticket directories, argued there +- fixed 2026-10-27 — `rules/technical-design.md`'s location sentence was missing from *Changes by file*; license: *Placement*; listed, with the working-process README +- fixed 2026-10-27 — the move had no path for an uncommitted file in a tracked class directory; license: the lifecycle rule (documents stay uncommitted while authored); any untracked file moves with `mv`, nothing staged +- fixed 2026-10-27 — eight implementer questions answered as author's calls: the root's Process-directory guard, existing-only choice on several matches, the gate in class directories, numeric keys, skipped checks in a ticket directory, solo and standalone runs, legacy topics, the README +- fixed 2026-10-27 — the final code review found the gate unscoped while the backfill exemption was scoped, against goal 4; ruling: 2026-10-27; option (b) — D8, *Recognising a process document*, *Companion documents* and *Calls made* scope the gate to ticket.root, the stamp's hash recomputed without a new audit + +### 2026-10-27 — architect, fable 5.1, concerns (round 4, diff-scoped) + +- fixed 2026-10-27 — [Minor] R4-1: D14 placed a report only by the branch's ticket, while row 3 places it by the developer's answer; license: D19; D14 adds "or the developer names for it (D19)" +- fixed 2026-10-27 — [Minor] R4-2: the report's `ticket:` field was undefined for rows 1, 2 and 4; ruling: 2026-10-27; option (i) — the table decides placement only, the field derives as today with the row-3 and session answers as context +- fixed 2026-10-27 — [Minor] R4-3: "digits alone" made row 3 ask on `feature/oauth2-login`; license: R3-2's ruling (a name that suggests a ticket); row 3 counts only the letters-hyphen-digits shape, and digits alone count only at the key position +- fixed 2026-10-27 — [Minor] R4-4: no rule owned the shared session answer; license: R3-1 (the always-loaded owner); the sentence lives in *Branch naming*, listed in *Changes by file* + +Resolved without a fresh round: four single-sentence fixes; no decision moved beyond R4-2's ruling. + +### 2026-10-27 — architect, fable 5.1, blocking (round 3, diff-scoped) + +- fixed 2026-10-27 — [Important] R3-1: the branch scheme sat in review-reports, while the workflow rule's *Branch naming* owns branch names and ticket-frontmatter defers to it; license: D19 ("one definition"); the scheme moves to *Branch naming*, reconciled with "fixes the shape and not the spelling", and the other two rules point to it +- fixed 2026-10-27 — [Important] R3-2: row 2's question changed nothing, and review-reports says a review never asks; ruling: 2026-10-27; option (a) — row 2 goes to `docs/code-review/` without a question, the one remaining question (row 3) is a named interactive exception whose answer also sets the report's `ticket:` +- fixed 2026-10-27 — [Minor] R3-3: the table's unattended column sent row 1 to the ticket directory against D20; license: D20 and the CI non-goal; the column is replaced by one sentence +- fixed 2026-10-27 — [Minor] R3-4: `jan/abc-123-fix` fits the scheme yet was listed outside it; license: D19; the example is `fix-for-ABC-123` +- fixed 2026-10-27 — [Minor] R3-5: no fall-through after a declined confirmation, and no shared answer between the two rules; license: ticket-frontmatter's "never ask twice"; a decline falls through to the conversation and `none`, and one answer serves both rules for the session +- fixed 2026-10-27 — [Minor] R3-6: the scheme changed branch sourcing in projects without `ticket.root`; license: goal 4; the scheme applies only with `ticket.root` set + +### 2026-10-27 — architect, fable 5.1, concerns (round 2, diff-scoped) + +- fixed 2026-10-27 — [Minor] R2-1: F1's fix put the lookup duty in the always-loaded workflow rule but left its commands in the lifecycle rule, which loads too late; license: D11; the workflow clause ends by requiring a read of the spec-plan-lifecycle rule before creating a ticket directory, the pattern the workflow rule already uses for a plan-writing brief +- fixed 2026-10-27 — [Minor] R2-2: the glossary's *Dispatch record* still located a review report under `docs/code-review/`; license: D18 and F3; the appositive names no location +- fixed 2026-10-27 — the reviewer's integrity note: D14 sent a local-only report to the ticket directory, and D20 had a solo run hand an agent the path; license: F2's ruling and F8; D14 excepts local-only reports, D20 separates the dispatched and the solo run + +Resolved without a fresh round: both findings and the note are wording; no decision moved. + +- fixed 2026-10-27 — D19 read a ticket only after `feature/`, so `bugfix/ABC-1-x` or a bare `ABC-123` branch lost its ticket; ruling: 2026-10-27; D19 and *Review reports* define the scheme `[/][-]`, ask about a name outside it or without a ticket directory, and the ticket-frontmatter rule's branch sourcing reads the same scheme +- fixed 2026-10-27 — the branch-sourced ticket of a new document had no guard, so `feature/phase-2-cleanup` would give a spec `ticket: PHASE-2` and create its directory; ruling: 2026-10-27; with `ticket.root` set, a branch ticket without a ticket directory is confirmed before the document is written (D19, *Review reports*) + +### 2026-10-27 — architect, fable 5.1, blocking (round 1, full-document) + +- fixed 2026-10-27 — [Important] F1: the lookup guarding anti-goal 1 sat in a path-scoped rule that loads only on the write creating the directory; license: anti-goal 1 and D4; D11 and *Recognising a process document* put the reuse of an existing ticket directory into the always-loaded workflow rule +- fixed 2026-10-27 — [Important] F2: the local pocket writes a `.gitignore`, which D10 and the glossary's *Ticket root* forbid under the root; ruling: 2026-10-27; option (a) — a local-only report always goes to `docs/code-review/` (D20, *Review reports*), D10 keeps no exception +- fixed 2026-10-27 — [Minor] F3: the glossary's *Review report* tied the report to `docs/code-review/`; license: D14; the entry admits a ticket directory's `code-review/`, D18 and *Changes by file* say so +- fixed 2026-10-27 — [Minor] F4: *Process document* recognised a document by its class suffix alone, excluding every document named before the convention; license: *Recognising a process document* (directory globs stay); the glossary entry and D7 add the class directory +- fixed 2026-10-27 — [Minor] F5: `git ls-tree` without `--full-tree` prints nothing below the top level and exits 0; license: anti-goal 1 and D4; *Placement* prescribes `--full-tree` and lists the working tree from `git rev-parse --show-toplevel` +- fixed 2026-10-27 — [Minor] F6: the review lookup carried the integration-branch check, which guards only directory creation; license: D19 (a review never creates a directory); *Review reports* and D20 look in the working tree only +- fixed 2026-10-27 — [Minor] F7: `read-by:` of `ticket.root` omitted the two review commands; license: D20 and the `dir.docs/code-review` precedent; *The setting* names them +- fixed 2026-10-27 — [Minor] F8: a solo review run had no step before writing; license: D14; *Review reports* and D20 have a solo run resolve the directory before it writes +- fixed 2026-10-27 — [Minor] F9: the brace-glob probe checks documented platform behaviour; license: the Claude Code memory docs (brace expansion, `src/**/*.{ts,tsx}`); the probe and its fallback are dropped from *Verification* +- fixed 2026-10-27 — *Ticket root* said every immediate subdirectory is a ticket directory, which a `templates/` subdirectory contradicts; ruling: 2026-10-27; the entry says the root holds the ticket directories diff --git a/plugins/python-standards/.claude-plugin/plugin.json b/plugins/python-standards/.claude-plugin/plugin.json index d7177ee..9395a08 100644 --- a/plugins/python-standards/.claude-plugin/plugin.json +++ b/plugins/python-standards/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "python-standards", "description": "Python coding standards for the uv + ruff + pytest + pyright toolchain: six area skills, a code-review stack (python-code-review skill, python-code-reviewer agent, /python-review command) writing review reports to docs/code-review/, a python-plan-review checklist for plan reviews, and a python-toolchain rule shipped as a Rules payload", - "version": "0.4.0", + "version": "0.5.0", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["python", "standards", "uv", "ruff", "pytest", "pyright", "typer", "fastapi", "review"] diff --git a/plugins/python-standards/CHANGELOG.md b/plugins/python-standards/CHANGELOG.md index 2fbff15..b6da90f 100644 --- a/plugins/python-standards/CHANGELOG.md +++ b/plugins/python-standards/CHANGELOG.md @@ -2,6 +2,15 @@ Released versions of this plugin, newest first. +## 0.5.0 — 2026-11-13 + +- Agent cards forbid reading a credential's value or writing one into a + command; a check that needs authentication nobody provided is + reported as not checked. +- `/python-review` places a ticket's report in the ticket directory's + `code-review/` when the working-process `ticket.root` is set; + otherwise reports stay in `docs/code-review/`. + ## 0.4.0 — 2026-09-29 - `/python-review` reads the settings key `dir.docs/code-review` from a diff --git a/plugins/python-standards/README.md b/plugins/python-standards/README.md index 88a5b51..8c8d5d7 100644 --- a/plugins/python-standards/README.md +++ b/plugins/python-standards/README.md @@ -24,10 +24,11 @@ Each skill ships `reference/` examples alongside its SKILL.md. - **`python-code-review` skill** — audits Python code against the standards skills; writes one review report per run to - `docs/code-review/`. + `docs/code-review/`, or to a ticket directory's `code-review/` when + the working-process rules place it there. - **`python-code-reviewer` agent** — reviews a diff or named files, - writes the report to `docs/code-review/`, returns findings by - severity. + writes the report to the directory the command resolved, returns + findings by severity. - **`/python-review` command** — review the current diff or named files. Python files only; out-of-domain files are noted as out of scope. diff --git a/plugins/python-standards/agents/python-code-reviewer.md b/plugins/python-standards/agents/python-code-reviewer.md index 826d19f..993cb3d 100644 --- a/plugins/python-standards/agents/python-code-reviewer.md +++ b/plugins/python-standards/agents/python-code-reviewer.md @@ -1,6 +1,6 @@ --- name: python-code-reviewer -description: "Reviews Python code — a diff or named files — against the python-standards skills, writes the review report to docs/code-review/, and returns findings by severity. Python files only; out-of-domain files are noted in the report Summary as out of scope." +description: "Reviews Python code — a diff or named files — against the python-standards skills, writes the review report to the directory the dispatch prompt names, and returns findings by severity. Python files only; out-of-domain files are noted in the report Summary as out of scope." --- Code reviewer for Python. FIRST ACTION: load the `python-code-review` @@ -11,7 +11,12 @@ skills, severity grading, the Contract probe, and report writing. given files; nothing else. - One run, one report — this agent is the run's owner (`mode: agent` when the shared review-reports contract applies). +- Write the report to the directory the dispatch prompt names; the + prompt names none → `docs/code-review/`. - Never stage or commit the report. +- Never read a credential's value — `gh auth token`, a token or key + file, a keyring — or write one into a command. Report a check that + needs authentication the dispatch did not provide as not checked. - Reply with the report path and the findings grouped Critical → Important → Minor, then the candidate-gap list and offers per the skill's step 5; zero findings is still a written report and a stated diff --git a/plugins/python-standards/commands/python-review.md b/plugins/python-standards/commands/python-review.md index bc9eb99..05852fd 100644 --- a/plugins/python-standards/commands/python-review.md +++ b/plugins/python-standards/commands/python-review.md @@ -9,7 +9,17 @@ this session. 1. Resolve the scope: `$ARGUMENTS` when given (named files); otherwise the current diff — staged plus unstaged changes, or, on a clean tree, the diff of the current branch against its base. -2. Pre-dispatch first-create check, gated on the contract probe: +2. Resolve the report directory, gated on the same contract probe + as step 3. A review the developer requests as local-only uses + `docs/code-review/`, whatever the branch. Otherwise, with the + contract found, `ticket.root` set in a settings + block in context and the session interactive, resolve it from the + working tree only, as the review-reports rule's *Ticket-directory + placement* prescribes, and pass the agent its absolute path. + In any other case — no `ticket.root`, a Standalone install, an + unattended run — use `docs/code-review/`. A report bound for a + ticket directory skips step 3. +3. Pre-dispatch first-create check, gated on the contract probe: check `/.claude/rules/working-process/review-reports.md`, then `$HOME/.claude/rules/working-process/review-reports.md` — first hit wins (paths owned by the review-reports contract; @@ -28,19 +38,20 @@ this session. which stands, nothing changed until they answer; the key with no visible signal is applied unasked, the ignored mode by writing the `*` `.gitignore`. -3. Dispatch the `python-code-reviewer` agent in the BACKGROUND with +4. Dispatch the `python-code-reviewer` agent in the BACKGROUND with the resolved scope. Python files only (`*.py`, `pyproject.toml`); the agent notes out-of-domain files in the report Summary as out of scope and writes the one report itself (`mode: agent` under the installed contract). The dispatch prompt carries the scope, the prior report's runid for a rerun (`rerun-of`), and the - directory-mode decision from step 2 — never report-shaping + report directory from step 2 and the directory-mode decision + from step 3 — never report-shaping instructions of its own: aggregation and counting policy, layout, and severity policy belong to the contract and the reviewer's skill, and a whole-project scope is no exception. -4. Tell the developer: the review is running in the background; the +5. Tell the developer: the review is running in the background; the summary arrives as a task notification, not inline; progress via - `/tasks`; the report will land under `docs/code-review/`. -5. When the run's notification arrives, relay its reply to the + `/tasks`; the report will land in the directory resolved in step 2. +6. When the run's notification arrives, relay its reply to the developer: report path, findings by severity, and the candidate-gap offers verbatim. diff --git a/plugins/python-standards/skills/python-code-review/SKILL.md b/plugins/python-standards/skills/python-code-review/SKILL.md index 9ff1147..1680201 100644 --- a/plugins/python-standards/skills/python-code-review/SKILL.md +++ b/plugins/python-standards/skills/python-code-review/SKILL.md @@ -101,7 +101,9 @@ When the Contract probe finds nothing, this minimal contract applies — a strict subset of the shared review-reports contract, never a different shape: -- **Location**: `/docs/code-review/`; create the +- **Location**: the directory the run resolved: `docs/code-review/`, or + a ticket directory's `code-review/`. The dispatch prompt names it; + with no prompt, `/docs/code-review/`. Create the directory if absent (the first-create mode question belongs to working-process's process-artifacts rule and is absent in a Standalone install). diff --git a/plugins/salesforce-standards/.claude-plugin/plugin.json b/plugins/salesforce-standards/.claude-plugin/plugin.json index 08ce1a1..810544b 100644 --- a/plugins/salesforce-standards/.claude-plugin/plugin.json +++ b/plugins/salesforce-standards/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "salesforce-standards", "description": "Salesforce coding standards for the sf CLI + Code Analyzer + Prettier-Apex + sfdx-lwc-jest toolchain: nine area skills (Apex, Apex triggers, Apex testing, LWC, Flow, data model, security model, maintenance-first Aura and Visualforce), a code-review stack (salesforce-code-review skill, salesforce-code-reviewer agent, /salesforce-review command) writing review reports to docs/code-review/, a salesforce-plan-review checklist for plan reviews, and a salesforce-toolchain rule shipped as a Rules payload", - "version": "0.5.0", + "version": "0.6.0", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["salesforce", "standards", "apex", "triggers", "lwc", "flow", "aura", "visualforce", "sf-cli", "review"] diff --git a/plugins/salesforce-standards/CHANGELOG.md b/plugins/salesforce-standards/CHANGELOG.md index 303f6ff..1601271 100644 --- a/plugins/salesforce-standards/CHANGELOG.md +++ b/plugins/salesforce-standards/CHANGELOG.md @@ -2,6 +2,15 @@ Released versions of this plugin, newest first. +## 0.6.0 — 2026-11-13 + +- Agent cards forbid reading a credential's value or writing one into a + command; a check that needs authentication nobody provided is + reported as not checked. +- `/salesforce-review` places a ticket's report in the ticket + directory's `code-review/` when the working-process `ticket.root` is + set; otherwise reports stay in `docs/code-review/`. + ## 0.5.0 — 2026-09-29 - `/salesforce-review` reads the settings key `dir.docs/code-review` diff --git a/plugins/salesforce-standards/README.md b/plugins/salesforce-standards/README.md index 4ab2e7b..727a02e 100644 --- a/plugins/salesforce-standards/README.md +++ b/plugins/salesforce-standards/README.md @@ -44,10 +44,11 @@ document. - **`salesforce-code-review` skill** — audits Salesforce code and metadata against the standards skills; writes one review report per - run to `docs/code-review/`. + run to `docs/code-review/`, or to a ticket directory's `code-review/` + when the working-process rules place it there. - **`salesforce-code-reviewer` agent** — reviews a diff or named - files, writes the report to `docs/code-review/`, returns findings by - severity. + files, writes the report to the directory the command resolved, + returns findings by severity. - **`/salesforce-review` command** — review the current diff or named files. Salesforce files only; out-of-domain files are noted as out of scope. diff --git a/plugins/salesforce-standards/agents/salesforce-code-reviewer.md b/plugins/salesforce-standards/agents/salesforce-code-reviewer.md index 81eead8..661b9cb 100644 --- a/plugins/salesforce-standards/agents/salesforce-code-reviewer.md +++ b/plugins/salesforce-standards/agents/salesforce-code-reviewer.md @@ -1,6 +1,6 @@ --- name: salesforce-code-reviewer -description: "Reviews Salesforce code and metadata — a diff or named files — against the salesforce-standards skills, writes the review report to docs/code-review/, and returns findings by severity. Salesforce files only; out-of-domain files are noted in the report Summary as out of scope." +description: "Reviews Salesforce code and metadata — a diff or named files — against the salesforce-standards skills, writes the review report to the directory the dispatch prompt names, and returns findings by severity. Salesforce files only; out-of-domain files are noted in the report Summary as out of scope." --- Code reviewer for Salesforce. FIRST ACTION: load the @@ -12,7 +12,12 @@ and report writing. given files; nothing else. - One run, one report — this agent is the run's owner (`mode: agent` when the shared review-reports contract applies). +- Write the report to the directory the dispatch prompt names; the + prompt names none → `docs/code-review/`. - Never stage or commit the report. +- Never read a credential's value — `gh auth token`, a token or key + file, a keyring — or write one into a command. Report a check that + needs authentication the dispatch did not provide as not checked. - Reply with the report path and the findings grouped Critical → Important → Minor, then the candidate-gap list and offers per the skill's step 5; zero findings is still a written report and a stated diff --git a/plugins/salesforce-standards/commands/salesforce-review.md b/plugins/salesforce-standards/commands/salesforce-review.md index b978a79..87d2c21 100644 --- a/plugins/salesforce-standards/commands/salesforce-review.md +++ b/plugins/salesforce-standards/commands/salesforce-review.md @@ -17,7 +17,17 @@ review must never block this session. the directory-mode decision; the agent verifies it against the declarations on disk. Where step (c) resolved the framework, offer to write the declaration before dispatching. -3. Pre-dispatch first-create check, gated on the contract probe: +3. Resolve the report directory, gated on the same contract probe + as step 4. A review the developer requests as local-only uses + `docs/code-review/`, whatever the branch. Otherwise, with the + contract found, `ticket.root` set in a settings + block in context and the session interactive, resolve it from the + working tree only, as the review-reports rule's *Ticket-directory + placement* prescribes, and pass the agent its absolute path. + In any other case — no `ticket.root`, a Standalone install, an + unattended run — use `docs/code-review/`. A report bound for a + ticket directory skips step 4. +4. Pre-dispatch first-create check, gated on the contract probe: check `/.claude/rules/working-process/review-reports.md`, then `$HOME/.claude/rules/working-process/review-reports.md` — first hit wins (paths owned by the review-reports contract; @@ -36,20 +46,21 @@ review must never block this session. which stands, nothing changed until they answer; the key with no visible signal is applied unasked, the ignored mode by writing the `*` `.gitignore`. -4. Dispatch the `salesforce-code-reviewer` agent in the BACKGROUND +5. Dispatch the `salesforce-code-reviewer` agent in the BACKGROUND with the resolved scope. Salesforce files only, per the skill's run scope; the agent notes out-of-domain files in the report Summary as out of scope and writes the one report itself (`mode: agent` under the installed contract). The dispatch prompt carries the scope, the prior report's runid for a rerun - (`rerun-of`), the resolution record from step 2, and the - directory-mode decision from step 3 — never report-shaping + (`rerun-of`), the resolution record from step 2, the report + directory from step 3, and the directory-mode decision from + step 4 — never report-shaping instructions of its own: aggregation and counting policy, layout, and severity policy belong to the contract and the reviewer's skill, and a whole-project scope is no exception. -5. Tell the developer: the review is running in the background; the +6. Tell the developer: the review is running in the background; the summary arrives as a task notification, not inline; progress via - `/tasks`; the report will land under `docs/code-review/`. -6. When the run's notification arrives, relay its reply to the + `/tasks`; the report will land in the directory resolved in step 3. +7. When the run's notification arrives, relay its reply to the developer: report path, findings by severity, and the candidate-gap offers verbatim. diff --git a/plugins/salesforce-standards/skills/salesforce-code-review/SKILL.md b/plugins/salesforce-standards/skills/salesforce-code-review/SKILL.md index 0d9f83a..87d1a0d 100644 --- a/plugins/salesforce-standards/skills/salesforce-code-review/SKILL.md +++ b/plugins/salesforce-standards/skills/salesforce-code-review/SKILL.md @@ -162,7 +162,9 @@ When the Contract probe finds nothing, this minimal contract applies — a strict subset of the shared review-reports contract, never a different shape: -- **Location**: `/docs/code-review/`; create the +- **Location**: the directory the run resolved: `docs/code-review/`, or + a ticket directory's `code-review/`. The dispatch prompt names it; + with no prompt, `/docs/code-review/`. Create the directory if absent (the first-create mode question belongs to working-process's process-artifacts rule and is absent in a Standalone install). diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index 37b3e92..bbb9e25 100644 --- a/plugins/working-process/.claude-plugin/plugin.json +++ b/plugins/working-process/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "working-process", "description": "Spec-driven working process on top of superpowers: grilling-session, architect-session, system-designer-session, process-status, process-setup and sync-rules skills, architect and plan-adversary verdict agents, architect-consult and system-designer-consult consultation agents, propagation-auditor and integrity-auditor audit agents, and process rules distributed as a Rules payload; domain plugins hook in via *-plan-review checklist skills and their own rules/ payloads", - "version": "0.18.0", + "version": "0.19.0", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 4cb99be..04cea26 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -2,6 +2,24 @@ Released versions of this plugin, newest first. +## 0.19.0 — 2026-11-13 + +- New design specs, technical designs and plans are named + `--.md`: the ticket key (`ABC-123`, + `ticket-42`) or, without a ticket, the date, then the topic and + `spec`, `technical-design` or `plan`. Existing documents keep their + names. +- Agent cards and the workflow rule forbid reading a credential's value + or writing one into a command; a check that needs authentication + nobody provided is reported as not checked. +- An opt-in team settings key, `ticket.root` (a path under `docs/`), + moves a ticket's documents into its ticket directory. With it set, a + new design spec, technical design or plan for a ticket goes there, a + document's class is recognised by its file-name suffix, a document + written without a ticket can move into a ticket directory with its + chain, and code-review reports for a ticket go to the directory's + `code-review/`. + ## 0.18.0 — 2026-09-29 - New `technical-design` rule: a third document class between the design diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index 8574572..c60972f 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -319,6 +319,12 @@ A tracked-mode `docs/code-review/` additionally carries a `.gitignore` with `local-*` — the local pocket for reports the developer keeps out of git. +With `ticket.root` set, the ticket root (a directory the project names) +holds one ticket directory per ticket. A ticket's design spec, +technical design and plan go to its ticket directory, and so does a +review report whose ticket the branch name gives, in `code-review/` +beside them. + ## Project memory The in-repo Project memory store ships as its own plugin, `project-memory` diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index 3a1c37d..c0a214d 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -8,7 +8,8 @@ and nothing more. The shape is fixed so that `sed` and the test parse it without a Markdown parser: one `## ` heading per key, then exactly these five fields, one per line, in this order — `scope:` (`team` or `personal`), `values:` (the -allowed values, separated by ` | `), `default:` (a value, or `unset` +allowed values, separated by ` | `, or the token ``, a +directory under `docs/` that the loader checks — see `ticket.root`), `default:` (a value, or `unset` where the rule asks), `read-by:` (the files that read the key, comma-separated, relative to `plugins/`) and `question:` (what the skill asks, and the comment `--set` writes above the key). A `dir.` @@ -128,3 +129,11 @@ values: yes | no default: unset read-by: working-process/rules/workflow.md, working-process/rules/spec-plan-lifecycle.md question: May the review loop commit the reviewed document once per round? + +## ticket.root + +scope: team +values: +default: unset +read-by: working-process/skills/process-setup/SKILL.md, working-process/rules/spec-plan-lifecycle.md, working-process/rules/technical-design.md, working-process/rules/process-artifacts.md, working-process/rules/workflow.md, working-process/rules/ticket-frontmatter.md, working-process/rules/review-reports.md, python-standards/commands/python-review.md, salesforce-standards/commands/salesforce-review.md +question: Which directory under docs/ holds one directory per ticket, if the project keeps them? diff --git a/plugins/working-process/agents/architect-consult.md b/plugins/working-process/agents/architect-consult.md index 9a2f125..38e24aa 100644 --- a/plugins/working-process/agents/architect-consult.md +++ b/plugins/working-process/agents/architect-consult.md @@ -52,3 +52,6 @@ worth more to the developer than a confident answer built on it. domain-expertise duty often requires it. Never spawn another working-process persona: two personas reconciled inside one answer hand back one opinion where the developer asked for two. +- Never read a credential's value — `gh auth token`, a token or key + file, a keyring — or write one into a command. Report a check that + needs authentication the dispatch did not provide as not checked. diff --git a/plugins/working-process/agents/architect.md b/plugins/working-process/agents/architect.md index 94251c9..80e498d 100644 --- a/plugins/working-process/agents/architect.md +++ b/plugins/working-process/agents/architect.md @@ -65,3 +65,6 @@ this field; it is stamped only after THIS agent's review. rollout) — plan-adversary owns that. - Rewriting the reviewed document. - Padding the findings list or grading style. +- Reading a credential's value — `gh auth token`, a token or key file, + a keyring — or writing one into a command. Report a check that needs + authentication the dispatch did not provide as not checked. diff --git a/plugins/working-process/agents/integrity-auditor.md b/plugins/working-process/agents/integrity-auditor.md index f730806..fe1485b 100644 --- a/plugins/working-process/agents/integrity-auditor.md +++ b/plugins/working-process/agents/integrity-auditor.md @@ -192,3 +192,6 @@ at all. project set another — and re-running it here spends the tier on arithmetic. - Prose quality, naming taste, and style. +- Reading a credential's value — `gh auth token`, a token or key file, + a keyring — or writing one into a command. Report a check that needs + authentication the dispatch did not provide as not checked. diff --git a/plugins/working-process/agents/plan-adversary.md b/plugins/working-process/agents/plan-adversary.md index 84e3804..0a61f7a 100644 --- a/plugins/working-process/agents/plan-adversary.md +++ b/plugins/working-process/agents/plan-adversary.md @@ -29,6 +29,9 @@ contradicting a glossary term or a recorded ADR is a finding naming, docs. When a domain checklist assigns a severity to its rule, that severity wins — never re-grade it. - One finding per issue. No filler. No claims without a citation. +- Never read a credential's value — `gh auth token`, a token or key + file, a keyring — or write one into a command. Report a check that + needs authentication the dispatch did not provide as not checked. ## Domain checklists diff --git a/plugins/working-process/agents/propagation-auditor.md b/plugins/working-process/agents/propagation-auditor.md index cddfcb5..e19d4e1 100644 --- a/plugins/working-process/agents/propagation-auditor.md +++ b/plugins/working-process/agents/propagation-auditor.md @@ -60,6 +60,9 @@ reliance and is re-dispatched at the right rung. count is the thing under audit, never the evidence for it. - Report what you found and stop there: no severity, no ranking, no advice on the design. +- Never read a credential's value — `gh auth token`, a token or key + file, a keyring — or write one into a command. Report a check that + needs authentication the dispatch did not provide as not checked. ## Duties — walk every one below; each is a class measured in a real loop diff --git a/plugins/working-process/agents/system-designer-consult.md b/plugins/working-process/agents/system-designer-consult.md index 216bcdd..131a26d 100644 --- a/plugins/working-process/agents/system-designer-consult.md +++ b/plugins/working-process/agents/system-designer-consult.md @@ -50,3 +50,6 @@ more to the developer than a confident proposal built on it. domain-expertise duty often requires it. Never spawn another working-process persona: two personas reconciled inside one answer hand back one opinion where the developer asked for two. +- Never read a credential's value — `gh auth token`, a token or key + file, a keyring — or write one into a command. Report a check that + needs authentication the dispatch did not provide as not checked. diff --git a/plugins/working-process/rules/process-artifacts.md b/plugins/working-process/rules/process-artifacts.md index 9189772..3beb8e2 100644 --- a/plugins/working-process/rules/process-artifacts.md +++ b/plugins/working-process/rules/process-artifacts.md @@ -3,6 +3,7 @@ paths: - "docs/specs/**" - "docs/plans/**" - "docs/technical-designs/**" + - "docs/**/*-{spec,technical-design,plan}.md" - "docs/domain/**" - "docs/code-review/**" - ".superpowers/**" @@ -79,6 +80,12 @@ that rule reads its own exception, `dir.docs/memory`, in the same order — it is listed above only so `docs/memory/` counts as a Process directory for the conventions below. +With `ticket.root` set, the ticket root and its ticket directories are +not Process directories: they are tracked, with no first-create question, +no `.gitignore` written by the process and no `dir.*` key reaching them. +The process respects ignores the project sets inside them and never +force-adds a file. + ## Handling artifacts - Tracked mode: artifact updates ride along with the commits of the work diff --git a/plugins/working-process/rules/propagation-duties.md b/plugins/working-process/rules/propagation-duties.md index 651e19a..6a878b9 100644 --- a/plugins/working-process/rules/propagation-duties.md +++ b/plugins/working-process/rules/propagation-duties.md @@ -3,6 +3,7 @@ paths: - "docs/specs/**" - "docs/technical-designs/**" - "docs/plans/**" + - "docs/**/*-{spec,technical-design,plan}.md" - "docs/domain/**" --- diff --git a/plugins/working-process/rules/review-reports.md b/plugins/working-process/rules/review-reports.md index e8af1d5..f598289 100644 --- a/plugins/working-process/rules/review-reports.md +++ b/plugins/working-process/rules/review-reports.md @@ -1,20 +1,23 @@ --- paths: - "docs/code-review/**" + - "docs/**/code-review/**" --- # Review reports The domain-agnostic contract for code-review reports. It binds any -writer to `docs/code-review/` — the review stacks of standards plugins +writer to `docs/code-review/` (or, with `ticket.root` set, a ticket +directory's `code-review/`; see *Ticket-directory placement*) — the review stacks of standards plugins are its primary consumers, not its only ones. This rule supersedes any inline fallback format a domain plugin's review skill carries for standalone installs. ## Location and directory mode -Review reports live in `/docs/code-review/` — a Process -directory; its ignored-vs-tracked mode comes from the first-create +Review reports live in `/docs/code-review/` (or, with +`ticket.root` set, a ticket directory's `code-review/`; see +*Ticket-directory placement*) — a Process directory; its ignored-vs-tracked mode comes from the first-create question (process-artifacts rule). Who asks depends on who can: - An interactive run (`mode: solo`) asks the first-create question as @@ -33,6 +36,47 @@ question (process-artifacts rule). Who asks depends on who can: This is safe because reports are never staged (see Committing); the next interactive touch asks per the process-artifacts rule. +## Ticket-directory placement + +With `ticket.root` set, a report whose ticket the branch name gives goes +to `/code-review/`. The workflow rule's *Branch +naming* owns the branch scheme and the session-answer sentence; the +spec-plan-lifecycle rule's *Ticket directories* owns the ticket +directory and its lookup. In an interactive session a review places its +report by this table: + +| the branch name | the report goes to | +|---|---| +| fits the scheme, and the key's ticket directory exists | the ticket directory, no question | +| fits the scheme, no ticket directory (`feature/phase-2-cleanup`) | `docs/code-review/`, no question | +| carries a letters-hyphen-digits shape outside the scheme (`fix-for-ABC-123`, `release-ABC-123`) | asks for the ticket; an existing ticket directory for the answer takes the report, else `docs/code-review/` | +| carries no key shape (`feature/ticket-directories`) | `docs/code-review/`, no question | + +Digits alone count as a key only at the scheme's key position, so +`feature/oauth2-login` asks nothing. A run with no interactive +dispatcher writes to `docs/code-review/` whatever the branch, as does a +run whose branch matches several ticket directories; an interactive +session asks which one. Nothing blocks an unattended run. + +- The command resolves the directory before dispatch, looking in the + working tree only (a directory present only on another branch sends + the report to `docs/code-review/`), and hands the agent the report + directory as an absolute path. An interactive solo run resolves it + the same way before it writes, through this rule, which the Contract + probe reads. +- A review never creates a ticket directory. +- `/code-review/` inherits the ticket directory's + tracked mode: no first-create question is asked, and the report + skips the `docs/code-review/` first-create check and the local + pocket. +- A local-only report always goes to `docs/code-review/`, because the + pocket works by writing a `.gitignore` and the process writes none + under the ticket root. +- A numeric key from a branch fills `ticket:` as the ticket-frontmatter + rule writes it (`"#42"`); its prefix is `ticket-42`. +- A standards plugin installed without the working-process rules sees + no `ticket.root` and writes to `docs/code-review/`. + ## One run, one report Each review run writes exactly one report, written by the run's owner @@ -78,7 +122,11 @@ findings: { critical: 0, important: 2, minor: 5 } only when a new run-owner kind actually ships. - `ticket`: derive from context or branch, else `none` — a review run never blocks on a question. This is a deliberate exception to the - ticket-frontmatter rule's ask-once step for new documents. + ticket-frontmatter rule's ask-once step for new documents. With + `ticket.root` set, the row-3 answer and the session's answer about + the branch count as context; the one interactive question in + *Ticket-directory placement* is the only exception to "never blocks + on a question", and only in an interactive session. - `scope`: what was reviewed, matching the filename slug. - `runid`: this run's id, matching the filename. - `standards`: what the run reviewed against — a single standards-plugin @@ -229,6 +277,9 @@ keeping is simply deleted. ## Local pocket (tracked mode only) +With `ticket.root` set, a report written to a ticket directory has no +pocket; this section covers `docs/code-review/` only. + When `docs/code-review/` resolves to tracked mode — by the first-create question, or unasked by a signal or a settings key, in the order the process-artifacts rule gives — also write `docs/code-review/.gitignore` diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 1a170e3..2e84f36 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -3,13 +3,29 @@ paths: - "docs/specs/**" - "docs/technical-designs/**" - "docs/plans/**" + - "docs/**/*-{spec,technical-design,plan}.md" --- # Judged documents and plans — frontmatter and lifecycle Design specs live in `docs/specs/`, technical designs in -`docs/technical-designs/`, plans in `docs/plans/`. All three open with a -YAML frontmatter block: +`docs/technical-designs/`, plans in `docs/plans/`. + +A new document is named `--.md`. The prefix is +the ticket key when the document has a ticket: `ticket-` for a +numeric key (`ticket-42`), otherwise the key in the case the project's +ticket-named files already use, or the tracker's case where none exist +yet (`ABC-123`). Without a ticket the prefix is the ISO creation date +(`2026-07-13`). The class is `spec`, `technical-design` or `plan`, so +one topic's documents never share a name and each name tells its class. +A second design spec for the same ticket takes its own topic +(`ABC-123-login-errata-spec.md`). Documents named before this +convention keep their names. When the superpowers brainstorming or +writing-plans skill writes the document, these names override its +default file name. With `ticket.root` set, a document for a ticket goes +to a ticket directory: see *Ticket directories*. + +All three open with a YAML frontmatter block: ```yaml --- @@ -167,6 +183,95 @@ base: master # optional: branch the topic branch was cut from section with its `**Defers:**` and `**Follows:**` lines. The rest of the template stays with that tool. +## Ticket directories + +With `ticket.root` set, a new design spec, technical design or plan +whose `ticket:` yields a file prefix goes into the ticket directory +`/-/`, one level below the ticket root and named as +above. A ticket value yielding no prefix, or `none`, leaves the document +in its class directory. + +Before creating a directory, look for one. List the root's immediate +subdirectories whose name starts with `-`, ignoring case; the +trailing hyphen keeps `abc-14-` from matching `abc-1489-`. Search two +places: + +- the working tree, listed from the repository's top level + (`git rev-parse --show-toplevel`); +- the integration branch, with + `git ls-tree --full-tree -d --name-only /`. Without + `--full-tree` git reads the path from the current directory, and a run + below the top level prints nothing and exits 0. + +The integration branch is the one topic branches are cut from, as the +project's instructions name it; where they name none, ask once. A +document's `base:` cannot serve, since the lookup runs before the +document exists. `` is the branch's remote-tracking ref +(`origin/develop`) where one exists, else the local branch. Never fetch: +that stays with the developer. A branch that exists nowhere skips the +second lookup; say so. + +One match is used whatever its topic. With no match, create the +directory with the topic of the creating document. A file prefix and a +new directory take the case the project's existing ticket-named files +and directories use, else the tracker's case. Several matches, or a +`ticket:` list of several keys, go to the developer, who picks one of +the existing directories; while one exists, offer no new directory. Where +no listed ticket has a directory, the developer picks the ticket whose +directory is created. A review command asks before dispatch, a session +before it writes the document. + +With `ticket.root` set, a process document opens with frontmatter +carrying `status:`. A file matching a class suffix or lying in a class +directory, but without `status:` in its frontmatter, is not a process +document: it belongs to the developer, and the process neither adds +frontmatter to it nor reports it. + +Frontmatter links are relative to the document that holds them. In a +ticket directory the documents of one chain are siblings +(`spec: ./ABC-123-login-spec.md`); a link from a ticket directory to a +class directory climbs further (`../../specs/.md`). The +`../specs/.md` examples in the frontmatter block above read as +relative links, not as templates. + +### Moving a document into a ticket directory + +With `ticket.root` set, a document written without a ticket may later +belong to one. Move it only on the developer's command, never on the +session's initiative. Six steps: + +1. **Ticket.** Take the document's `ticket:` value, or the command's + when that value is `none`. Where several tickets apply, ask which one. +2. **Chain.** Find the documents the moved one links to and those that + link to it, by `spec:`, `technical-design:`, `revises:` and + `**Follows:**`. Offer to move them together, as one move. +3. **Names and moving.** Each moved file takes the convention's full + name in the ticket directory and keeps its own topic. A file named + before the convention gains its class suffix; its topic is its name + without a leading date and a trailing `-design`, or its whole stem + where neither is there. Move a tracked file with `git mv`, an + untracked one (uncommitted, or in an ignored class directory) with + `mv`; nothing is staged, since committing stays with the developer. +4. **References.** Before any rewrite, compare each affected + document's `integrity:` hashes (its own `sha:` and any `with:` hash) + with the bodies as they stand, and note which matched. Then rewrite + inbound and outbound frontmatter links, the `with:` file in + `integrity:`, `**Follows:**` lines, and qualified decision + identifiers (`.md#D3`) in bodies. A body edit that an + `implemented` document would need stops the move and goes to the + developer; its frontmatter may change, since the `integrity:` hash + covers the body only. +5. **Hashes.** A rewritten path changes no content, so the move asks + for no new audit. Recompute after the rewrite, with the hash command + above, only a hash noted in step 4 as one that + matched its body before the move, and keep the audit date. A hash + that did not match stays as it was: recomputing it would stamp edits + nobody audited. +6. **Report.** References outside `docs/` and paths in body prose are + listed, never rewritten. Report every path rewritten, every + reference left alone, and each untracked file that now lies in the + tracked ticket directory. + ## Decision register A design spec that sets `decisions: registered` carries a `## Decisions` diff --git a/plugins/working-process/rules/technical-design.md b/plugins/working-process/rules/technical-design.md index 7b7aea6..111147d 100644 --- a/plugins/working-process/rules/technical-design.md +++ b/plugins/working-process/rules/technical-design.md @@ -1,14 +1,17 @@ --- paths: - "docs/technical-designs/**" + - "docs/**/*-technical-design.md" --- # Technical design — what the thing is made of A technical design answers what a thing is made of, as its design spec answers what and why and the implementation plan answers in what order -and verified how. It lives in `docs/technical-designs/`, one file per -design spec, named `-technical-design.md`. +and verified how. It lives in `docs/technical-designs/`, one file per design +spec, named as the spec-plan-lifecycle rule names documents, with +the class `technical-design`. With `ticket.root` set and a ticket, it +lives where that rule's *Ticket directories* says. The boundary against the design spec runs between identity and placement. The design spec names parts by the name their consumers use diff --git a/plugins/working-process/rules/ticket-frontmatter.md b/plugins/working-process/rules/ticket-frontmatter.md index 48e6293..8cce912 100644 --- a/plugins/working-process/rules/ticket-frontmatter.md +++ b/plugins/working-process/rules/ticket-frontmatter.md @@ -15,6 +15,10 @@ GitLab, or anything else; the field is always `ticket`. `docs/technical-designs/`, `docs/plans/`): `ticket` + `date` + `status` + the process and branch fields — details in the spec-plan-lifecycle rule. +- With `ticket.root` set, the class — class suffix or class directory — + chooses this set, not the directory a file lies in. A companion + document in a ticket directory is exempt from `ticket` and `date`, and + its own frontmatter is left untouched. - Review reports (`docs/code-review/`): the review-reports rule's frontmatter set — `date`, `mode`, `ticket`, `scope`, `runid`, `standards`, optional `rerun-of`, `findings` — not the bare @@ -50,23 +54,35 @@ GitLab, or anything else; the field is always `ticket`. ## Sourcing and backfill -For a NEW document: branch name (`feature/ABC-123-...`) → conversation -context → ask the developer once; no answer means `none`. Never ask twice -for one unit of work — a technical design and a plan inherit their -design spec's ticket, and artifacts -of the same session reuse the established value. The branch naming +For a NEW document: branch name (`feature/ABC-123-...`; with +`ticket.root` set, read by the scheme in the workflow rule's +*Branch naming*) → conversation context → ask the developer once; no +answer means `none`. Never ask twice for one unit of work — a technical +design and a plan inherit their design spec's ticket, and artifacts of +the same session reuse the established value. The branch naming convention that produces the names this order reads is the workflow rule's, which is where a branch is cut — before any `docs/` file of that work exists, and so before this rule loads. Where a branch name yields no usable reference, the order above simply falls through to its next source, as it does for any work whose branch carries none. +With `ticket.root` set, a branch ticket whose ticket directory does +not exist yet is stated and confirmed before the document is written — +the one question of the order. A declined confirmation falls through to +the conversation and then to `none`, never to a second question +(*Branch naming* holds the rule). + When editing an existing `docs/` document that has no frontmatter, add the block as part of the edit — sourced from document content → branch → conversation → `none`, never a question (asking is reserved for new documents). `date` is the file's git creation date: `git log --follow --format=%as -- | tail -1`. +With `ticket.root` set, the backfill skips every file the `status:` gate +excludes — a file matching a class suffix or lying in a class directory +without `status:` — and every companion document in a ticket directory; +every other document under `docs/` is backfilled as today. + ## Finding documents by ticket The `ticket:` line matches both single-reference and inline-list forms; diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 1df1cf6..149f9de 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -6,8 +6,9 @@ disables its suggestion — never the work itself. 1. **Idea → spec.** When the superpowers:brainstorming skill is available, start non-trivial features there; capture the agreed design - as a spec in `docs/specs/`. When the working-process consult agents - (`architect-consult`, `system-designer-consult`) are available, ask + as a spec in `docs/specs/` (with `ticket.root` set, see the + ticket-directory paragraph below). When the working-process consult + agents (`architect-consult`, `system-designer-consult`) are available, ask once, early in the design conversation, whether the two personas should be consulted as the design forms — unless `consult.personas`, read as the process-settings rule says, is set, which answers it @@ -125,7 +126,7 @@ disables its suggestion — never the work itself. has passed, leaving no confirmed hit, when that agent is available. Then write the implementation plan with superpowers:writing-plans when available; - plans live in `docs/plans/`. A brief that delegates plan-writing to a + plans live in `docs/plans/` (or the ticket directory, below). A brief that delegates plan-writing to a separate context names the spec-plan-lifecycle rule and requires reading it before the plan is written: that rule carries the annotations a plan owes a registered design spec, and a separate @@ -151,6 +152,15 @@ disables its suggestion — never the work itself. whatever review surface the matched plugin ships, and that surface owns scope resolution, dispatch, and the report. +With `ticket.root` set, a new design spec, technical design or plan +whose `ticket:` yields a file prefix goes into the root's subdirectory +whose name starts with `-`, ignoring case, in the working tree +or on the integration branch. Several matches go to the developer. Only +with none does it go into a new `/-/`, named by +the spec-plan-lifecycle rule's *Ticket directories*. Read that rule +before creating a ticket directory: it holds the lookup's commands, and +a path-scoped rule has not loaded before the first file is written. + Both audits offered above run in the background, so a gated dispatch waits for its audit's task notification before it is issued — a sequencing rule rather than a blocking call, running on the relay @@ -224,6 +234,12 @@ run an explicit editing pass over the changed prose of an existing one. The pass binds wording, never decisions. Without the skill there is no substitute pass and no install nagging — the work proceeds normally. +## Credentials + +Never read a credential's value — `gh auth token`, a token or key file, +a keyring — or write one into a command. Report a check that needs +authentication the developer did not provide as not checked. + ## Branch naming Feature work happens on a topic branch named @@ -244,6 +260,23 @@ spec-plan-lifecycle rule names and which is a sibling of it rather than a second topic branch. The ticket rule's sourcing order reads the current branch name first when a new document needs a ticket. +With `ticket.root` set, the process reads a branch name as +`[/][-]`: an optional one-segment `` (`feature/`, +`bugfix/`, `hotfix/`), then a `` — letters, a hyphen and digits +(`ABC-123`), or digits alone (`42`) — then an optional slug. +`feature/ABC-123-login`, `ABC-123` and `hotfix/42-crash` fit. Digits +alone count only at the key position, so `feature/oauth2-login` names +no key. The convention above still fixes the shape and not the +spelling: a project spells its keys as it likes, and the process reads +only the names that take this shape. + +With `ticket.root` set, the integration branch is the one the project's +instructions name, else the session asks once. A declined confirmation +of a branch's ticket falls through to the conversation and then to +`none`, never to a second question. One answer about a branch's ticket +serves every rule that reads it for the rest of the session; nothing is +recorded, and a fresh session or a compaction may ask again. + ## Dispatching a verdict agent Dispatching a verdict agent (`architect`, `plan-adversary`), when diff --git a/plugins/working-process/scripts/decision-coverage.py b/plugins/working-process/scripts/decision-coverage.py index 1ee3c1d..a014919 100755 --- a/plugins/working-process/scripts/decision-coverage.py +++ b/plugins/working-process/scripts/decision-coverage.py @@ -554,9 +554,10 @@ def audit_spec(display: str, lines: list[str]) -> list[str]: def is_technical_design(display: str) -> bool: - """The resolved path has `docs/technical-designs/` among its parents.""" + """The resolved path has `docs/technical-designs/` among its parents, or + the file name ends in `-technical-design.md` (a ticket directory's design).""" parts = Path(os.path.abspath(display)).parts - return any(a == "docs" and b == "technical-designs" + return parts[-1].endswith("-technical-design.md") or any(a == "docs" and b == "technical-designs" for a, b in zip(parts, parts[1:])) diff --git a/plugins/working-process/scripts/load-settings.sh b/plugins/working-process/scripts/load-settings.sh index 98546e9..969f93e 100755 --- a/plugins/working-process/scripts/load-settings.sh +++ b/plugins/working-process/scripts/load-settings.sh @@ -204,7 +204,16 @@ AWK_PROG=' } file_label = ENVIRON["FL"] } + function valid_path(val, n, parts, i) { + if (val !~ /^[A-Za-z0-9._\/-]+$/) return 0 + if (val !~ /^docs\/./ || val ~ /\/$/) return 0 + n = split(val, parts, "/") + for (i = 1; i <= n; i++) if (parts[i] == "" || parts[i] == "..") return 0 + if (val ~ /^docs\/(specs|technical-designs|plans|domain|code-review|memory)(\/|$)/) return 0 + return 1 + } function valid_value(val, padded, needle) { + if (padded == " ") return valid_path(val) needle = " " val " " return index(padded, needle) > 0 } @@ -749,6 +758,25 @@ apply_write() { esac } +# A ticket-root path: the awk valid_path rules, character class first. +path_value_ok() { + case $1 in + *[!A-Za-z0-9._/-]*) return 1 ;; + docs/?*) ;; + *) return 1 ;; + esac + case "/$1/" in + *//* | */../*) return 1 ;; + esac + case $1 in + */) return 1 ;; + docs/specs | docs/specs/* | docs/technical-designs | docs/technical-designs/* \ + | docs/plans | docs/plans/* | docs/domain | docs/domain/* \ + | docs/code-review | docs/code-review/* | docs/memory | docs/memory/*) return 1 ;; + esac + return 0 +} + # do_set : validates the key and value against # the registry (nothing is created before both pass), then plans and, # unless dry, applies the write, then, on a real write, prints a blank @@ -775,9 +803,13 @@ do_set() { s_values=$(registry_field "$s_key" values) || return 1 s_values_norm=$(printf '%s' "$s_values" | sed 's/ | / /g') || return 1 s_value_ok=0 - for s_v in $s_values_norm; do - if [ "$s_v" = "$s_value" ]; then s_value_ok=1; break; fi - done + if [ "$s_values_norm" = "" ]; then + path_value_ok "$s_value" && s_value_ok=1 + else + for s_v in $s_values_norm; do + if [ "$s_v" = "$s_value" ]; then s_value_ok=1; break; fi + done + fi if [ "$s_value_ok" -eq 0 ]; then # shellcheck disable=SC2016 printf 'error: invalid value for `%s`: %s (allowed: %s)\n' "$s_key" "$s_value" "$s_values" >&2 diff --git a/plugins/working-process/skills/process-setup/SKILL.md b/plugins/working-process/skills/process-setup/SKILL.md index e9a011d..716d126 100644 --- a/plugins/working-process/skills/process-setup/SKILL.md +++ b/plugins/working-process/skills/process-setup/SKILL.md @@ -66,6 +66,10 @@ ones: ask `dir.default`, then offer exceptions only when the developer asks for them, `dir.docs/memory` among them. A candidate from step 1 the developer confirmed is an answer and is not asked again. +A key whose registry `values:` is ``, such as `ticket.root`, takes +a free-text answer: offer "leave unset" first, then accept a path the +loader validates. + A team's suggestion for a personal key is the one line `--set` never writes: where the developer wants one, say that it goes into `settings.md` by hand, and that diff --git a/plugins/working-process/skills/process-status/SKILL.md b/plugins/working-process/skills/process-status/SKILL.md index 2e275d5..653bedf 100644 --- a/plugins/working-process/skills/process-status/SKILL.md +++ b/plugins/working-process/skills/process-status/SKILL.md @@ -1,6 +1,6 @@ --- name: process-status -description: "Report what the working process left unfinished in this repo — a pending grilling, an unresolved verdict, a re-review nobody ran, a stamp in the wrong place. Use when the developer asks what is unfinished, what the process still owes, or for a status pass over docs/specs, docs/technical-designs and docs/plans." +description: "Report what the working process left unfinished in this repo — a pending grilling, an unresolved verdict, a re-review nobody ran, a stamp in the wrong place. Use when the developer asks what is unfinished, what the process still owes, or for a status pass over docs/specs, docs/technical-designs and docs/plans, and over ticket directories where the project keeps them." --- # process-status — what the process left unfinished diff --git a/tests/working-process/test_decision_coverage.py b/tests/working-process/test_decision_coverage.py index 611fb71..45be0fc 100644 --- a/tests/working-process/test_decision_coverage.py +++ b/tests/working-process/test_decision_coverage.py @@ -625,6 +625,30 @@ def test_13_technical_design_produces_no_output(self): self.assertEqual(proc.stdout, "") self.assertEqual(proc.stderr, "") + def test_13b_technical_design_in_ticket_directory_produces_no_output(self): + (self.root / "docs" / "specs").mkdir(parents=True) + (self.root / "docs" / "jira" / "abc-12-x").mkdir(parents=True) + self.write("docs/specs/s.md", SPEC_BASIC) + design = dedent("""\ + --- + spec: ../../specs/s.md + --- + + # S — technical design + + Text. + """) + self.write("docs/jira/abc-12-x/abc-12-x-technical-design.md", design) + proc = subprocess.run( + [sys.executable, SCRIPT, + str(self.root / "docs" / "jira" / "abc-12-x" / "abc-12-x-technical-design.md")], + capture_output=True, + text=True, + ) + self.assertEqual(proc.returncode, 0, proc.stderr) + self.assertEqual(proc.stdout, "") + self.assertEqual(proc.stderr, "") + # 14 def test_14_plan_under_plans_is_still_counted(self): (self.root / "docs" / "specs").mkdir(parents=True) diff --git a/tests/working-process/test_load_settings.py b/tests/working-process/test_load_settings.py index 6abb381..d473950 100644 --- a/tests/working-process/test_load_settings.py +++ b/tests/working-process/test_load_settings.py @@ -25,6 +25,7 @@ "dir.docs/domain", "dir.docs/code-review", "dir..superpowers", "dir.docs/memory", "design.technical-design-offer", "dispatch.propagation-auditor-tier", "docs-branch.merge", "consult.personas", "review.autonomy", "review.per-round-commit", + "ticket.root", ] @@ -158,6 +159,31 @@ def test_precedence_and_defaults(self) -> None: printed = self.run_loader(self.root, "--print") self.assertEqual(printed.out, res.out) + def test_ticket_root_path_values(self) -> None: + self.git_init() + res = self.run_loader(self.root, "--set", "ticket.root", "docs/jira") + self.assertEqual(res.code, 0) + self.assertEqual(self.run_loader(self.root).line("ticket.root"), "ticket.root: docs/jira [team]") + for ok in ("docs/tickets/active", "docs/specs-archive"): + with self.subTest(ok=ok): + self.assertEqual(self.run_loader(self.root, "--set", "ticket.root", ok).code, 0) + self.assertEqual(self.run_loader(self.root).line("ticket.root"), f"ticket.root: {ok} [team]") + bad = ("jira", "docs", "docs/", "docs/jira/", "docs/../jira", "docs/specs", + "docs/code-review/x", "docs/a*b") + for v in bad: + with self.subTest(set=v): + res = self.run_loader(self.root, "--set", "ticket.root", v) + self.assertEqual(res.code, 1) + self.assertIn("error: invalid value for `ticket.root`", res.err) + with self.subTest(hand=v): + root = self.base / "hand" + root.mkdir(exist_ok=True) + self.git_init(root) + self.settings(root, team=f"ticket.root: {v}\n") + res = self.run_loader(root) + self.assertEqual(res.line("ticket.root"), "ticket.root: unset [invalid in team]") + self.assertTrue(res.errors) + # 2. Suggestion. def test_suggestion(self) -> None: self.git_init() diff --git a/tests/working-process/test_settings_registry.py b/tests/working-process/test_settings_registry.py index 630fa4a..967218d 100644 --- a/tests/working-process/test_settings_registry.py +++ b/tests/working-process/test_settings_registry.py @@ -54,14 +54,14 @@ class RegistryShapeTest(unittest.TestCase): def setUp(self) -> None: self.entries = read_registry(REGISTRY) - def test_fourteen_keys_in_order(self) -> None: + def test_fifteen_keys_in_order(self) -> None: self.assertEqual(list(self.entries), [ "dir.default", "dir.docs/specs", "dir.docs/technical-designs", "dir.docs/plans", "dir.docs/domain", "dir.docs/code-review", "dir..superpowers", "dir.docs/memory", "design.technical-design-offer", "dispatch.propagation-auditor-tier", "docs-branch.merge", "consult.personas", "review.autonomy", - "review.per-round-commit", + "review.per-round-commit", "ticket.root", ]) def test_every_entry_is_well_formed(self) -> None: @@ -69,11 +69,12 @@ def test_every_entry_is_well_formed(self) -> None: with self.subTest(key=key): self.assertRegex(key, KEY_RE) self.assertIn(fields["scope"], ("team", "personal")) - values = fields["values"].split(" | ") - self.assertTrue(all(re.fullmatch(r"[A-Za-z0-9._/-]+", v) for v in values), values) - self.assertEqual(len(values), len(set(values))) - self.assertTrue(fields["default"] == "unset" or fields["default"] in values, - fields["default"]) + if fields["values"] != "": # the one non-enumerated shape + values = fields["values"].split(" | ") + self.assertTrue(all(re.fullmatch(r"[A-Za-z0-9._/-]+", v) for v in values), values) + self.assertEqual(len(values), len(set(values))) + self.assertTrue(fields["default"] == "unset" or fields["default"] in values, + fields["default"]) for reader in fields["read-by"].split(", "): self.assertTrue((PLUGINS / reader).is_file(), reader) self.assertTrue(fields["question"].endswith("?"), fields["question"])