diff --git a/.docket.example.yml b/.docket.example.yml index 01edc32c5..c6f3292df 100644 --- a/.docket.example.yml +++ b/.docket.example.yml @@ -250,9 +250,8 @@ change_types: [chore, docs, feat, fix, refactor, perf] # (jira, linear, …), `site` names where it lives (tickets.example.com), and `project` names where # new tickets go. Each is a single line; empty (the default) means not set. # -# No docket command reads these settings yet, so setting them has no effect today. Linking a -# change to a ticket does not consult them either: the ticket a change links to, and its tool, -# are whatever that change's link records. +# Linking a change to a ticket, and creating one from a change, read these settings and ask for +# one that is needed and empty. # # What `project` means, and what kind of ticket each tool creates, depends on the tool: # @@ -268,11 +267,19 @@ change_types: [chore, docs, feat, fix, refactor, perf] # # The `auto` switches name five events: a change is created, its spec is written, its pull # request opens, its pull request merges, or its results are complete. All are off by default, -# and like the settings above, docket does not act on them yet. +# and docket does not act on them yet. # -# These settings belong to the repository, except `companion_skill`: any other value in the global -# config or `.docket.local.yml` is ignored with a warning. -# scope: repo-only (shared-setting guarded) +# Like most settings, these can be set in any layer. `provider` and `site` are usually the same for +# every repository, so the global config suits them. A repository cancels a global value by +# writing the default here (or in `.docket.local.yml` for one clone): +# +# tickets: +# project: "" # cancels a global project for this repository +# auto: +# pr_opened: false # cancels a global true +# +# A bare `project:` with nothing after it is not an empty value and is rejected. +# scope: any layer tickets: provider: "" site: "" @@ -282,9 +289,7 @@ tickets: # team, or yourself), named the way your session's skill list shows it. When a ticket is created # from a change, docket follows it for the project's title format, sprint, fields, labels, and # ticket type. Empty (the default) means docket looks for a skill whose description covers the - # project, and creates the ticket as usual when there is none. Unlike the other ticket settings, - # it may be set in the global config, since a skill is usually installed for you rather than for - # one repository. + # project, and creates the ticket as usual when there is none. # scope: any layer companion_skill: "" diff --git a/docs/reference/config-keys.md b/docs/reference/config-keys.md index 03dfad743..af0823518 100644 --- a/docs/reference/config-keys.md +++ b/docs/reference/config-keys.md @@ -57,21 +57,28 @@ Each key has one scope: | `board.section_order` | `[in-progress, built, blocked, groomed, proposed, deferred]` | any layer | the order of the board's sections | | `board.sorting.
.by` / `.direction` | `updated` / `desc` | any layer | how each board section is sorted | | `change_types` | `[chore, docs, feat, fix, refactor, perf]` | any layer | the types a change can be classified as | -| `tickets.provider` | `""` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket | -| `tickets.site` | `""` (unset) | repo-only | where that ticket system lives; used when linking a ticket by URL or id | -| `tickets.project` | `""` (unset) | repo-only | where new tickets go (a project, team, repository, or board, by tool); used when creating a ticket | +| `tickets.provider` | `""` (unset) | any layer | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket | +| `tickets.site` | `""` (unset) | any layer | where that ticket system lives; used when linking a ticket by URL or id | +| `tickets.project` | `""` (unset) | any layer | where new tickets go (a project, team, repository, or board, by tool); used when creating a ticket | | `tickets.companion_skill` | `""` (unset) | any layer | the skill to follow for project-specific details when creating a ticket (title format, sprint, fields, labels, type) | -| `tickets.auto.change_created` | `false` | repo-only | a switch for when a change is created; no effect yet | -| `tickets.auto.spec_written` | `false` | repo-only | a switch for when a change's spec is written; no effect yet | -| `tickets.auto.pr_opened` | `false` | repo-only | a switch for when a change's pull request opens; no effect yet | -| `tickets.auto.pr_merged` | `false` | repo-only | a switch for when a change's pull request merges; no effect yet | -| `tickets.auto.results_completed` | `false` | repo-only | a switch for when a change's results are complete; no effect yet | +| `tickets.auto.change_created` | `false` | any layer | a switch for when a change is created; no effect yet | +| `tickets.auto.spec_written` | `false` | any layer | a switch for when a change's spec is written; no effect yet | +| `tickets.auto.pr_opened` | `false` | any layer | a switch for when a change's pull request opens; no effect yet | +| `tickets.auto.pr_merged` | `false` | any layer | a switch for when a change's pull request merges; no effect yet | +| `tickets.auto.results_completed` | `false` | any layer | a switch for when a change's results are complete; no effect yet | | `agent_harnesses` | none | any layer | the dispatch opt-in (below) | | `agents...model` / `.effort` | the built-in table | global-only | model and effort pins for docket's agents | -**`tickets`** settings are accepted and checked, but no docket command reads them yet, so setting -them has no effect today. Linking a change to a ticket does not consult them: the ticket a change -links to, and its tool, are whatever that change's link records. +**`tickets`** settings are read by `docket-link-ticket` through `docket diagnostic config` when +you link a change to a ticket or create one from a change: it uses `provider`, `site`, and +`project`, and asks for one it needs when it is empty. The five `auto` switches are reported by the +ticket context, but nothing acts on them yet. Each setting can come from any layer, so `provider` +and `site` can be set once in the global config, and a switch can be tried on one machine in +`.docket.local.yml`. To cancel a global value for one repository, write the default in +`.docket.yml` (for everyone) or `.docket.local.yml` (for this clone): `project: ""` for a setting, +`pr_opened: false` for a switch. A bare `project:` with nothing after it is not an empty value and +is rejected. A private repository reads the global config and `.git/dckt/config.yml`, so its +cancel goes in `.git/dckt/config.yml`. **`agent_harnesses`** opts a repository in to docket's parent-facing dispatch surfaces: the managed block in `CLAUDE.md` / `AGENTS.md` and, for Cursor, `.cursor/rules/docket-dispatch.mdc`. diff --git a/docs/superpowers/specs/2026-11-11-layer-the-tickets-config-keys-at-every-normal-level-not-just-design.md b/docs/superpowers/specs/2026-11-11-layer-the-tickets-config-keys-at-every-normal-level-not-just-design.md new file mode 100644 index 000000000..ec13b7b30 --- /dev/null +++ b/docs/superpowers/specs/2026-11-11-layer-the-tickets-config-keys-at-every-normal-level-not-just-design.md @@ -0,0 +1,55 @@ +# Layer the tickets.* config keys at every normal level + +Change 0592 — Layer the tickets.* config keys at every normal level, not just the repo + +Change #592, groomed 2026-11-10, revised 2026-11-10. + +## Problem + +`internal/config/schema.go` declares nine `tickets.*` keys. One, `tickets.companion_skill`, already uses `scopeAny`. The other eight (`provider`, `site`, `project`, and the five `auto.*` switches) use `scopeRepoOnly`, so a value for any of them in the global config or `.docket.local.yml` is warned and ignored. Most other keys, such as `change_types` and `auto_groom`, use `scopeAny` and layer per field: repo-local > repo-committed > global > built-in. + +The schema comment gives the reason as "They belong to the repository". The repo-only set otherwise holds the repository-identity keys (`integration_branch`, `changes_dir`, `adrs_dir`, `results_dir`), where a machine-level override would make clones disagree about where records live (ADR-0019). No tickets key has that property. + +## Decision + +All eight keys move to `scopeAny`, the same scope `companion_skill` already has. This was decided with the human at grooming, key by key: + +| Key | Why it can layer | +|---|---| +| `provider`, `site` | Usually the same ticket system for every repo a person works in, so the global config is their natural home. Only the `docket-link-ticket` skill reads them, through `diagnostic.config`, and it asks the person when one is empty. Nothing derives a record path, branch name, or other cross-clone value from them. | +| `project` | Usually set per repo in `.docket.yml`, but a person whose repos all file into one project can set it once globally. Linking and creating a ticket is always attended, so a wrong project is caught before a ticket is created. | +| `auto.change_created`, `auto.spec_written`, `auto.pr_opened`, `auto.pr_merged`, `auto.results_completed` | Same shape as `auto_groom`, which already layers. Today `ticket.context` only reports them, and nothing acts on them. A team that wants agreement commits the value in `.docket.yml`. A global value never outranks a committed one, so only the person's own `.docket.local.yml` can override the team's choice. | + +## Unsetting a global value at the repo level + +Every `tickets.*` key defaults to empty (`""`) or `false`, and a value declared in a higher layer wins. So a repo cancels a global value by writing the default explicitly, in `.docket.yml` (for everyone) or `.docket.local.yml` (for this machine): + +```yaml +tickets: + project: "" # cancels a global project for this repo + auto: + pr_opened: false # cancels a global true +``` + +`diagnostic.config` then reports the empty or `false` value with the repo layer as its source. This needs no new mechanism. It is documented in the config reference and in the `.docket.example.yml` comment. + +A bare `project:` (nothing after the colon) is a YAML null, not an empty string, and stays rejected. The rejection message for a string key that accepts an empty value names the fix: write `""` to clear the value. The hint goes in the shared string validator, so every such string key gets it, not just the tickets keys. Null is not newly accepted as "unset", which would make these keys read YAML differently from every other string key. + +## Trace to confirm at build + +1. Re-grep every reader of `eff.Tickets.*` (today: `internal/app/config.go` for `diagnostic.config`, `internal/app/ticket_context.go` for the `auto.*` switches, the `docket-link-ticket` skill) and confirm none needs cross-clone agreement. If a new reader appeared since grooming and does, stop and report rather than moving that key. +2. Check the private-repository path: a private repository keeps its config in `.git/dckt/config.yml` and never reads `.docket.yml`. State what the global layer and `.docket.local.yml` do there, and test it. +3. Confirm `diagnostic.config` reports provenance for a value from each machine layer, and for the explicit `""` / `false` cancel. + +## Build + +- Change the eight scopes in the schema table to `scopeAny`, and rewrite the comment above the block: the ticket settings layer like any other key. +- Add the `""` hint to the rejection message for a null on a string key that accepts empty. +- Update the schema, decode, resolve, and defaults tests that enumerate the keys so each of the eight has global and `.docket.local.yml` cases, including precedence, provenance, and a repo-level cancel of a global value (`""` for strings, `false` for switches). Add a test for the null rejection's hint, and a private-repository case. +- `docs/reference/config-keys.md`: change the eight rows from `repo-only` to `any layer`; replace the stale paragraph under the table ("no docket command reads them yet …") with how the settings are read today, which layers they can come from, and how to cancel a global value. +- `.docket.example.yml`: rewrite the stale comment above the `tickets` block the same way, including the cancel example. +- Update any skill prose that says these values come only from the repository config (`docket-link-ticket`, `docket-update-ticket`), and regenerate embedded assets after skill edits. + +## Out of scope + +Repository-identity keys, new ticket settings, new providers, any new place to read ticket settings from, and accepting YAML null as "unset". diff --git a/internal/app/config_test.go b/internal/app/config_test.go index 14e3634c6..a8b90af2c 100644 --- a/internal/app/config_test.go +++ b/internal/app/config_test.go @@ -966,3 +966,33 @@ func TestConfigDiagnosticsTicketsSurface(t *testing.T) { } } } + +// TestConfigDiagnosticsTicketsMachineLayers pins the provenance DiagnosticConfig +// reports for ticket settings declared in the machine layers, and for the +// explicit ""/false a higher layer writes to cancel a global value. +func TestConfigDiagnosticsTicketsMachineLayers(t *testing.T) { + src := []config.Source{ + {Layer: config.LayerGlobal, Name: "/home/u/.config/docket/config.yml", Data: []byte( + "tickets:\n provider: jira\n project: CLOUD\n auto:\n pr_opened: true\n")}, + {Layer: config.LayerRepository, Name: ".docket.yml", Data: []byte("tickets:\n project: \"\"\n")}, + {Layer: config.LayerRepositoryLocal, Name: ".docket.local.yml", Data: []byte( + "tickets:\n auto:\n pr_opened: false\n site: tickets.example.com\n")}, + } + r := DiagnosticConfig(src, mainCtx(), false) + text := r.HumanText() + for _, want := range []string{ + "tickets.provider = jira [global /home/u/.config/docket/config.yml:2]", + "tickets.project = (unset) [repository .docket.yml:2]", + "tickets.site = tickets.example.com [repository-local .docket.local.yml:4]", + "tickets.auto.pr_opened = false [repository-local .docket.local.yml:3]", + } { + if !strings.Contains(text, want) { + t.Errorf("inspection lacks %q:\n%s", want, text) + } + } + for _, d := range r.Diagnostics { + if d.Code == config.CodeSharedSettingIgnored { + t.Errorf("unexpected %s diagnostic for %s", d.Code, d.Path) + } + } +} diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index e31ab1cff..8449ab657 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,14 +1,14 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:db8870e2ba32c5fde8ed4698ddb53a478d6b49cb2493ed05973aa28ff1df169c", + "asset_set_id": "sha256:d28bf7a5a890737ec3cb057b95cd07afa527adb64fc2c05a0c456ffcdb20883b", "entries": [ { "path": ".docket.example.yml", "role": "config-schema", "mode": 420, - "size": 24509, - "sha256": "895433aad374061e9cbc530f39655714a2b7d0a414a89d54ce320e7e95f755d5" + "size": 24542, + "sha256": "c36753fd7c45af579c42af58d5b994f40a9b6002594d8766954aafadbd90de46" }, { "path": "agents/docket-adr.md", diff --git a/internal/assets/embedded/tree/.docket.example.yml b/internal/assets/embedded/tree/.docket.example.yml index 01edc32c5..c6f3292df 100644 --- a/internal/assets/embedded/tree/.docket.example.yml +++ b/internal/assets/embedded/tree/.docket.example.yml @@ -250,9 +250,8 @@ change_types: [chore, docs, feat, fix, refactor, perf] # (jira, linear, …), `site` names where it lives (tickets.example.com), and `project` names where # new tickets go. Each is a single line; empty (the default) means not set. # -# No docket command reads these settings yet, so setting them has no effect today. Linking a -# change to a ticket does not consult them either: the ticket a change links to, and its tool, -# are whatever that change's link records. +# Linking a change to a ticket, and creating one from a change, read these settings and ask for +# one that is needed and empty. # # What `project` means, and what kind of ticket each tool creates, depends on the tool: # @@ -268,11 +267,19 @@ change_types: [chore, docs, feat, fix, refactor, perf] # # The `auto` switches name five events: a change is created, its spec is written, its pull # request opens, its pull request merges, or its results are complete. All are off by default, -# and like the settings above, docket does not act on them yet. +# and docket does not act on them yet. # -# These settings belong to the repository, except `companion_skill`: any other value in the global -# config or `.docket.local.yml` is ignored with a warning. -# scope: repo-only (shared-setting guarded) +# Like most settings, these can be set in any layer. `provider` and `site` are usually the same for +# every repository, so the global config suits them. A repository cancels a global value by +# writing the default here (or in `.docket.local.yml` for one clone): +# +# tickets: +# project: "" # cancels a global project for this repository +# auto: +# pr_opened: false # cancels a global true +# +# A bare `project:` with nothing after it is not an empty value and is rejected. +# scope: any layer tickets: provider: "" site: "" @@ -282,9 +289,7 @@ tickets: # team, or yourself), named the way your session's skill list shows it. When a ticket is created # from a change, docket follows it for the project's title format, sprint, fields, labels, and # ticket type. Empty (the default) means docket looks for a skill whose description covers the - # project, and creates the ticket as usual when there is none. Unlike the other ticket settings, - # it may be set in the global config, since a skill is usually installed for you rather than for - # one repository. + # project, and creates the ticket as usual when there is none. # scope: any layer companion_skill: "" diff --git a/internal/config/private_source_test.go b/internal/config/private_source_test.go index 7762084b0..d505018a6 100644 --- a/internal/config/private_source_test.go +++ b/internal/config/private_source_test.go @@ -98,3 +98,45 @@ func TestSharedSettingRemedyNamesPrivateConfig(t *testing.T) { t.Errorf("remedy = %q, want it to name .git/dckt/config.yml and not .docket.yml", r) } } + +// TestPrivateRepositoryTicketsLayerOverGlobal: a private repository reads the +// global config and then .git/dckt/config.yml, so a global ticket value is +// honoured there and the private config cancels one by declaring the default. +func TestPrivateRepositoryTicketsLayerOverGlobal(t *testing.T) { + tmp := pinEnv(t) + repo := t.TempDir() + writeFile(t, filepath.Join(repo, ".git", "dckt", "config.yml"), + "visibility: private\ntickets:\n project: \"\"\n auto:\n pr_opened: false\n") + global := filepath.Join(tmp, "global.yml") + writeFile(t, global, + "tickets:\n provider: jira\n site: tickets.example.com\n project: CLOUD\n auto:\n pr_opened: true\n") + + got, err := LoadFilesystemSources(FSOptions{RepoDir: repo, GlobalPath: global}) + if err != nil { + t.Fatalf("LoadFilesystemSources: %v", err) + } + if len(got) != 2 || got[0].Layer != LayerGlobal || + got[1].Layer != LayerRepository || got[1].Name != ".git/dckt/config.yml" { + t.Fatalf("sources = %+v, want [global, {repository .git/dckt/config.yml}]", got) + } + snap, _, err := Resolve(got, mainCtx) + if err != nil { + t.Fatalf("Resolve: %v", err) + } + tk := snap.Effective.Tickets + if tk.Provider.Value != "jira" || tk.Provider.Provenance.Layer != LayerGlobal { + t.Errorf("provider = %+v, want jira from the global layer", tk.Provider) + } + if tk.Site.Value != "tickets.example.com" || tk.Site.Provenance.Layer != LayerGlobal { + t.Errorf("site = %+v, want tickets.example.com from the global layer", tk.Site) + } + if tk.Project.Value != "" || !tk.Project.Explicit || tk.Project.Provenance.Layer != LayerRepository { + t.Errorf("project = %+v, want an explicit \"\" from the private config", tk.Project) + } + if tk.Auto.PROpened.Value || !tk.Auto.PROpened.Explicit || tk.Auto.PROpened.Provenance.Layer != LayerRepository { + t.Errorf("auto.pr_opened = %+v, want an explicit false from the private config", tk.Auto.PROpened) + } + if ignored := diagPathSet(snap, CodeSharedSettingIgnored); len(ignored) != 0 { + t.Errorf("unexpected %s diagnostics: %v", CodeSharedSettingIgnored, ignored) + } +} diff --git a/internal/config/resolve_test.go b/internal/config/resolve_test.go index f34613f8e..59563acc7 100644 --- a/internal/config/resolve_test.go +++ b/internal/config/resolve_test.go @@ -637,58 +637,6 @@ func guardCases() []guardCase { {"github_project", "github_project: {owner: acme, number: 7}\n", "github_project: auto\n", githubProject{Owner: "acme", Number: 7}}, {"terminal_publish", "terminal_publish: true\n", "terminal_publish: false\n", true}, - {"tickets.provider", "tickets:\n provider: jira\n", "tickets:\n provider: linear\n", "jira"}, - {"tickets.site", "tickets:\n site: tickets.example.com\n", "tickets:\n site: other.example.com\n", "tickets.example.com"}, - {"tickets.project", "tickets:\n project: CLOUD\n", "tickets:\n project: OPS\n", "CLOUD"}, - {"tickets.auto.change_created", "tickets:\n auto: {change_created: true}\n", "tickets:\n auto: {change_created: false}\n", true}, - {"tickets.auto.spec_written", "tickets:\n auto: {spec_written: true}\n", "tickets:\n auto: {spec_written: false}\n", true}, - {"tickets.auto.pr_opened", "tickets:\n auto: {pr_opened: true}\n", "tickets:\n auto: {pr_opened: false}\n", true}, - {"tickets.auto.pr_merged", "tickets:\n auto: {pr_merged: true}\n", "tickets:\n auto: {pr_merged: false}\n", true}, - {"tickets.auto.results_completed", "tickets:\n auto: {results_completed: true}\n", "tickets:\n auto: {results_completed: false}\n", true}, - } -} - -// TestTicketsKeysRepoOnly: the ticket settings belong to the repository. A -// machine layer (global or repository-local) declaring one is warned about -// per key and leaves the built-in value in force; the committed layer's -// declaration resolves with repository provenance and blocks nothing. -func TestTicketsKeysRepoOnly(t *testing.T) { - const doc = "tickets:\n provider: jira\n auto:\n pr_opened: true\n" - for _, build := range []func(string) Source{srcG, srcL} { - src := build(doc) - t.Run(string(src.Layer), func(t *testing.T) { - snap := mustSnapshot(t, src) - ignored := diagPathSet(snap, CodeSharedSettingIgnored) - for _, p := range []string{"tickets.provider", "tickets.auto.pr_opened"} { - if !ignored[p] { - t.Errorf("%s declared in the %s layer produced no shared-setting-ignored warning", p, src.Layer) - } - } - for _, d := range snap.Diagnostics { - if d.Code == CodeSharedSettingIgnored && d.Severity != SeverityWarning { - t.Errorf("%s: severity %q, want warning", d.Path, d.Severity) - } - } - eff := snap.Effective - if eff.Tickets.Provider.Value != "" || eff.Tickets.Provider.Explicit { - t.Errorf("tickets.provider = %q (explicit %v), want the built-in \"\"", eff.Tickets.Provider.Value, eff.Tickets.Provider.Explicit) - } - if eff.Tickets.Auto.PROpened.Value || eff.Tickets.Auto.PROpened.Explicit { - t.Errorf("tickets.auto.pr_opened = %v (explicit %v), want the built-in false", eff.Tickets.Auto.PROpened.Value, eff.Tickets.Auto.PROpened.Explicit) - } - }) - } - - snap := mustSnapshot(t, srcR(doc)) - eff := snap.Effective - if eff.Tickets.Provider.Value != "jira" || eff.Tickets.Provider.Provenance.Layer != LayerRepository { - t.Errorf("tickets.provider = %q from %q, want jira from the repository layer", eff.Tickets.Provider.Value, eff.Tickets.Provider.Provenance.Layer) - } - if !eff.Tickets.Auto.PROpened.Value || eff.Tickets.Auto.PROpened.Provenance.Layer != LayerRepository { - t.Errorf("tickets.auto.pr_opened = %v from %q, want true from the repository layer", eff.Tickets.Auto.PROpened.Value, eff.Tickets.Auto.PROpened.Provenance.Layer) - } - if !PreflightMutation(snap).Allowed { - t.Errorf("preflight blocked a repository declaring ticket settings: %v", blockerPaths(snap)) } } @@ -712,6 +660,21 @@ func TestTicketsStringSingleLine(t *testing.T) { } } +// TestTicketsBareKeyIsRejectedWithHint: a bare ticket key is rejected with a +// message naming the fix, and the fix it names is accepted. +func TestTicketsBareKeyIsRejectedWithHint(t *testing.T) { + _, diags := decodeDoc(t, "tickets:\n project:\n") + if len(diags) != 1 || diags[0].Code != CodeInvalidType || diags[0].Path != "tickets.project" { + t.Fatalf("want one %s diagnostic at tickets.project, got %+v", CodeInvalidType, diags) + } + if !strings.Contains(diags[0].Message, `write "" to clear the value`) { + t.Errorf("message %q does not name the empty-string fix", diags[0].Message) + } + if _, diags := decodeDoc(t, "tickets:\n project: \"\"\n"); len(diags) != 0 { + t.Errorf("project: \"\" should be accepted, got %+v", diags) + } +} + // TestEverySharedSettingGuard asserts BOTH halves for every repo-only row in both machine // layers: the machine declaration is warned about at ITS OWN provenance, and // the committed layer's value is the one that resolves. A warning alone would @@ -1521,50 +1484,6 @@ func TestOpenArtifactsIsAnOrdinaryLayeredKey(t *testing.T) { } } -// TestTicketsCompanionSkillAnyLayer pins tickets.companion_skill as the one -// ticket leaf settable at any layer (change 0591): it names the person's own -// tooling, so a global or local declaration is honoured with ordinary -// precedence and never draws the shared-setting warning its repo-only -// siblings get, even when declared in the same block. -func TestTicketsCompanionSkillAnyLayer(t *testing.T) { - doc := func(v string) string { return "tickets:\n companion_skill: " + v + "\n" } - if v := mustSnapshot(t).Effective.Tickets.CompanionSkill; v.Value != "" || v.Provenance.Layer != LayerBuiltIn || v.Explicit { - t.Fatalf("default = %+v, want non-explicit built-in empty", v) - } - for _, tc := range []struct { - name string - sources []Source - want string - layer LayerKind - }{ - {"global", []Source{srcG(doc("a"))}, "a", LayerGlobal}, - {"local", []Source{srcL(doc("a"))}, "a", LayerRepositoryLocal}, - {"repository over global", []Source{srcG(doc("a")), srcR(doc("b"))}, "b", LayerRepository}, - {"local over repository", []Source{srcR(doc("b")), srcL(doc("c"))}, "c", LayerRepositoryLocal}, - {"local over global", []Source{srcG(doc("a")), srcL(doc("c"))}, "c", LayerRepositoryLocal}, - } { - snap := mustSnapshot(t, tc.sources...) - if v := snap.Effective.Tickets.CompanionSkill; v.Value != tc.want || v.Provenance.Layer != tc.layer || !v.Explicit { - t.Errorf("%s: companion_skill = %+v, want explicit %q from %q", tc.name, v, tc.want, tc.layer) - } - if diagPathSet(snap, CodeSharedSettingIgnored)["tickets.companion_skill"] { - t.Errorf("%s: companion_skill drew %s", tc.name, CodeSharedSettingIgnored) - } - } - - snap := mustSnapshot(t, srcG("tickets:\n provider: jira\n companion_skill: team-tickets\n")) - ignored := diagPathSet(snap, CodeSharedSettingIgnored) - if !ignored["tickets.provider"] || snap.Effective.Tickets.Provider.Value != "" { - t.Errorf("mixed block: provider = %+v, ignored=%v; want the global provider warned about and dropped", snap.Effective.Tickets.Provider, ignored) - } - if ignored["tickets.companion_skill"] { - t.Errorf("mixed block: companion_skill drew %s", CodeSharedSettingIgnored) - } - if v := snap.Effective.Tickets.CompanionSkill; v.Value != "team-tickets" || v.Provenance.Layer != LayerGlobal || !v.Explicit { - t.Errorf("mixed block: companion_skill = %+v, want explicit team-tickets from global", v) - } -} - // The shipped implement-next TTL obeys the same per-field layering as model and // effort: a model-only override keeps it, and a global `auto` or `5m` replaces it. func TestAgentsShippedCacheTTLLayering(t *testing.T) { @@ -1585,3 +1504,100 @@ func TestAgentsShippedCacheTTLLayering(t *testing.T) { } } } + +// ticketsDoc renders one tickets leaf as a YAML document: tickets.X as a +// direct child of tickets, tickets.auto.X under the auto block. +func ticketsDoc(path, literal string) string { + leaf := strings.TrimPrefix(path, "tickets.") + if ev, ok := strings.CutPrefix(leaf, "auto."); ok { + return "tickets:\n auto:\n " + ev + ": " + literal + "\n" + } + return "tickets:\n " + leaf + ": " + literal + "\n" +} + +// TestTicketsKeysAnyLayer: every ticket setting layers like any other key. A +// global or repository-local declaration is honoured with ordinary per-field +// precedence and never draws shared-setting-ignored, and a higher layer +// cancels a global value by declaring the default ("" or false) explicitly. +// The population is derived from the registry so a new tickets row is covered. +func TestTicketsKeysAnyLayer(t *testing.T) { + var rows []pathSpec + seen := map[string]bool{} + for _, spec := range registry() { + if strings.HasPrefix(spec.path, "tickets.") { + rows = append(rows, spec) + seen[spec.path] = true + } + } + if len(rows) != 9 || !seen["tickets.provider"] || !seen["tickets.auto.results_completed"] { + t.Fatalf("tickets population = %v, want the nine ticket settings", seen) + } + + for _, spec := range rows { + path := spec.path + var g, r, l, cancel string + var gv, rv, lv, zero any + switch spec.kind { + case kindString: + g, r, l, cancel = "g-val", "r-val", "l-val", `""` + gv, rv, lv, zero = "g-val", "r-val", "l-val", "" + case kindBool: + g, r, l, cancel = "true", "false", "true", "false" + gv, rv, lv, zero = true, false, true, false + default: + t.Fatalf("%s: unexpected kind %v", path, spec.kind) + } + doc := func(lit string) string { return ticketsDoc(path, lit) } + + t.Run(path+"/default", func(t *testing.T) { + snap := mustSnapshot(t) + v, prov, explicit := effectiveLeaf(t, snap.Effective, path) + if v != zero || explicit || prov.Layer != LayerBuiltIn { + t.Errorf("default = %v (explicit %v) from %q, want non-explicit built-in %v", v, explicit, prov.Layer, zero) + } + }) + for _, tc := range []struct { + name string + sources []Source + want any + layer LayerKind + }{ + {"global", []Source{srcG(doc(g))}, gv, LayerGlobal}, + {"local", []Source{srcL(doc(l))}, lv, LayerRepositoryLocal}, + {"repo over global", []Source{srcG(doc(g)), srcR(doc(r))}, rv, LayerRepository}, + {"local over repo", []Source{srcR(doc(r)), srcL(doc(l))}, lv, LayerRepositoryLocal}, + {"repo cancels global", []Source{srcG(doc(g)), srcR(doc(cancel))}, zero, LayerRepository}, + {"local cancels global", []Source{srcG(doc(g)), srcL(doc(cancel))}, zero, LayerRepositoryLocal}, + } { + t.Run(path+"/"+tc.name, func(t *testing.T) { + snap := mustSnapshot(t, tc.sources...) + v, prov, explicit := effectiveLeaf(t, snap.Effective, path) + if v != tc.want || prov.Layer != tc.layer || !explicit { + t.Errorf("%s = %v (explicit %v) from %q, want explicit %v from %q", path, v, explicit, prov.Layer, tc.want, tc.layer) + } + if diagPathSet(snap, CodeSharedSettingIgnored)[path] { + t.Errorf("%s drew %s", path, CodeSharedSettingIgnored) + } + }) + } + } + + t.Run("mixed block", func(t *testing.T) { + snap := mustSnapshot(t, + srcG("tickets:\n provider: jira\n project: CLOUD\n"), + srcR("tickets:\n project: OPS\n")) + eff := snap.Effective + if v := eff.Tickets.Provider; v.Value != "jira" || v.Provenance.Layer != LayerGlobal { + t.Errorf("provider = %+v, want jira from the global layer", v) + } + if v := eff.Tickets.Project; v.Value != "OPS" || v.Provenance.Layer != LayerRepository { + t.Errorf("project = %+v, want OPS from the repository layer", v) + } + if ignored := diagPathSet(snap, CodeSharedSettingIgnored); len(ignored) != 0 { + t.Errorf("unexpected %s diagnostics: %v", CodeSharedSettingIgnored, ignored) + } + if !PreflightMutation(snap).Allowed { + t.Errorf("preflight blocked a layered tickets block: %v", blockerPaths(snap)) + } + }) +} diff --git a/internal/config/schema.go b/internal/config/schema.go index a24c63a95..ccd515bfd 100644 --- a/internal/config/schema.go +++ b/internal/config/schema.go @@ -383,33 +383,33 @@ func buildRegistry() []pathSpec { })}, // The ticket settings: which ticket system a repository links to, where - // new tickets go, and the per-event automation switches. They belong to - // the repository, so a machine layer's declaration is ignored with a - // warning. The one exception is companion_skill, which names the - // person's own tooling (a skill usually installed for the user, in every - // repository) and so is set at any layer. + // new tickets go, the person's companion skill, and the per-event + // automation switches. They layer like any other key, because nothing + // derives a record path, branch, or other value every clone must agree + // on from them. A repository cancels a global value by declaring the + // default ("" or false). {path: "tickets.provider", kind: kindString, def: "", - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: singleLineStringLeaf()}, {path: "tickets.site", kind: kindString, def: "", - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: singleLineStringLeaf()}, {path: "tickets.project", kind: kindString, def: "", - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: singleLineStringLeaf()}, {path: "tickets.companion_skill", kind: kindString, def: "", merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: singleLineStringLeaf()}, {path: "tickets.auto.change_created", kind: kindBool, def: false, - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: boolLeaf()}, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.spec_written", kind: kindBool, def: false, - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: boolLeaf()}, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.pr_opened", kind: kindBool, def: false, - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: boolLeaf()}, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.pr_merged", kind: kindBool, def: false, - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: boolLeaf()}, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, {path: "tickets.auto.results_completed", kind: kindBool, def: false, - merge: mergeScalar, scope: scopeRepoOnly, disp: dispSupported, validate: boolLeaf()}, + merge: mergeScalar, scope: scopeAny, disp: dispSupported, validate: boolLeaf()}, // 25-26: auto capture. The subset check against effective change_types // cannot run here — it is cross-leaf, so resolution owns it. @@ -601,6 +601,11 @@ func enumLeaf(allowed ...string) leafValidator { // requires a clean, relative, parent-free path. func stringLeaf(nonEmpty, spaceFree, relPath bool) leafValidator { return func(src Source, path string, n *yaml.Node) (any, []Diagnostic) { + // A bare key on a setting that accepts the empty string: name the fix. + if !nonEmpty && !relPath && n.Kind == yaml.ScalarNode && n.Tag == tagNull { + return nil, []Diagnostic{leafDiag(src, path, CodeInvalidType, n, + `expects a string, got an empty value; write "" to clear the value`)} + } if diags := scalarWithTag(src, path, n, tagStr, "a string"); diags != nil { return nil, diags } diff --git a/internal/config/schema_test.go b/internal/config/schema_test.go index f270c0907..5428ec034 100644 --- a/internal/config/schema_test.go +++ b/internal/config/schema_test.go @@ -87,9 +87,6 @@ func TestRegistryRepoOnlySet(t *testing.T) { "integration_branch", "changes_dir", "adrs_dir", "results_dir", "github_project", "terminal_publish", - "tickets.provider", "tickets.site", "tickets.project", - "tickets.auto.change_created", "tickets.auto.spec_written", "tickets.auto.pr_opened", - "tickets.auto.pr_merged", "tickets.auto.results_completed", } wantLocalOnly := []string{"runtime.bash"} @@ -542,3 +539,50 @@ func TestAgentHarnessTokensIsACopy(t *testing.T) { t.Fatalf("mutation leaked into the next call: %v", again) } } + +// TestStringNullNamesEmptyStringFix: a bare null on a string setting that +// accepts the empty string names the fix (write ""); a string setting that +// rejects empty never suggests it. Both sets come from the registry. +func TestStringNullNamesEmptyStringFix(t *testing.T) { + emptyStr := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: ""} + nullNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!null"} + accepts := map[string]pathSpec{} + rejects := map[string]pathSpec{} + for _, spec := range registry() { + if spec.kind != kindString || spec.validate == nil { + continue + } + if _, diags := spec.validate(repoSource(""), spec.path, emptyStr); diags == nil { + accepts[spec.path] = spec + } else { + rejects[spec.path] = spec + } + } + for _, p := range []string{"tickets.provider", "tickets.project", "finalize.test_command"} { + if _, ok := accepts[p]; !ok { + t.Errorf("population floor: %s should accept the empty string", p) + } + } + if _, ok := rejects["changes_dir"]; !ok { + t.Errorf("population floor: changes_dir should reject the empty string") + } + for p, spec := range accepts { + _, diags := spec.validate(repoSource(""), p, nullNode) + if len(diags) != 1 || diags[0].Code != CodeInvalidType { + t.Errorf("%s: want one %s diagnostic for null, got %+v", p, CodeInvalidType, diags) + continue + } + m := diags[0].Message + if !strings.Contains(m, "expects a string, got an empty value") || !strings.Contains(m, `write "" to clear the value`) { + t.Errorf("%s: null message %q does not name the empty-string fix", p, m) + } + } + for p, spec := range rejects { + _, diags := spec.validate(repoSource(""), p, nullNode) + for _, d := range diags { + if strings.Contains(d.Message, `write ""`) { + t.Errorf("%s: rejects empty but null message %q suggests writing \"\"", p, d.Message) + } + } + } +} diff --git a/internal/config/setting_paths_test.go b/internal/config/setting_paths_test.go index 278ef7243..229e2ad3d 100644 --- a/internal/config/setting_paths_test.go +++ b/internal/config/setting_paths_test.go @@ -13,10 +13,7 @@ import ( // the leaves a machine layer may not declare and a visibility switch never // carries out of the local file. func TestRepoOnlyPaths(t *testing.T) { - want := []string{"integration_branch", "changes_dir", "adrs_dir", "results_dir", "github_project", "terminal_publish", - "tickets.provider", "tickets.site", "tickets.project", - "tickets.auto.change_created", "tickets.auto.spec_written", "tickets.auto.pr_opened", - "tickets.auto.pr_merged", "tickets.auto.results_completed"} + want := []string{"integration_branch", "changes_dir", "adrs_dir", "results_dir", "github_project", "terminal_publish"} got := RepoOnlyPaths() if len(got) != len(want) { t.Fatalf("RepoOnlyPaths() = %v, want %v", got, want) diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 0802f83cf..a15e45074 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -1735,7 +1735,7 @@ var alignmentContracts = []proseContract{ absent: []string{"work with you before posting"}}, {sentinel: "change_0585_update_ticket_skill", file: "docs/reference/config-keys.md", present: []string{ - "| `tickets.provider` | `\"\"` (unset) | repo-only | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket |", + "| `tickets.provider` | `\"\"` (unset) | any layer | the ticket system this repository's changes link to (jira, linear, …); used when linking or creating a ticket |", "; used when linking a ticket by URL or id |", "; used when creating a ticket |", }, @@ -1766,6 +1766,33 @@ var alignmentContracts = []proseContract{ absent: []string{"never rewritten", "cannot be rewritten", "written once"}}, {sentinel: "change_0591_companion_skill", file: "docs/reference/config-keys.md", present: []string{"| `tickets.companion_skill` | `\"\"` (unset) | any layer |"}}, + // change 0592 — every tickets.* key layers like any other key, and a repository cancels a global value by writing the default. + {sentinel: "change_0592_tickets_any_layer", file: "docs/reference/config-keys.md", + present: []string{ + "| `tickets.site` | `\"\"` (unset) | any layer |", + "| `tickets.project` | `\"\"` (unset) | any layer |", + "| `tickets.auto.change_created` | `false` | any layer |", + "| `tickets.auto.spec_written` | `false` | any layer |", + "| `tickets.auto.pr_opened` | `false` | any layer |", + "| `tickets.auto.pr_merged` | `false` | any layer |", + "| `tickets.auto.results_completed` | `false` | any layer |", + "`project: \"\"`", + "`pr_opened: false`", + ".git/dckt/config.yml", + }, + absent: []string{ + "no docket command reads them yet", + "Linking a change to a ticket does not consult them", + "| repo-only | the ticket system ", + "| repo-only | a switch for ", + }}, + {sentinel: "change_0592_tickets_any_layer", file: ".docket.example.yml", + present: []string{"# project: \"\"", "# pr_opened: false"}, + absent: []string{ + "No docket command reads these settings yet", + "These settings belong to the repository", + "Unlike the other ticket settings", + }}, } // oneLayoutAbsent are the retired metadata-layout spellings. diff --git a/internal/reposetup/visibilityconfig_test.go b/internal/reposetup/visibilityconfig_test.go index 4cdd44716..89be5c202 100644 --- a/internal/reposetup/visibilityconfig_test.go +++ b/internal/reposetup/visibilityconfig_test.go @@ -338,3 +338,39 @@ func TestSplitOfFoldDeclaresTheHandFormattedLeaves(t *testing.T) { t.Errorf("SameConfigLeaves(hand, split) = %v, %v; want true\nsplit:\n%s", same, err, committed) } } + +// TestFoldPrivateConfigCarriesLocalTicketsKeys: ticket settings layer at any +// level, so going private carries a ticket leaf from .docket.local.yml into the +// private config rather than dropping it, and going shared routes it back to +// the local file. +func TestFoldPrivateConfigCarriesLocalTicketsKeys(t *testing.T) { + committedIn := []byte("tickets:\n provider: jira\n") + localIn := []byte("tickets:\n project: OPS\n auto:\n pr_opened: true\n") + paths := []string{"tickets.provider", "tickets.project", "tickets.auto.pr_opened"} + + folded, dropped, err := FoldPrivateConfig(committedIn, localIn, repoOnlyForTest()) + if err != nil { + t.Fatalf("FoldPrivateConfig: %v", err) + } + if len(dropped) != 0 { + t.Errorf("dropped = %v, want none", dropped) + } + want := map[string]string{"tickets.provider": "jira", "tickets.project": "OPS", "tickets.auto.pr_opened": "true"} + if got := leafValues(t, folded, paths...); !reflect.DeepEqual(got, want) { + t.Errorf("folded leaves = %v, want %v\n%s", got, want, folded) + } + mustResolve(t, folded, nil) + + committed, local, err := SplitPrivateConfig(folded, localIn, repoOnlyForTest()) + if err != nil { + t.Fatalf("SplitPrivateConfig: %v", err) + } + if got, wantC := leafValues(t, committed, paths...), map[string]string{"tickets.provider": "jira"}; !reflect.DeepEqual(got, wantC) { + t.Errorf("committed leaves = %v, want %v\n%s", got, wantC, committed) + } + wantL := map[string]string{"tickets.project": "OPS", "tickets.auto.pr_opened": "true"} + if got := leafValues(t, local, paths...); !reflect.DeepEqual(got, wantL) { + t.Errorf("local leaves = %v, want %v\n%s", got, wantL, local) + } + mustResolve(t, committed, local) +}