From 58e27075fd757c4719f63469a2dbeb7a7c9b250c Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 29 Sep 2026 21:15:09 +0200 Subject: [PATCH 01/36] docs(working-process): process-setup spec and plan implemented --- docs/plans/2026-09-28-process-setup.md | 2 +- docs/specs/2026-09-28-process-setup-design.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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/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) From c4b4193e1e289426582d104b6c27c257ac6c98d4 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 10:59:24 +0100 Subject: [PATCH 02/36] fix: forbid agents from reading or passing credential values --- plugins/python-standards/CHANGELOG.md | 6 ++++++ plugins/python-standards/agents/python-code-reviewer.md | 3 +++ plugins/salesforce-standards/CHANGELOG.md | 6 ++++++ .../salesforce-standards/agents/salesforce-code-reviewer.md | 3 +++ plugins/working-process/CHANGELOG.md | 6 ++++++ plugins/working-process/agents/architect-consult.md | 3 +++ plugins/working-process/agents/architect.md | 3 +++ plugins/working-process/agents/integrity-auditor.md | 3 +++ plugins/working-process/agents/plan-adversary.md | 3 +++ plugins/working-process/agents/propagation-auditor.md | 3 +++ plugins/working-process/agents/system-designer-consult.md | 3 +++ plugins/working-process/rules/workflow.md | 6 ++++++ 12 files changed, 48 insertions(+) diff --git a/plugins/python-standards/CHANGELOG.md b/plugins/python-standards/CHANGELOG.md index 2fbff15..dcca98d 100644 --- a/plugins/python-standards/CHANGELOG.md +++ b/plugins/python-standards/CHANGELOG.md @@ -2,6 +2,12 @@ Released versions of this plugin, newest first. +## Unreleased + +- 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. + ## 0.4.0 — 2026-09-29 - `/python-review` reads the settings key `dir.docs/code-review` from a diff --git a/plugins/python-standards/agents/python-code-reviewer.md b/plugins/python-standards/agents/python-code-reviewer.md index 826d19f..9e406ec 100644 --- a/plugins/python-standards/agents/python-code-reviewer.md +++ b/plugins/python-standards/agents/python-code-reviewer.md @@ -12,6 +12,9 @@ skills, severity grading, the Contract probe, and report writing. - One run, one report — this agent is the run's owner (`mode: agent` when the shared review-reports contract applies). - 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/CHANGELOG.md b/plugins/salesforce-standards/CHANGELOG.md index 303f6ff..7ef46bd 100644 --- a/plugins/salesforce-standards/CHANGELOG.md +++ b/plugins/salesforce-standards/CHANGELOG.md @@ -2,6 +2,12 @@ Released versions of this plugin, newest first. +## Unreleased + +- 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. + ## 0.5.0 — 2026-09-29 - `/salesforce-review` reads the settings key `dir.docs/code-review` diff --git a/plugins/salesforce-standards/agents/salesforce-code-reviewer.md b/plugins/salesforce-standards/agents/salesforce-code-reviewer.md index 81eead8..91f1fa0 100644 --- a/plugins/salesforce-standards/agents/salesforce-code-reviewer.md +++ b/plugins/salesforce-standards/agents/salesforce-code-reviewer.md @@ -13,6 +13,9 @@ and report writing. - One run, one report — this agent is the run's owner (`mode: agent` when the shared review-reports contract applies). - 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/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index 4cb99be..b51074a 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -2,6 +2,12 @@ Released versions of this plugin, newest first. +## Unreleased + +- 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. + ## 0.18.0 — 2026-09-29 - New `technical-design` rule: a third document class between the design 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/workflow.md b/plugins/working-process/rules/workflow.md index 1df1cf6..de2d872 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -224,6 +224,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 From ba6e787df9c66a479b8e5fbc83c09a032f8cfec2 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 10:59:24 +0100 Subject: [PATCH 03/36] chore: enable the ponytail plugin in project settings --- .claude/settings.json | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) 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" + } } } } From a682108e9d65333c225ebdce800a12e6359d75fe Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 12:03:20 +0100 Subject: [PATCH 04/36] feat(working-process): name new documents by ticket or date, topic and class --- plugins/working-process/CHANGELOG.md | 5 +++++ .../rules/spec-plan-lifecycle.md | 18 ++++++++++++++++-- .../working-process/rules/technical-design.md | 3 ++- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index b51074a..b408030 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -4,6 +4,11 @@ Released versions of this plugin, newest first. ## Unreleased +- 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. diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 1a170e3..b1046cd 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -8,8 +8,22 @@ paths: # 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. + +All three open with a YAML frontmatter block: ```yaml --- diff --git a/plugins/working-process/rules/technical-design.md b/plugins/working-process/rules/technical-design.md index 7b7aea6..19729d3 100644 --- a/plugins/working-process/rules/technical-design.md +++ b/plugins/working-process/rules/technical-design.md @@ -8,7 +8,8 @@ paths: 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`. +design spec, named as the spec-plan-lifecycle rule names documents, with +the class `technical-design`. The boundary against the design spec runs between identity and placement. The design spec names parts by the name their consumers use From 5861000c2c5d18b8d197fc2ee5751b3f93973e43 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 13:12:49 +0100 Subject: [PATCH 05/36] docs: ticket directories spec and glossary terms --- docs/domain/glossary.md | 44 +- .../2026-10-27-ticket-directories-spec.md | 412 ++++++++++++++++++ 2 files changed, 454 insertions(+), 2 deletions(-) create mode 100644 docs/specs/2026-10-27-ticket-directories-spec.md diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 9398ad7..e21f647 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, whose immediate subdirectories are 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 @@ -246,9 +269,26 @@ 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 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 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..0042375 --- /dev/null +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -0,0 +1,412 @@ +--- +ticket: none +date: 2026-10-27 +status: draft +grilled: 2026-10-27 +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. Argued in *Placement*. +- **D7** — A process document's class is detected from its name + suffix; 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** — A file matching a class suffix 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. 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 + goes to `/code-review/`; any other report goes to + `docs/code-review/`. Argued in *Review reports*. +- **D19** — A branch names a ticket only when the segment after + `feature/` opens with a key shape — letters, a hyphen and digits, or + digits alone — and a ticket directory for that key already exists; a + review never creates a ticket directory. Argued in *Review reports*. +- **D20** — The review command resolves the report directory before + dispatch and hands the agent the path; a run with no interactive + dispatcher, or an ambiguity nobody can answer, 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** — The move rewrites every reference to and from each moved + file, 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*. +- **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, and + *Process directory* names the ticket root among its exclusions. + 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, 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 `/`; 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. + +## 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, and on the integration branch with +`git ls-tree -d --name-only /`. The integration branch is +the one topic branches are cut from, as the project's instructions or +the document's `base:` name it; where neither names it, the session +asks once. `` 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. + +## 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: +a process document opens with frontmatter carrying `status:`; a file +that matches a class suffix without it belongs to the developer, and +the process neither adds frontmatter to it nor reports it. + +Suffix globs fire only on a correctly named file, and the naming rule +itself is path-scoped. The workflow rule, which always loads, already +says where documents go; it gains: with `ticket.root` set and a ticket, +in `/-/`, named by the lifecycle rule. + +`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. + +## 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/`. A branch names a ticket only when +the segment after `feature/` opens with a key shape — letters, a hyphen +and digits (`ABC-123-login`), or digits alone (`6-salesforce`) — and a +ticket directory for that key, after the prefix rule (`6` gives +`ticket-6`), already exists. The shape alone proves nothing: +`feature/phase-2-cleanup` has it, and no ticket `phase-2` exists. A +review never creates a ticket directory; a ticket's directory appears +with its first process document. + +The review command resolves the directory before dispatch, as it +already runs the first-create check before dispatch: it looks the +ticket directory up by *Placement*'s rules and hands the agent the +report directory's path. The rule that generating a file +name runs no shell command and asks nothing still holds, since the +agent receives a resolved directory. An ambiguity *Placement* would put +to the developer is asked 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; the local pocket +works there as in any tracked report directory. 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. A tracked file moves with + `git mv`; an untracked one, in an ignored class directory, with `mv` + and `git add`. +4. The session rewrites every reference: 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/` are listed, never rewritten. +6. The session reports every path it rewrote and every reference it + left alone, and names each file that was untracked before the move + and is tracked now. + +## Verification + +- A probe confirms, before implementation, that a brace suffix glob + under `docs/` loads a rule when a matching file is read; if braces do + not load, each rule takes one glob per suffix. +- 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/`, and one on + `feature/phase-2-cleanup` writes to `docs/code-review/` and creates no + directory. +- 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. +- `rules/workflow.md` — where a ticket's documents go. +- `rules/ticket-frontmatter.md` — field sets by class; companion + documents in a ticket directory exempt. +- `rules/review-reports.md` — ticket placement of reports, the + branch-ticket shape, 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 directory list in its + description. +- `docs/domain/glossary.md` — done in the grilling session: six new + terms, the Process directory exclusion, the *Judged document* + sentence. +- 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. +- The integration-branch lookup asks once where no instruction names + the branch, reads the remote-tracking ref without fetching, and skips + a branch that exists nowhere. +- D19's key shape for branch names. +- 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 names each file it turns from untracked to tracked. From b93b539bc5d3a059685c322f771b3ab45a41de99 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 13:29:56 +0100 Subject: [PATCH 06/36] docs: ticket directories spec, architect round 1 fixes --- docs/domain/glossary.md | 10 +- .../2026-10-27-ticket-directories-spec.md | 93 +++++++++++++------ 2 files changed, 70 insertions(+), 33 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index e21f647..b43c16d 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -17,7 +17,7 @@ _Avoid_: artifact folder **Ticket root**: The directory under `docs/` that a project names in the `ticket.root` -settings key, whose immediate subdirectories are ticket directories. The +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. @@ -126,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. @@ -275,8 +276,9 @@ _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 together with a frontmatter `status:`; a file with the suffix -alone is not one — in a ticket directory, it is a companion document. +suffix or its class directory, 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**: diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 0042375..f1e14ca 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -3,6 +3,7 @@ ticket: none date: 2026-10-27 status: draft grilled: 2026-10-27 +architect: blocking decisions: registered branch: feature/ticket-directories base: develop @@ -86,8 +87,10 @@ Anti-goals — the change fails, even if it works, when: 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. Argued in *Placement*. -- **D7** — A process document's class is detected from its name - suffix; the rules covering design specs, technical designs and plans +- **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*. @@ -102,7 +105,9 @@ Anti-goals — the change fails, even if it works, when: 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. Argued in *Recognising a process document*. + 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 @@ -115,9 +120,10 @@ Anti-goals — the change fails, even if it works, when: `feature/` opens with a key shape — letters, a hyphen and digits, or digits alone — and a ticket directory for that key already exists; a review never creates a ticket directory. Argued in *Review reports*. -- **D20** — The review command resolves the report directory before - dispatch and hands the agent the path; a run with no interactive - dispatcher, or an ambiguity nobody can answer, writes to +- **D20** — The review command, or a solo run before it writes, + resolves the report directory from the working tree and hands the + agent the path; 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 @@ -133,15 +139,17 @@ Anti-goals — the change fails, even if it works, when: document*. - **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, and - *Process directory* names the ticket root among its exclusions. + 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, asked by process-setup. Its name says what it +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`. @@ -171,8 +179,11 @@ 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, and on the integration branch with -`git ls-tree -d --name-only /`. The integration branch is +`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 or the document's `base:` name it; where neither names it, the session asks once. `` is its remote-tracking ref (`origin/develop`) where @@ -215,9 +226,15 @@ that matches a class suffix without it belongs to the developer, and the process neither adds frontmatter to it nor reports it. Suffix globs fire only on a correctly named file, and the naming rule -itself is path-scoped. The workflow rule, which always loads, already -says where documents go; it gains: with `ticket.root` set and a ticket, -in `/-/`, named by the lifecycle 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, which holds the lookup's details. `decision-coverage.py` resolves links relative to the document it is given and finds nothing on its own; its one directory assumption is @@ -278,19 +295,25 @@ review never creates a ticket directory; a ticket's directory appears with its first process document. The review command resolves the directory before dispatch, as it -already runs the first-create check before dispatch: it looks the -ticket directory up by *Placement*'s rules and hands the agent the -report directory's path. The rule that generating a file -name runs no shell command and asks nothing still holds, since the -agent receives a resolved directory. An ambiguity *Placement* would put -to the developer is asked before dispatch in an interactive session; a -run with no interactive dispatcher writes to `docs/code-review/`, +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; the local pocket -works there as in any tracked report directory. The rule's `paths:` +tracked mode, so no first-create question is asked. 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 @@ -333,9 +356,6 @@ when the session opens the document. ## Verification -- A probe confirms, before implementation, that a brace suffix glob - under `docs/` loads a rule when a matching file is read; if braces do - not load, each rule takes one glob per suffix. - Loader tests cover the `` value: valid, outside `docs/`, `..`, trailing `/`. - A `test_decision_coverage.py` case audits a technical design outside @@ -386,9 +406,9 @@ when the session opens the document. — the suffix test. - `skills/process-status/SKILL.md` — the directory list in its description. -- `docs/domain/glossary.md` — done in the grilling session: six new - terms, the Process directory exclusion, the *Judged document* - sentence. +- `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 @@ -410,3 +430,18 @@ when the session opens the document. - D20: an unattended run, or an ambiguity nobody can answer, writes to `docs/code-review/`, matching the CI non-goal. - A move names each file it turns from untracked to tracked. + +## Review rounds + +### 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 From 1e933431fb542edc005e5ada13a6b925cbecacc5 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 13:38:49 +0100 Subject: [PATCH 07/36] docs: ticket directories spec, architect round 2 fixes and branch scheme --- docs/domain/glossary.md | 2 +- .../2026-10-27-ticket-directories-spec.md | 86 +++++++++++++------ 2 files changed, 63 insertions(+), 25 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index b43c16d..4f39b0e 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -624,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/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index f1e14ca..d021c06 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -3,7 +3,7 @@ ticket: none date: 2026-10-27 status: draft grilled: 2026-10-27 -architect: blocking +architect: concerns (resolved 2026-10-27) decisions: registered branch: feature/ticket-directories base: develop @@ -114,15 +114,21 @@ Anti-goals — the change fails, even if it works, when: `-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 - goes to `/code-review/`; any other report goes to - `docs/code-review/`. Argued in *Review reports*. -- **D19** — A branch names a ticket only when the segment after - `feature/` opens with a key shape — letters, a hyphen and digits, or - digits alone — and a ticket directory for that key already exists; a - review never creates a ticket directory. Argued in *Review reports*. -- **D20** — The review command, or a solo run before it writes, - resolves the report directory from the working tree and hands the - agent the path; a run with no interactive dispatcher, an ambiguity + goes to `/code-review/`, unless it is local-only; + any other report goes to `docs/code-review/`. Argued in *Review + reports*. +- **D19** — A branch name follows the scheme `[/][-]`, + `` any one segment and `` a key shape; a name in the scheme + whose ticket directory exists gives the review its ticket, while a + name in the scheme without one, or a key shape outside the scheme, is + asked about in an interactive session and gives no ticket otherwise. + A review never creates a ticket directory. The ticket-frontmatter + rule sources a new document's ticket from a branch by the same + scheme. 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 @@ -234,7 +240,11 @@ 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, which holds the lookup's details. +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 @@ -285,14 +295,29 @@ class directory climbs further (`../../specs/…`). The lifecycle rule's 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/`. A branch names a ticket only when -the segment after `feature/` opens with a key shape — letters, a hyphen -and digits (`ABC-123-login`), or digits alone (`6-salesforce`) — and a -ticket directory for that key, after the prefix rule (`6` gives -`ticket-6`), already exists. The shape alone proves nothing: -`feature/phase-2-cleanup` has it, and no ticket `phase-2` exists. A -review never creates a ticket directory; a ticket's directory appears -with its first process document. +`/code-review/`. A branch name follows the scheme +`[/][-]`: 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 branch name | interactive session | no interactive dispatcher | +|---|---|---| +| fits the scheme, and the key's ticket directory exists | the ticket directory, no question | the ticket directory | +| fits the scheme, no ticket directory (`feature/phase-2-cleanup`) | asks whether the branch is ticket `PHASE-2`'s | `docs/code-review/` | +| carries a key shape outside the scheme (`jan/abc-123-fix`, `release-ABC-123`) | asks for the ticket | `docs/code-review/` | +| carries no key shape (`feature/ticket-directories`) | `docs/code-review/`, no question | `docs/code-review/` | + +An answer holds for that branch until the session ends, so later +review rounds do not ask again; nothing is recorded. A review never +creates a ticket directory: a confirmed ticket whose directory does +not exist sends the report to `docs/code-review/`, and 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; it reads the branch by the same +scheme, so one definition of a ticket in a branch name serves both. The review command resolves the directory before dispatch, as it already runs the first-create check before dispatch: it looks for the @@ -366,9 +391,10 @@ when the session opens the document. 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/`, and one on - `feature/phase-2-cleanup` writes to `docs/code-review/` and creates no - directory. + `feature/ABC-12-x` writes to `abc-12-old/code-review/`, so does one + on `bugfix/ABC-12-y` and one on `ABC-12`, and one on + `feature/phase-2-cleanup` asks, then writes to `docs/code-review/` + and creates no directory. - In a project without `ticket.root`, the dogfood's ticketless flow writes to the class directories as today. @@ -399,7 +425,8 @@ when the session opens the document. also the ticket-root exclusion. - `rules/workflow.md` — where a ticket's documents go. - `rules/ticket-frontmatter.md` — field sets by class; companion - documents in a ticket directory exempt. + documents in a ticket directory exempt; branch sourcing by the D19 + scheme. - `rules/review-reports.md` — ticket placement of reports, the branch-ticket shape, the `docs/**/code-review/**` glob. - `scripts/decision-coverage.py`, `tests/working-process/test_decision_coverage.py` @@ -424,7 +451,8 @@ when the session opens the document. - The integration-branch lookup asks once where no instruction names the branch, reads the remote-tracking ref without fetching, and skips a branch that exists nowhere. -- D19's key shape for branch names. +- An answer about a branch's ticket holds for the session and is not + recorded. - 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 @@ -433,6 +461,16 @@ when the session opens the document. ## Review rounds +### 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 + ### 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 From 8a096f7e6f9426d38d399e57493d52cbf1cf94cc Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 13:42:47 +0100 Subject: [PATCH 08/36] docs: ticket directories spec, confirm a branch ticket without a directory --- docs/specs/2026-10-27-ticket-directories-spec.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index d021c06..90e60cd 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -124,7 +124,8 @@ Anti-goals — the change fails, even if it works, when: asked about in an interactive session and gives no ticket otherwise. A review never creates a ticket directory. The ticket-frontmatter rule sources a new document's ticket from a branch by the same - scheme. Argued in *Review reports*. + scheme, confirming with the developer a ticket whose directory does + not exist yet. 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 @@ -318,6 +319,11 @@ directory appears with its first process document. The ticket-frontmatter rule sources a new document's ticket from the branch name before the conversation; it reads the branch by the same scheme, so one definition of a ticket in a branch name serves both. +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. The review command resolves the directory before dispatch, as it already runs the first-create check before dispatch: it looks for the @@ -470,6 +476,7 @@ when the session opens the document. 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) From 021450e83422c2211d725c75b9ec46103f0d1ee3 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 13:50:15 +0100 Subject: [PATCH 09/36] docs: ticket directories spec, architect round 3 fixes --- .../2026-10-27-ticket-directories-spec.md | 101 +++++++++++------- 1 file changed, 64 insertions(+), 37 deletions(-) diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 90e60cd..127ff5c 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -3,7 +3,7 @@ ticket: none date: 2026-10-27 status: draft grilled: 2026-10-27 -architect: concerns (resolved 2026-10-27) +architect: blocking decisions: registered branch: feature/ticket-directories base: develop @@ -117,15 +117,16 @@ Anti-goals — the change fails, even if it works, when: goes to `/code-review/`, unless it is local-only; any other report goes to `docs/code-review/`. Argued in *Review reports*. -- **D19** — A branch name follows the scheme `[/][-]`, - `` any one segment and `` a key shape; a name in the scheme - whose ticket directory exists gives the review its ticket, while a - name in the scheme without one, or a key shape outside the scheme, is - asked about in an interactive session and gives no ticket otherwise. - A review never creates a ticket directory. The ticket-frontmatter - rule sources a new document's ticket from a branch by the same - scheme, confirming with the developer a ticket whose directory does - not exist yet. 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, a name in the scheme whose ticket directory + exists gives the ticket; a key shape outside the scheme is asked + about in an interactive session; anything else gives no ticket. 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 @@ -296,34 +297,48 @@ class directory climbs further (`../../specs/…`). The lifecycle rule's 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/`. A branch name follows the scheme -`[/][-]`: 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 branch name | interactive session | no interactive dispatcher | -|---|---|---| -| fits the scheme, and the key's ticket directory exists | the ticket directory, no question | the ticket directory | -| fits the scheme, no ticket directory (`feature/phase-2-cleanup`) | asks whether the branch is ticket `PHASE-2`'s | `docs/code-review/` | -| carries a key shape outside the scheme (`jan/abc-123-fix`, `release-ABC-123`) | asks for the ticket | `docs/code-review/` | -| carries no key shape (`feature/ticket-directories`) | `docs/code-review/`, no question | `docs/code-review/` | - -An answer holds for that branch until the session ends, so later -review rounds do not ask again; nothing is recorded. A review never -creates a ticket directory: a confirmed ticket whose directory does -not exist sends the report to `docs/code-review/`, and a ticket's +`/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 key 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 | + +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; its answer also sets the report's +`ticket:`. 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; it reads the branch by the same -scheme, so one definition of a ticket in a branch name serves both. +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. +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. The review command resolves the directory before dispatch, as it already runs the first-create check before dispatch: it looks for the @@ -398,9 +413,10 @@ when the session opens the document. 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`, and one on - `feature/phase-2-cleanup` asks, then writes to `docs/code-review/` - and creates no directory. + 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. @@ -429,12 +445,14 @@ when the session opens the document. - `rules/technical-design.md`, `rules/propagation-duties.md`, `rules/process-artifacts.md` — the suffix globs; process-artifacts also the ticket-root exclusion. -- `rules/workflow.md` — where a ticket's documents go. +- `rules/workflow.md` — where a ticket's documents go; the branch + scheme in *Branch naming*. - `rules/ticket-frontmatter.md` — field sets by class; companion documents in a ticket directory exempt; branch sourcing by the D19 scheme. -- `rules/review-reports.md` — ticket placement of reports, the - branch-ticket shape, the `docs/**/code-review/**` glob. +- `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 directory list in its @@ -467,6 +485,15 @@ when the session opens the document. ## Review rounds +### 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 From c64dff5f7e95f841cf3cb11d2bfdcd41a8058267 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 13:56:35 +0100 Subject: [PATCH 10/36] docs: ticket directories spec, architect round 4 fixes --- .../2026-10-27-ticket-directories-spec.md | 43 ++++++++++++++----- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 127ff5c..3e74b3e 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -3,7 +3,7 @@ ticket: none date: 2026-10-27 status: draft grilled: 2026-10-27 -architect: blocking +architect: concerns (resolved 2026-10-27) decisions: registered branch: feature/ticket-directories base: develop @@ -113,8 +113,9 @@ Anti-goals — the change fails, even if it works, when: - **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 - goes to `/code-review/`, unless it is local-only; +- **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 @@ -318,14 +319,23 @@ In an interactive session a review places its report by this table: |---|---| | 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 key 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 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 | -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; its answer also sets the report's -`ticket:`. A review never creates a ticket directory: a ticket's +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 @@ -338,7 +348,9 @@ 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. +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 @@ -446,7 +458,7 @@ when the session opens the document. `rules/process-artifacts.md` — the suffix globs; process-artifacts also the ticket-root exclusion. - `rules/workflow.md` — where a ticket's documents go; the branch - scheme in *Branch naming*. + scheme and the shared session answer in *Branch naming*. - `rules/ticket-frontmatter.md` — field sets by class; companion documents in a ticket directory exempt; branch sourcing by the D19 scheme. @@ -485,6 +497,15 @@ when the session opens the document. ## Review rounds +### 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 From 42059a202d6045b9ede2cd828dd41bc39c10329a Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:09:12 +0100 Subject: [PATCH 11/36] docs: ticket directories spec, integrity audit dispositions --- .../2026-10-27-ticket-directories-spec.md | 125 +++++++++++++----- 1 file changed, 92 insertions(+), 33 deletions(-) diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 3e74b3e..9f3c24f 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -4,6 +4,7 @@ date: 2026-10-27 status: draft grilled: 2026-10-27 architect: concerns (resolved 2026-10-27) +integrity: 2026-10-27 (sha: 2182680) decisions: registered branch: feature/ticket-directories base: develop @@ -121,13 +122,15 @@ Anti-goals — the change fails, even if it works, when: - **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, a name in the scheme whose ticket directory - exists gives the ticket; a key shape outside the scheme is asked - about in an interactive session; anything else gives no ticket. 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*. + 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 @@ -139,13 +142,28 @@ Anti-goals — the change fails, even if it works, when: skill. Argued in *Moving a document*. - **D16** — The move offers the document's whole chain. Argued in *Moving a document*. -- **D17** — The move rewrites every reference to and from each moved - file, and stops for the developer before any body edit to an - `implemented` document. 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 @@ -167,7 +185,9 @@ 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 `/`; the settings grammar +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. @@ -175,7 +195,10 @@ 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. +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 @@ -193,9 +216,10 @@ 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 or -the document's `base:` name it; where neither names it, the session -asks once. `` is its remote-tracking ref (`origin/develop`) where +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 @@ -209,7 +233,9 @@ 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. +developer, who picks one of the existing directories; the question +offers no new directory, which anti-goal 1 rules out. A review command +asks before dispatch, a session before it writes the document. ## Recognising a process document @@ -231,8 +257,9 @@ The cost to every project, opted in or not: a file under `docs/` named A ticket directory holds files a developer names freely; the client project already has a `screens-spec.md` there. The lifecycle rule says: a process document opens with frontmatter carrying `status:`; a file -that matches a class suffix without it belongs to the developer, and -the process neither adds frontmatter to it nor reports it. +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 @@ -368,7 +395,14 @@ 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. A local-only +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:` @@ -391,9 +425,12 @@ when the session opens the document. `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. A tracked file moves with - `git mv`; an untracked one, in an ignored class directory, with `mv` - and `git add`. + 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 every reference: inbound and outbound frontmatter links, the `with:` file in `integrity:`, `**Follows:**` lines and qualified decision identifiers (`.md#D3`) in bodies. @@ -409,8 +446,8 @@ when the session opens the document. nobody audited. 5. References outside `docs/` are listed, never rewritten. 6. The session reports every path it rewrote and every reference it - left alone, and names each file that was untracked before the move - and is tracked now. + left alone, and names each untracked file that now lies in the + tracked ticket directory. ## Verification @@ -456,7 +493,10 @@ when the session opens the document. `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. + 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; companion @@ -467,8 +507,8 @@ when the session opens the document. 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 directory list in its - description. +- `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. @@ -484,19 +524,38 @@ when the session opens the document. 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. -- The integration-branch lookup asks once where no instruction names - the branch, reads the remote-tracking ref without fetching, and skips - a branch that exists nowhere. -- An answer about a branch's ticket holds for the session and is not - recorded. - 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 names each file it turns from untracked to tracked. +- 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. +- 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 — 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 + ### 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)" From 70fd8b8ff503be319b8e8eb75f463c8bd461fc6e Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:12:29 +0100 Subject: [PATCH 12/36] docs: ticket directories spec, audit closures --- .../2026-10-27-ticket-directories-spec.md | 54 +++++++++++-------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 9f3c24f..1899cc5 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -4,7 +4,7 @@ date: 2026-10-27 status: draft grilled: 2026-10-27 architect: concerns (resolved 2026-10-27) -integrity: 2026-10-27 (sha: 2182680) +integrity: 2026-10-27 (sha: 371c6bb) decisions: registered branch: feature/ticket-directories base: develop @@ -87,17 +87,19 @@ Anti-goals — the change fails, even if it works, when: 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. Argued in *Placement*. + 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** — A file matching a class suffix 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*. + 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** — 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*. @@ -134,9 +136,9 @@ Anti-goals — the change fails, even if it works, when: - **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*. + 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*. @@ -176,8 +178,8 @@ Anti-goals — the change fails, even if it works, when: `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 +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: @@ -215,8 +217,8 @@ ignoring case — the trailing hyphen keeps `abc-14-` from matching 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 +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 @@ -233,8 +235,10 @@ 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; the question -offers no new directory, which anti-goal 1 rules out. A review command +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 @@ -362,8 +366,9 @@ 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. +`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. @@ -431,7 +436,7 @@ when the session opens the document. 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 every reference: inbound and outbound +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 @@ -444,7 +449,8 @@ when the session opens the document. 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/` are listed, never rewritten. +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. @@ -546,6 +552,8 @@ when the session opens the document. ### 2026-10-27 — integrity audit, fable, at the consumption gate +- 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 From b585f127118880020910fb1c9ee4646cb01556a3 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:19:14 +0100 Subject: [PATCH 13/36] docs: ticket directories plan --- .../2026-10-27-ticket-directories-plan.md | 422 ++++++++++++++++++ 1 file changed, 422 insertions(+) create mode 100644 docs/plans/2026-10-27-ticket-directories-plan.md 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..bc61985 --- /dev/null +++ b/docs/plans/2026-10-27-ticket-directories-plan.md @@ -0,0 +1,422 @@ +--- +ticket: none +date: 2026-10-27 +status: draft +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.** + +## 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`. + +- [ ] **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` → exit 0; + - `jira`, `docs`, `docs/`, `docs/jira/`, `docs/../jira`, + `docs/specs`, `docs/code-review/x` → `--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. In `do_set`, when the normalised values + are ``, call a POSIX shell `path_value_ok "$s_value"` with the + same rules 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 + `python3 -m unittest discover -s tests -p 'test_*.py'` — expect all + pass. +- [ ] **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** (save as + `/tmp/…/t3-check.sh` in the session's scratch directory) and run it — + expect every line to fail: + - `grep -q 'docs/\*\*/\*-{spec,technical-design,plan}.md' rules/{spec-plan-lifecycle,propagation-duties,process-artifacts}.md` + - `grep -q 'docs/\*\*/\*-technical-design.md' rules/technical-design.md` + - `grep -q '^## Ticket directories' rules/spec-plan-lifecycle.md` + - `grep -q -- '--full-tree -d --name-only' rules/spec-plan-lifecycle.md` + - `grep -q 'git rev-parse --show-toplevel' rules/spec-plan-lifecycle.md` + - `sed -n '/^## Ticket directories/,/^## [^T]/p' rules/spec-plan-lifecycle.md | grep -q 'status:'` + - `grep -q 'ticket root' rules/process-artifacts.md` +- [ ] **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` after + the naming paragraph, 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 (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: 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 | 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`; + `grep -q 'read the spec-plan-lifecycle rule before creating a ticket directory' rules/workflow.md`; + `grep -q 'fixes the shape and not the spelling' rules/workflow.md` + (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:** 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: + `grep -q 'companion document' rules/ticket-frontmatter.md`; + `grep -q 'Branch naming' rules/ticket-frontmatter.md`; + `grep -q 'confirm' rules/ticket-frontmatter.md`. +- [ ] **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 companion documents in a ticket directory. +- [ ] **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`; + `grep -q 'ticket directories' skills/process-status/SKILL.md`. +- [ ] **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: Run** the check block, the full test suite 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: + `grep -q 'ticket.root' plugins/{python,salesforce}-standards/commands/*-review.md`; + `grep -q 'writes the review report to docs/code-review/' plugins/{python,salesforce}-standards/agents/*.md` + 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 full test suite, 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, so copy this + branch's `plugins/working-process/rules/*.md` into the scratch + project's `.claude/rules/working-process/`, and run every session + with a temporary `CLAUDE_CONFIG_DIR`, so no user-level rule loads, + and with `claude --plugin-dir` on this branch's three plugins. Before + the cases, ask a session to quote the spec-plan-lifecycle rule's + *Ticket directories* heading; no quote, no dogfood. +- [ ] **Step 2:** 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:** Report failures to the developer before any fix; + a fix is a new task. From bad62a2534ce2a65336fb842e657990063710c32 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:40:33 +0100 Subject: [PATCH 14/36] docs: ticket directories plan, adversary round 1 fixes --- .../2026-10-27-ticket-directories-plan.md | 150 +++++++++++++----- .../2026-10-27-ticket-directories-spec.md | 13 +- 2 files changed, 116 insertions(+), 47 deletions(-) diff --git a/docs/plans/2026-10-27-ticket-directories-plan.md b/docs/plans/2026-10-27-ticket-directories-plan.md index bc61985..21e6148 100644 --- a/docs/plans/2026-10-27-ticket-directories-plan.md +++ b/docs/plans/2026-10-27-ticket-directories-plan.md @@ -2,6 +2,7 @@ ticket: none date: 2026-10-27 status: draft +adversary: blocking spec: ../specs/2026-10-27-ticket-directories-spec.md branch: feature/ticket-directories base: develop @@ -60,6 +61,26 @@ validate`, and `claude --plugin-dir` for the dogfood. - **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 its commit. ## Review Focus @@ -100,7 +121,10 @@ validate`, and `claude --plugin-dir` for the dogfood. 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`. + `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` @@ -112,9 +136,9 @@ validate`, and `claude --plugin-dir` for the dogfood. `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` → exit 0; + - `docs/tickets/active` and `docs/specs-archive` → exit 0; - `jira`, `docs`, `docs/`, `docs/jira/`, `docs/../jira`, - `docs/specs`, `docs/code-review/x` → `--set` exits 1 with + `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. @@ -127,16 +151,18 @@ validate`, and `claude --plugin-dir` for the dogfood. 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. In `do_set`, when the normalised values - are ``, call a POSIX shell `path_value_ok "$s_value"` with the - same rules instead of the enumeration loop. The error text stays as + `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 - `python3 -m unittest discover -s tests -p 'test_*.py'` — expect all - pass. +- [ ] **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 @@ -185,20 +211,22 @@ validate`, and `claude --plugin-dir` for the dogfood. `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** (save as - `/tmp/…/t3-check.sh` in the session's scratch directory) and run it — - expect every line to fail: - - `grep -q 'docs/\*\*/\*-{spec,technical-design,plan}.md' rules/{spec-plan-lifecycle,propagation-duties,process-artifacts}.md` - - `grep -q 'docs/\*\*/\*-technical-design.md' rules/technical-design.md` +- [ ] **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` - `grep -q -- '--full-tree -d --name-only' rules/spec-plan-lifecycle.md` - `grep -q 'git rev-parse --show-toplevel' rules/spec-plan-lifecycle.md` - - `sed -n '/^## Ticket directories/,/^## [^T]/p' rules/spec-plan-lifecycle.md | grep -q 'status:'` - - `grep -q 'ticket root' rules/process-artifacts.md` + - `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` after - the naming paragraph, carrying, in the spec's words: placement under + 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 @@ -206,7 +234,8 @@ validate`, and `claude --plugin-dir` for the dogfood. 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 (D8); "frontmatter links are + 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 @@ -217,8 +246,9 @@ validate`, and `claude --plugin-dir` for the dogfood. - [ ] **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: Run** `claude plugin validate plugins/working-process` — - expect "Validation passed". +- [ ] **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 @@ -238,7 +268,7 @@ validate`, and `claude --plugin-dir` for the dogfood. 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 | grep -q ''`. + 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:`, @@ -267,8 +297,8 @@ validate`, and `claude --plugin-dir` for the dogfood. - [ ] **Step 1: Write the check block** and run it — expect failure: `grep -q '\[/\]\[-\]' rules/workflow.md`; - `grep -q 'read the spec-plan-lifecycle rule before creating a ticket directory' rules/workflow.md`; - `grep -q 'fixes the shape and not the spelling' 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 @@ -289,7 +319,7 @@ validate`, and `claude --plugin-dir` for the dogfood. ### Task 6: Ticket-frontmatter rule -**Realizes:** D9, D19, D23 +**Realizes:** D8, D9, D19, D23 **Files:** - Modify: `plugins/working-process/rules/ticket-frontmatter.md` @@ -302,7 +332,8 @@ validate`, and `claude --plugin-dir` for the dogfood. - [ ] **Step 1: Write the check block** and run it — expect failure: `grep -q 'companion document' rules/ticket-frontmatter.md`; `grep -q 'Branch naming' rules/ticket-frontmatter.md`; - `grep -q 'confirm' 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 @@ -311,7 +342,10 @@ validate`, and `claude --plugin-dir` for the dogfood. *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 companion documents in a ticket directory. + exempts every file the `status:` gate excludes — a file matching a + class suffix or lying in a class directory without `status:`, and a + 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`. @@ -349,8 +383,9 @@ validate`, and `claude --plugin-dir` for the dogfood. 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: Run** the check block, the full test suite and - `claude plugin validate plugins/working-process` — expect pass. +- [ ] **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 @@ -371,18 +406,22 @@ validate`, and `claude --plugin-dir` for the dogfood. - Consumes: the review-reports placement section (Task 7a). - [ ] **Step 1: Write the check block** and run it — expect each to fail: - `grep -q 'ticket.root' plugins/{python,salesforce}-standards/commands/*-review.md`; - `grep -q 'writes the review report to docs/code-review/' plugins/{python,salesforce}-standards/agents/*.md` - must **pass** before and **fail** after (the only-location claim is - gone). + 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 full test suite, and - `claude plugin validate` on both standards plugins — expect pass. +- [ ] **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 @@ -406,17 +445,42 @@ validate`, and `claude --plugin-dir` for the dogfood. - [ ] **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, so copy this - branch's `plugins/working-process/rules/*.md` into the scratch - project's `.claude/rules/working-process/`, and run every session - with a temporary `CLAUDE_CONFIG_DIR`, so no user-level rule loads, - and with `claude --plugin-dir` on this branch's three plugins. Before - the cases, ask a session to quote the spec-plan-lifecycle rule's - *Ticket directories* heading; no quote, no dogfood. + 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: + - back up `~/.claude/rules/working-process/` to a dated directory + beside it, and copy this branch's `plugins/working-process/rules/*.md` + in its place; + - `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:** 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:** Report failures to the developer before any fix; +- [ ] **Step 4:** Restore: delete the copied rules, move the backup + back, `claude plugin enable` the three plugins; confirm with + `diff -r` against the backup's listing and `claude plugin list`. +- [ ] **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 diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 1899cc5..4b647b9 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -4,7 +4,7 @@ date: 2026-10-27 status: draft grilled: 2026-10-27 architect: concerns (resolved 2026-10-27) -integrity: 2026-10-27 (sha: 371c6bb) +integrity: 2026-10-27 (sha: b5e6677) decisions: registered branch: feature/ticket-directories base: develop @@ -297,7 +297,10 @@ 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. +which the process reads. The ticket-frontmatter rule's backfill — the +block it adds to an edited document that has none — skips every file +D8's gate excludes, a companion document among them; every other +document under `docs/` is backfilled as today. ## Modes @@ -505,8 +508,8 @@ when the session opens the document. - `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; companion - documents in a ticket directory exempt; branch sourcing by the D19 +- `rules/ticket-frontmatter.md` — field sets by class; the backfill + skips every file D8's gate excludes; 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", @@ -552,6 +555,8 @@ when the session opens the document. ### 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 — 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 From 31330336412a81b97998e1a5f50b66f160001f3d Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:50:53 +0100 Subject: [PATCH 15/36] docs: ticket directories plan, adversary round 2 fixes --- .../2026-10-27-ticket-directories-plan.md | 47 +++++++++++++------ .../2026-10-27-ticket-directories-spec.md | 9 ++-- 2 files changed, 37 insertions(+), 19 deletions(-) diff --git a/docs/plans/2026-10-27-ticket-directories-plan.md b/docs/plans/2026-10-27-ticket-directories-plan.md index 21e6148..babb330 100644 --- a/docs/plans/2026-10-27-ticket-directories-plan.md +++ b/docs/plans/2026-10-27-ticket-directories-plan.md @@ -2,7 +2,7 @@ ticket: none date: 2026-10-27 status: draft -adversary: blocking +adversary: concerns (resolved 2026-10-27) spec: ../specs/2026-10-27-ticket-directories-spec.md branch: feature/ticket-directories base: develop @@ -80,7 +80,8 @@ validate`, and `claude --plugin-dir` for the dogfood. 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 its commit. + text before the task's check block runs, so the pass cannot rewrite a + phrase the block already certified. ## Review Focus @@ -218,8 +219,8 @@ validate`, and `claude --plugin-dir` for the dogfood. `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` - - `grep -q -- '--full-tree -d --name-only' rules/spec-plan-lifecycle.md` - - `grep -q 'git rev-parse --show-toplevel' 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 @@ -330,7 +331,7 @@ validate`, and `claude --plugin-dir` for the dogfood. - Consumes: *Branch naming* (Task 5). - [ ] **Step 1: Write the check block** and run it — expect failure: - `grep -q 'companion document' rules/ticket-frontmatter.md`; + `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'`. @@ -343,9 +344,9 @@ validate`, and `claude --plugin-dir` for the dogfood. 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 a - companion document in a ticket directory — while every other document - under `docs/` is backfilled as today (D8, D9). + 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`. @@ -372,7 +373,7 @@ validate`, and `claude --plugin-dir` for the dogfood. `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`; - `grep -q 'ticket directories' skills/process-status/SKILL.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 @@ -448,9 +449,12 @@ validate`, and `claude --plugin-dir` for the dogfood. 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: - - back up `~/.claude/rules/working-process/` to a dated directory - beside it, and copy this branch's `plugins/working-process/rules/*.md` - in its place; + - 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; @@ -463,9 +467,12 @@ validate`, and `claude --plugin-dir` for the dogfood. 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: delete the copied rules, move the backup - back, `claude plugin enable` the three plugins; confirm with - `diff -r` against the backup's listing and `claude plugin list`. +- [ ] **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. @@ -484,3 +491,13 @@ validate`, and `claude --plugin-dir` for the dogfood. - 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-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index 4b647b9..dfad78e 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -4,7 +4,7 @@ date: 2026-10-27 status: draft grilled: 2026-10-27 architect: concerns (resolved 2026-10-27) -integrity: 2026-10-27 (sha: b5e6677) +integrity: 2026-10-27 (sha: 72637ab) decisions: registered branch: feature/ticket-directories base: develop @@ -299,7 +299,7 @@ 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 every file -D8's gate excludes, a companion document among them; every other +D8's gate excludes and every companion document (D9); every other document under `docs/` is backfilled as today. ## Modes @@ -509,8 +509,8 @@ when the session opens the document. - `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; branch sourcing by the D19 - scheme. + 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. @@ -556,6 +556,7 @@ when the session opens the document. ### 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 From 75f5f928c5adc3f2a5daf94f6e7fb65497805125 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:52:22 +0100 Subject: [PATCH 16/36] docs: ticket directories plan, a diff for each dogfood review --- docs/plans/2026-10-27-ticket-directories-plan.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/plans/2026-10-27-ticket-directories-plan.md b/docs/plans/2026-10-27-ticket-directories-plan.md index babb330..19d543c 100644 --- a/docs/plans/2026-10-27-ticket-directories-plan.md +++ b/docs/plans/2026-10-27-ticket-directories-plan.md @@ -462,7 +462,11 @@ validate`, and `claude --plugin-dir` for the dogfood. *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:** Run every case of the spec's *Verification* dogfood +- [ ] **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 From eb67da17f53fa316e99a31ec5713cba7955cd394 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 14:58:23 +0100 Subject: [PATCH 17/36] feat(working-process): ticket.root settings key with a path value --- plugins/working-process/SETTINGS_REGISTRY.md | 11 +++++- .../working-process/scripts/load-settings.sh | 38 +++++++++++++++++-- .../skills/process-setup/SKILL.md | 4 ++ tests/working-process/test_load_settings.py | 25 ++++++++++++ .../working-process/test_settings_registry.py | 15 ++++---- 5 files changed, 82 insertions(+), 11 deletions(-) diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index 3a1c37d..f047a02 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 +question: Which directory under docs/ holds one directory per ticket, if the project keeps them? 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/tests/working-process/test_load_settings.py b/tests/working-process/test_load_settings.py index 6abb381..331f35f 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,30 @@ 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) + 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"]) From 2bdd7d0cd669ed72fbb81452043d59400f51cc53 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:02:22 +0100 Subject: [PATCH 18/36] feat(working-process): decision coverage recognises a technical design by its suffix --- .../scripts/decision-coverage.py | 5 ++-- .../working-process/test_decision_coverage.py | 24 +++++++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) 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/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) From ead24d8ad3f35443ea652d19b4e349b52688f516 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:12:25 +0100 Subject: [PATCH 19/36] feat(working-process): ticket directories in the document rules --- plugins/working-process/SETTINGS_REGISTRY.md | 2 +- .../rules/process-artifacts.md | 7 +++ .../rules/propagation-duties.md | 1 + .../rules/spec-plan-lifecycle.md | 55 ++++++++++++++++++- .../working-process/rules/technical-design.md | 8 ++- 5 files changed, 68 insertions(+), 5 deletions(-) diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index f047a02..0ba63ba 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -135,5 +135,5 @@ question: May the review loop commit the reviewed document once per round? scope: team values: default: unset -read-by: working-process/skills/process-setup/SKILL.md +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 question: Which directory under docs/ holds one directory per ticket, if the project keeps them? 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/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index b1046cd..19cebd4 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -3,6 +3,7 @@ paths: - "docs/specs/**" - "docs/technical-designs/**" - "docs/plans/**" + - "docs/**/*-{spec,technical-design,plan}.md" --- # Judged documents and plans — frontmatter and lifecycle @@ -21,7 +22,8 @@ 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. +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: @@ -181,6 +183,57 @@ 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. + +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. + ## 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 19729d3..111147d 100644 --- a/plugins/working-process/rules/technical-design.md +++ b/plugins/working-process/rules/technical-design.md @@ -1,15 +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 as the spec-plan-lifecycle rule names documents, with -the class `technical-design`. +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 From 1aa7dbdbfb9c639fbfd3e5fbbd283115ff337c3f Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:19:14 +0100 Subject: [PATCH 20/36] feat(working-process): move a document into a ticket directory --- .../rules/spec-plan-lifecycle.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 19cebd4..c6e30a0 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -234,6 +234,41 @@ 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`. Several tickets go to the developer. +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.** 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. Where a document's `integrity:` hashes (its own + `sha:` and any `with:` hash) matched its body before the move, + recompute them after the rewrite with the hash command above 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` From e1c013b447adbf6f9d7a108cc6cb5dd54f4d6fef Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:23:10 +0100 Subject: [PATCH 21/36] fix(working-process): move procedure checks hashes before the rewrite --- .../rules/spec-plan-lifecycle.md | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index c6e30a0..04fe10f 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -241,7 +241,7 @@ 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`. Several tickets go to the developer. + 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. @@ -252,18 +252,21 @@ session's initiative. Six steps: 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.** 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 +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. Where a document's `integrity:` hashes (its own - `sha:` and any `with:` hash) matched its body before the move, - recompute them after the rewrite with the hash command above and - keep the audit date. A hash that did not match stays as it was: - recomputing it would stamp edits nobody audited. + 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 From 3d15d3951fdc2d160ee49418aae31825cecc6733 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:39:56 +0100 Subject: [PATCH 22/36] feat(working-process): ticket placement and the branch scheme in the workflow rule --- plugins/working-process/SETTINGS_REGISTRY.md | 2 +- plugins/working-process/rules/workflow.md | 26 ++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index 0ba63ba..f3955a8 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -135,5 +135,5 @@ question: May the review loop commit the reviewed document once per round? 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 +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 question: Which directory under docs/ holds one directory per ticket, if the project keeps them? diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index de2d872..1d554ab 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -151,6 +151,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 for +a ticket 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 @@ -250,6 +259,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 From 86e87488cacb96f9c56dcbca59499c76afe69b46 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:46:29 +0100 Subject: [PATCH 23/36] fix(working-process): point the flow steps at the ticket-directory clause --- plugins/working-process/rules/workflow.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index 1d554ab..a64f012 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,9 +152,10 @@ 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 for -a ticket goes into the root's subdirectory whose name starts with -`-`, ignoring case, in the working tree or on the integration +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 `-` (the ticket's file prefix, as the +spec-plan-lifecycle rule names it), 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 From 73e64b91675d00e949304ea42409576f0ca43008 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:52:53 +0100 Subject: [PATCH 24/36] feat(working-process): ticket-frontmatter for ticket directories --- plugins/working-process/SETTINGS_REGISTRY.md | 2 +- .../working-process/rules/ticket-frontmatter.md | 17 +++++++++++++++-- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/plugins/working-process/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index f3955a8..db1fe0d 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -135,5 +135,5 @@ question: May the review loop commit the reviewed document once per round? 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 +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 question: Which directory under docs/ holds one directory per ticket, if the project keeps them? diff --git a/plugins/working-process/rules/ticket-frontmatter.md b/plugins/working-process/rules/ticket-frontmatter.md index 48e6293..204d5d7 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,8 +54,9 @@ 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 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 @@ -61,11 +66,19 @@ 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. + 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 From ef832fa4268d3761723b2d4590439651c4c8a8d6 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 15:56:50 +0100 Subject: [PATCH 25/36] fix(working-process): a declined ticket-directory confirmation falls through, never to a second question --- plugins/working-process/rules/ticket-frontmatter.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/plugins/working-process/rules/ticket-frontmatter.md b/plugins/working-process/rules/ticket-frontmatter.md index 204d5d7..8cce912 100644 --- a/plugins/working-process/rules/ticket-frontmatter.md +++ b/plugins/working-process/rules/ticket-frontmatter.md @@ -56,10 +56,10 @@ GitLab, or anything else; the field is always `ticket`. 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 +*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 @@ -68,13 +68,16 @@ 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. +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; From 433d47b3a522ad884a8009f1b37a243c428907a3 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 16:45:24 +0100 Subject: [PATCH 26/36] feat(working-process): review reports in ticket directories --- plugins/working-process/README.md | 5 ++ plugins/working-process/SETTINGS_REGISTRY.md | 2 +- .../working-process/rules/review-reports.md | 51 ++++++++++++++++++- .../skills/process-status/SKILL.md | 2 +- 4 files changed, 57 insertions(+), 3 deletions(-) diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index 8574572..25f420c 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -319,6 +319,11 @@ 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, and a review report whose +ticket the branch name gives goes to that ticket directory's +`code-review/`. + ## 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 db1fe0d..6eb4a02 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -135,5 +135,5 @@ question: May the review loop commit the reviewed document once per round? 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 +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 question: Which directory under docs/ holds one directory per ticket, if the project keeps them? diff --git a/plugins/working-process/rules/review-reports.md b/plugins/working-process/rules/review-reports.md index e8af1d5..7948665 100644 --- a/plugins/working-process/rules/review-reports.md +++ b/plugins/working-process/rules/review-reports.md @@ -1,6 +1,7 @@ --- paths: - "docs/code-review/**" + - "docs/**/code-review/**" --- # Review reports @@ -33,6 +34,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 +120,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 +275,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/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 From 559870fc4b6e983fd46e6d47ddb718c759374f1d Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 16:50:52 +0100 Subject: [PATCH 27/36] feat: standards review commands place reports in ticket directories --- plugins/python-standards/README.md | 7 +++--- .../agents/python-code-reviewer.md | 4 +++- .../commands/python-review.md | 21 ++++++++++++----- .../skills/python-code-review/SKILL.md | 4 +++- plugins/salesforce-standards/README.md | 7 +++--- .../agents/salesforce-code-reviewer.md | 4 +++- .../commands/salesforce-review.md | 23 +++++++++++++------ .../skills/salesforce-code-review/SKILL.md | 4 +++- plugins/working-process/SETTINGS_REGISTRY.md | 2 +- 9 files changed, 52 insertions(+), 24 deletions(-) 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 9e406ec..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,6 +11,8 @@ 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 diff --git a/plugins/python-standards/commands/python-review.md b/plugins/python-standards/commands/python-review.md index bc9eb99..1093661 100644 --- a/plugins/python-standards/commands/python-review.md +++ b/plugins/python-standards/commands/python-review.md @@ -9,7 +9,15 @@ 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. 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. + Otherwise — 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 +36,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/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 91f1fa0..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,6 +12,8 @@ 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 diff --git a/plugins/salesforce-standards/commands/salesforce-review.md b/plugins/salesforce-standards/commands/salesforce-review.md index b978a79..611d5eb 100644 --- a/plugins/salesforce-standards/commands/salesforce-review.md +++ b/plugins/salesforce-standards/commands/salesforce-review.md @@ -17,7 +17,15 @@ 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. 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. + Otherwise — 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 +44,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/SETTINGS_REGISTRY.md b/plugins/working-process/SETTINGS_REGISTRY.md index 6eb4a02..c0a214d 100644 --- a/plugins/working-process/SETTINGS_REGISTRY.md +++ b/plugins/working-process/SETTINGS_REGISTRY.md @@ -135,5 +135,5 @@ question: May the review loop commit the reviewed document once per round? 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 +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? From 8ac90d56f7ed688c0357f78fbc1c0967e9a24aad Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 16:52:52 +0100 Subject: [PATCH 28/36] fix: standards review commands send local-only reviews to docs/code-review --- plugins/python-standards/commands/python-review.md | 3 ++- plugins/salesforce-standards/commands/salesforce-review.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/plugins/python-standards/commands/python-review.md b/plugins/python-standards/commands/python-review.md index 1093661..1465f07 100644 --- a/plugins/python-standards/commands/python-review.md +++ b/plugins/python-standards/commands/python-review.md @@ -15,7 +15,8 @@ this session. working tree only, as the review-reports rule's *Ticket-directory placement* prescribes, and pass the agent its absolute path. Otherwise — no `ticket.root`, a Standalone install, an - unattended run — use `docs/code-review/`. A report bound for a + unattended run, a review the developer requests as local-only, + whatever the branch — 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`, diff --git a/plugins/salesforce-standards/commands/salesforce-review.md b/plugins/salesforce-standards/commands/salesforce-review.md index 611d5eb..f621d7e 100644 --- a/plugins/salesforce-standards/commands/salesforce-review.md +++ b/plugins/salesforce-standards/commands/salesforce-review.md @@ -23,7 +23,8 @@ review must never block this session. working tree only, as the review-reports rule's *Ticket-directory placement* prescribes, and pass the agent its absolute path. Otherwise — no `ticket.root`, a Standalone install, an - unattended run — use `docs/code-review/`. A report bound for a + unattended run, a review the developer requests as local-only, + whatever the branch — 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`, From d39ac5931ed5acb2a2d8b1ec4135030e88ff0d7f Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 16:54:37 +0100 Subject: [PATCH 29/36] fix: standards review commands check local-only before the ticket branch --- plugins/python-standards/commands/python-review.md | 9 +++++---- .../salesforce-standards/commands/salesforce-review.md | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/plugins/python-standards/commands/python-review.md b/plugins/python-standards/commands/python-review.md index 1465f07..05852fd 100644 --- a/plugins/python-standards/commands/python-review.md +++ b/plugins/python-standards/commands/python-review.md @@ -10,13 +10,14 @@ this session. otherwise the current diff — staged plus unstaged changes, or, on a clean tree, the diff of the current branch against its base. 2. Resolve the report directory, gated on the same contract probe - as step 3. With the contract found, `ticket.root` set in a settings + 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. - Otherwise — no `ticket.root`, a Standalone install, an - unattended run, a review the developer requests as local-only, - whatever the branch — use `docs/code-review/`. A report bound for a + 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`, diff --git a/plugins/salesforce-standards/commands/salesforce-review.md b/plugins/salesforce-standards/commands/salesforce-review.md index f621d7e..87d2c21 100644 --- a/plugins/salesforce-standards/commands/salesforce-review.md +++ b/plugins/salesforce-standards/commands/salesforce-review.md @@ -18,13 +18,14 @@ review must never block this session. declarations on disk. Where step (c) resolved the framework, offer to write the declaration before dispatching. 3. Resolve the report directory, gated on the same contract probe - as step 4. With the contract found, `ticket.root` set in a settings + 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. - Otherwise — no `ticket.root`, a Standalone install, an - unattended run, a review the developer requests as local-only, - whatever the branch — use `docs/code-review/`. A report bound for a + 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`, From 473a784bf81395b8d44f4deeb1f16e86ab6b05ba Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 16:56:25 +0100 Subject: [PATCH 30/36] docs: changelog entries for ticket directories --- plugins/python-standards/CHANGELOG.md | 3 +++ plugins/salesforce-standards/CHANGELOG.md | 3 +++ plugins/working-process/CHANGELOG.md | 7 +++++++ 3 files changed, 13 insertions(+) diff --git a/plugins/python-standards/CHANGELOG.md b/plugins/python-standards/CHANGELOG.md index dcca98d..d0612e9 100644 --- a/plugins/python-standards/CHANGELOG.md +++ b/plugins/python-standards/CHANGELOG.md @@ -7,6 +7,9 @@ Released versions of this plugin, newest first. - 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 diff --git a/plugins/salesforce-standards/CHANGELOG.md b/plugins/salesforce-standards/CHANGELOG.md index 7ef46bd..980d387 100644 --- a/plugins/salesforce-standards/CHANGELOG.md +++ b/plugins/salesforce-standards/CHANGELOG.md @@ -7,6 +7,9 @@ Released versions of this plugin, newest first. - 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 diff --git a/plugins/working-process/CHANGELOG.md b/plugins/working-process/CHANGELOG.md index b408030..cdb53b9 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -12,6 +12,13 @@ Released versions of this plugin, newest first. - 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 From 0078f5efb58766b058a3e670a2dce9dd6de301ea Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 17:45:40 +0100 Subject: [PATCH 31/36] fix(working-process): scope the status gate to ticket.root, name ticket-directory placement --- plugins/working-process/README.md | 7 ++++--- plugins/working-process/rules/review-reports.md | 8 +++++--- .../working-process/rules/spec-plan-lifecycle.md | 10 +++++----- plugins/working-process/rules/workflow.md | 13 ++++++------- tests/working-process/test_load_settings.py | 1 + 5 files changed, 21 insertions(+), 18 deletions(-) diff --git a/plugins/working-process/README.md b/plugins/working-process/README.md index 25f420c..c60972f 100644 --- a/plugins/working-process/README.md +++ b/plugins/working-process/README.md @@ -320,9 +320,10 @@ A tracked-mode — 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, and a review report whose -ticket the branch name gives goes to that ticket directory's -`code-review/`. +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 diff --git a/plugins/working-process/rules/review-reports.md b/plugins/working-process/rules/review-reports.md index 7948665..f598289 100644 --- a/plugins/working-process/rules/review-reports.md +++ b/plugins/working-process/rules/review-reports.md @@ -7,15 +7,17 @@ paths: # 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 diff --git a/plugins/working-process/rules/spec-plan-lifecycle.md b/plugins/working-process/rules/spec-plan-lifecycle.md index 04fe10f..2e84f36 100644 --- a/plugins/working-process/rules/spec-plan-lifecycle.md +++ b/plugins/working-process/rules/spec-plan-lifecycle.md @@ -221,11 +221,11 @@ 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. -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. +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 diff --git a/plugins/working-process/rules/workflow.md b/plugins/working-process/rules/workflow.md index a64f012..149f9de 100644 --- a/plugins/working-process/rules/workflow.md +++ b/plugins/working-process/rules/workflow.md @@ -154,13 +154,12 @@ disables its suggestion — never the work itself. 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 `-` (the ticket's file prefix, as the -spec-plan-lifecycle rule names it), 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. +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 diff --git a/tests/working-process/test_load_settings.py b/tests/working-process/test_load_settings.py index 331f35f..d473950 100644 --- a/tests/working-process/test_load_settings.py +++ b/tests/working-process/test_load_settings.py @@ -167,6 +167,7 @@ def test_ticket_root_path_values(self) -> None: 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: From 0a3532526fe0c3a0a001a54b79d39cad8f214f51 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 17:45:40 +0100 Subject: [PATCH 32/36] docs: scope the status gate to ticket.root in the spec and glossary --- docs/domain/glossary.md | 6 +++--- .../2026-10-27-ticket-directories-spec.md | 20 ++++++++++--------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/domain/glossary.md b/docs/domain/glossary.md index 4f39b0e..f19d51e 100644 --- a/docs/domain/glossary.md +++ b/docs/domain/glossary.md @@ -276,9 +276,9 @@ _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, together with a frontmatter `status:`; -a file with the suffix alone is not one — in a ticket directory, it is -a companion document. +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**: diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index dfad78e..f8805e7 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -4,7 +4,7 @@ date: 2026-10-27 status: draft grilled: 2026-10-27 architect: concerns (resolved 2026-10-27) -integrity: 2026-10-27 (sha: 72637ab) +integrity: 2026-10-27 (sha: fcf90fc) decisions: registered branch: feature/ticket-directories base: develop @@ -96,9 +96,9 @@ Anti-goals — the change fails, even if it works, when: 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** — 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 +- **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. @@ -260,8 +260,8 @@ The cost to every project, opted in or not: a file under `docs/` named A ticket directory holds files a developer names freely; the client project already has a `screens-spec.md` there. The lifecycle rule says: -a process document opens with frontmatter carrying `status:`; a file -without it — matched by a class suffix or lying in a class directory — +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. @@ -298,8 +298,9 @@ a process document nor a review report — needs neither `ticket:` nor 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 every file -D8's gate excludes and every companion document (D9); every other +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 @@ -542,7 +543,7 @@ when the session opens the document. - The loader refuses a `ticket.root` equal to or inside a Process directory. - Several matching directories offer only the existing ones. -- The `status:` gate holds in class directories too. +- 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/` @@ -569,6 +570,7 @@ when the session opens the document. - 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) From d0b2dbe6cfeb6860654dff04b8e4c7f05cd2c251 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 18:09:13 +0100 Subject: [PATCH 33/36] docs(working-process): ticket directories spec and plan implemented --- docs/plans/2026-10-27-ticket-directories-plan.md | 2 +- docs/specs/2026-10-27-ticket-directories-spec.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plans/2026-10-27-ticket-directories-plan.md b/docs/plans/2026-10-27-ticket-directories-plan.md index 19d543c..67b8412 100644 --- a/docs/plans/2026-10-27-ticket-directories-plan.md +++ b/docs/plans/2026-10-27-ticket-directories-plan.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-10-27 -status: draft +status: implemented adversary: concerns (resolved 2026-10-27) spec: ../specs/2026-10-27-ticket-directories-spec.md branch: feature/ticket-directories diff --git a/docs/specs/2026-10-27-ticket-directories-spec.md b/docs/specs/2026-10-27-ticket-directories-spec.md index f8805e7..542eb8b 100644 --- a/docs/specs/2026-10-27-ticket-directories-spec.md +++ b/docs/specs/2026-10-27-ticket-directories-spec.md @@ -1,7 +1,7 @@ --- ticket: none date: 2026-10-27 -status: draft +status: implemented grilled: 2026-10-27 architect: concerns (resolved 2026-10-27) integrity: 2026-10-27 (sha: fcf90fc) From 8c53b632f0cb027670ef540ef36ad6319183b77d Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 18:46:16 +0100 Subject: [PATCH 34/36] chore(working-process): dogfooding version for ticket directories --- plugins/working-process/.claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index 37b3e92..a5ef94d 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-dev.4.ticket-directories", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["process", "workflow", "spec", "plan", "review", "glossary", "adr", "architecture"], From fad67933a5ddaef4cbd6cf6c687332fd5b71c13d Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Tue, 27 Oct 2026 18:47:04 +0100 Subject: [PATCH 35/36] chore: dogfooding versions for ticket directories - python-standards, salesforce-standards --- plugins/python-standards/.claude-plugin/plugin.json | 2 +- plugins/salesforce-standards/.claude-plugin/plugin.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/python-standards/.claude-plugin/plugin.json b/plugins/python-standards/.claude-plugin/plugin.json index d7177ee..22db44d 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-dev.1.ticket-directories", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["python", "standards", "uv", "ruff", "pytest", "pyright", "typer", "fastapi", "review"] diff --git a/plugins/salesforce-standards/.claude-plugin/plugin.json b/plugins/salesforce-standards/.claude-plugin/plugin.json index 08ce1a1..0ba2725 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-dev.1.ticket-directories", "author": { "name": "Missing Bits (Jacek Nakonieczny)" }, "license": "MIT", "keywords": ["salesforce", "standards", "apex", "triggers", "lwc", "flow", "aura", "visualforce", "sf-cli", "review"] From fa0ff866e6286f59694dd7cae3ffe388c838c901 Mon Sep 17 00:00:00 2001 From: Jacek Nakonieczny Date: Fri, 13 Nov 2026 15:09:43 +0100 Subject: [PATCH 36/36] chore: mint release versions - working-process 0.19.0, python-standards 0.5.0, salesforce-standards 0.6.0 --- plugins/python-standards/.claude-plugin/plugin.json | 2 +- plugins/python-standards/CHANGELOG.md | 2 +- plugins/salesforce-standards/.claude-plugin/plugin.json | 2 +- plugins/salesforce-standards/CHANGELOG.md | 2 +- plugins/working-process/.claude-plugin/plugin.json | 2 +- plugins/working-process/CHANGELOG.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/python-standards/.claude-plugin/plugin.json b/plugins/python-standards/.claude-plugin/plugin.json index 22db44d..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.5.0-dev.1.ticket-directories", + "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 d0612e9..b6da90f 100644 --- a/plugins/python-standards/CHANGELOG.md +++ b/plugins/python-standards/CHANGELOG.md @@ -2,7 +2,7 @@ Released versions of this plugin, newest first. -## Unreleased +## 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 diff --git a/plugins/salesforce-standards/.claude-plugin/plugin.json b/plugins/salesforce-standards/.claude-plugin/plugin.json index 0ba2725..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.6.0-dev.1.ticket-directories", + "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 980d387..1601271 100644 --- a/plugins/salesforce-standards/CHANGELOG.md +++ b/plugins/salesforce-standards/CHANGELOG.md @@ -2,7 +2,7 @@ Released versions of this plugin, newest first. -## Unreleased +## 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 diff --git a/plugins/working-process/.claude-plugin/plugin.json b/plugins/working-process/.claude-plugin/plugin.json index a5ef94d..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.19.0-dev.4.ticket-directories", + "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 cdb53b9..04cea26 100644 --- a/plugins/working-process/CHANGELOG.md +++ b/plugins/working-process/CHANGELOG.md @@ -2,7 +2,7 @@ Released versions of this plugin, newest first. -## Unreleased +## 0.19.0 — 2026-11-13 - New design specs, technical designs and plans are named `--.md`: the ticket key (`ABC-123`,