Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 15 additions & 10 deletions .docket.example.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
#
Expand All @@ -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: ""
Expand All @@ -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: ""

Expand Down
29 changes: 18 additions & 11 deletions docs/reference/config-keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<section>.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.<harness>.<agent>.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`.
Expand Down
Original file line number Diff line number Diff line change
@@ -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".
30 changes: 30 additions & 0 deletions internal/app/config_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
}
6 changes: 3 additions & 3 deletions internal/assets/embedded/manifest.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

25 changes: 15 additions & 10 deletions internal/assets/embedded/tree/.docket.example.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

42 changes: 42 additions & 0 deletions internal/config/private_source_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
Loading
Loading