@luminascale/shepherd 0.0.0-stage → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# Implementation Plan: Per-workspace self-contained Shepherd settings
|
|
2
|
+
|
|
3
|
+
This plan migrates pi-shepherd's existing settings implementation to the
|
|
4
|
+
per-workspace activation and self-contained project-file model already used by
|
|
5
|
+
pi-zvec-grep. The change is intentionally staged so the config core is settled
|
|
6
|
+
before the menu, runtime fixtures, and documentation are updated.
|
|
7
|
+
|
|
8
|
+
## Target architecture
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
user config (values only) ───────────────┐
|
|
12
|
+
│ inactive project
|
|
13
|
+
▼
|
|
14
|
+
effective user values
|
|
15
|
+
|
|
16
|
+
project config (values + projectScope) ─┐
|
|
17
|
+
│ projectScope: true
|
|
18
|
+
▼
|
|
19
|
+
built-in defaults + project values
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`projectScope` is read from the project file for the current cwd. It is never a
|
|
23
|
+
machine-global switch and is never taken from the user file.
|
|
24
|
+
|
|
25
|
+
## Design decisions
|
|
26
|
+
|
|
27
|
+
1. **Per-workspace activation** — move scope ownership from the user file to
|
|
28
|
+
`.shepherd/config.json`, so activating one repository cannot affect another.
|
|
29
|
+
2. **Self-contained project files** — write every project-overridable Shepherd
|
|
30
|
+
value to an active project file; do not write a delta against the current
|
|
31
|
+
user's preferences. `confirmProjectAgents` is the user-owned security
|
|
32
|
+
exception and is never project-controlled.
|
|
33
|
+
3. **Built-in fallback for active projects** — an active project file is
|
|
34
|
+
portable. Missing or invalid values fall back to `DEFAULT_SETTINGS`, never
|
|
35
|
+
to the user's private values.
|
|
36
|
+
4. **Dormant legacy files are safe by default** — keyless project files remain
|
|
37
|
+
inactive until explicitly activated. This avoids silently enabling old
|
|
38
|
+
repository-controlled deltas during migration.
|
|
39
|
+
5. **Read-only legacy compatibility** — accept project
|
|
40
|
+
`settingsScope: "project"` as active, but write only boolean
|
|
41
|
+
`projectScope` going forward.
|
|
42
|
+
6. **Parked-value preservation** — deactivation keeps project values, and
|
|
43
|
+
reactivation restores those values rather than replacing them with user
|
|
44
|
+
values.
|
|
45
|
+
7. **No public lifecycle API change** — runtime code consumes the same setting
|
|
46
|
+
names and `loadSettings(cwd)` result; only the scope metadata and config
|
|
47
|
+
persistence internals change.
|
|
48
|
+
8. **Project settings can be committed deliberately** — adjust `.gitignore` to
|
|
49
|
+
ignore fieldnote sessions while allowing an explicit `.shepherd/config.json`
|
|
50
|
+
exception.
|
|
51
|
+
9. **Repository configs cannot weaken the trust gate** — `confirmProjectAgents`
|
|
52
|
+
remains in the user layer. A committed project file may select project agent
|
|
53
|
+
definitions but cannot suppress interactive confirmation.
|
|
54
|
+
|
|
55
|
+
## Phase 1 — Replace the configuration model
|
|
56
|
+
|
|
57
|
+
Update `src/extension/config.ts`:
|
|
58
|
+
|
|
59
|
+
- Replace `ConfigScope` and `settingsScope` with `projectScope: boolean` on the
|
|
60
|
+
effective settings type.
|
|
61
|
+
- Keep the existing nine value fields, defaults, validators, timeout migration,
|
|
62
|
+
and per-file mtime cache.
|
|
63
|
+
- Treat `confirmProjectAgents` as user-only: validate/read/write it only in the
|
|
64
|
+
user layer, ignore any project-file copy, and retain it when resolving an
|
|
65
|
+
active project.
|
|
66
|
+
- Keep `userConfigFile()` and `projectConfigFile()` paths unchanged.
|
|
67
|
+
- Make `validateLayer()` parse `projectScope` and the legacy project
|
|
68
|
+
`settingsScope` string, while ensuring scope flags from the user file are
|
|
69
|
+
ignored for resolution.
|
|
70
|
+
- Implement the zvec-style `loadSettings(cwd)` resolution algorithm.
|
|
71
|
+
- Add `loadProjectFileValues(cwd)`.
|
|
72
|
+
- Add `deactivateProjectScope(cwd)`.
|
|
73
|
+
- Replace delta-writing project saves with full project writes containing all
|
|
74
|
+
project-overridable fields plus `projectScope`; never write
|
|
75
|
+
`confirmProjectAgents` to a project file.
|
|
76
|
+
- Make user saves values-only and strip legacy scope keys.
|
|
77
|
+
- Remove `overlayProject()` and `loadProjectDelta()` once all callers are
|
|
78
|
+
migrated.
|
|
79
|
+
- Preserve the existing `settings.json` → `config.json` migration and timeout
|
|
80
|
+
unit migration.
|
|
81
|
+
- Update cache entries after project activation, deactivation, and user saves.
|
|
82
|
+
|
|
83
|
+
The implementation should use the zvec-grep implementation as the behavioral
|
|
84
|
+
reference, adapted to Shepherd's larger settings object and existing legacy
|
|
85
|
+
migrations.
|
|
86
|
+
|
|
87
|
+
## Phase 2 — Rewrite the settings menu
|
|
88
|
+
|
|
89
|
+
Update `src/extension/settings-ui.ts`:
|
|
90
|
+
|
|
91
|
+
- Change the scope item id from `settingsScope` to `projectScope`.
|
|
92
|
+
- Import `deactivateProjectScope`, `loadProjectFileValues`, and
|
|
93
|
+
`projectConfigFile`.
|
|
94
|
+
- Add the three scope display states: `project`,
|
|
95
|
+
`user (project file dormant)`, and `user`.
|
|
96
|
+
- On project activation, merge parked project values before saving a complete
|
|
97
|
+
project file with `projectScope: true`; preserve the trusted user-layer
|
|
98
|
+
`confirmProjectAgents` value separately.
|
|
99
|
+
- On user selection, call `deactivateProjectScope()` rather than changing a
|
|
100
|
+
user-file pointer.
|
|
101
|
+
- Route non-scope changes to the user file or complete project file according
|
|
102
|
+
to the effective workspace scope; always persist `confirmProjectAgents` in
|
|
103
|
+
the user file.
|
|
104
|
+
- Resync state and display after every successful change.
|
|
105
|
+
- Preserve existing notifications, especially the next-session fieldnotes
|
|
106
|
+
notice and project-agent security notice.
|
|
107
|
+
- Preserve error notifications and the inline TUI behavior.
|
|
108
|
+
|
|
109
|
+
## Phase 3 — Migrate runtime and extension call sites
|
|
110
|
+
|
|
111
|
+
Search all settings consumers and remove assumptions that `loadSettings()`
|
|
112
|
+
returns `settingsScope`:
|
|
113
|
+
|
|
114
|
+
- `index.ts` widget and command completion rendering;
|
|
115
|
+
- `src/core/lifecycle.ts` timeout and stale-wait resolution;
|
|
116
|
+
- `src/extension/shepherd.ts` timeout, agent scope, bundled-agent, and
|
|
117
|
+
confirmation resolution;
|
|
118
|
+
- `src/extension/settings-ui.ts`;
|
|
119
|
+
- session-start fieldnote initialization.
|
|
120
|
+
|
|
121
|
+
Fix the existing cwd-sensitive lifecycle lookups explicitly:
|
|
122
|
+
|
|
123
|
+
- Store the owning workspace cwd on the agent/task record when the agent is
|
|
124
|
+
spawned.
|
|
125
|
+
- Use that cwd for `sendParentMessage()` reply deadlines instead of
|
|
126
|
+
`process.cwd()`.
|
|
127
|
+
- Use the waiting task's owning cwd in the stale-wait monitor instead of
|
|
128
|
+
`process.cwd()`.
|
|
129
|
+
- Add tests where a child/task cwd differs from the parent process cwd.
|
|
130
|
+
|
|
131
|
+
The runtime should continue passing the relevant cwd. No lifecycle tool schema
|
|
132
|
+
or model-facing argument changes should be introduced.
|
|
133
|
+
|
|
134
|
+
## Phase 4 — Update tests and fixtures
|
|
135
|
+
|
|
136
|
+
Rewrite `test/verify-settings.mjs` around the new contract:
|
|
137
|
+
|
|
138
|
+
- no files → built-in defaults and `projectScope: false`;
|
|
139
|
+
- user saves write values only;
|
|
140
|
+
- user-file `settingsScope` and stray `projectScope` are ignored and stripped
|
|
141
|
+
on the next user save;
|
|
142
|
+
- no project file → user values apply;
|
|
143
|
+
- `projectScope: false` → project values dormant, user values apply;
|
|
144
|
+
- keyless project file → dormant;
|
|
145
|
+
- non-boolean project flag → dormant;
|
|
146
|
+
- malformed project file → user layer applies;
|
|
147
|
+
- `projectScope: true` → project values apply and missing fields use built-in
|
|
148
|
+
defaults rather than user values;
|
|
149
|
+
- project activation is independent across two cwd values;
|
|
150
|
+
- legacy project `settingsScope: "project"` activates;
|
|
151
|
+
- user and project saves write the expected complete shapes;
|
|
152
|
+
- activation creates a file when needed;
|
|
153
|
+
- deactivation writes `projectScope: false`, preserves values, drops the legacy
|
|
154
|
+
key, and does not delete the file;
|
|
155
|
+
- dormant project values survive reactivation through
|
|
156
|
+
`loadProjectFileValues()`;
|
|
157
|
+
- legacy user-file migration and timeout migration still work.
|
|
158
|
+
|
|
159
|
+
Update dependent fixtures:
|
|
160
|
+
|
|
161
|
+
- `test/verify-status-widget.mjs` must put `projectScope: true` in its project
|
|
162
|
+
fixture rather than relying on a user `settingsScope` pointer.
|
|
163
|
+
- `test/verify-command-ux.mjs` and any other configuration fixtures must use
|
|
164
|
+
values-only user files and explicit project activation where required.
|
|
165
|
+
- Add coverage for effective settings used by fieldnotes, timeouts, stale-wait
|
|
166
|
+
reminders, agent discovery, confirmation, and the status widget.
|
|
167
|
+
- Assert that project config cannot disable `confirmProjectAgents`, while an
|
|
168
|
+
explicit user-layer opt-out remains effective.
|
|
169
|
+
- Add focused lifecycle tests proving reply deadlines and stale-wait thresholds
|
|
170
|
+
resolve from the task/agent workspace cwd, not the parent process cwd.
|
|
171
|
+
- Cover all validators, including timeout unit migration, stale-wait values at
|
|
172
|
+
and below zero, non-object project files, and invalid parked values.
|
|
173
|
+
|
|
174
|
+
## Phase 5 — Repository and documentation updates
|
|
175
|
+
|
|
176
|
+
Update repository guidance and user documentation:
|
|
177
|
+
|
|
178
|
+
- Replace the old scope/delta explanation in `README.md`.
|
|
179
|
+
- Update `AGENTS.md` to describe user values-only plus self-contained project
|
|
180
|
+
settings and the project-owned activation flag.
|
|
181
|
+
- Mark `docs/plans/settings-scope.md` as superseded or replace its design
|
|
182
|
+
details with a link to this specification.
|
|
183
|
+
- Update `docs/README.md` if the plan/spec index requires a new entry.
|
|
184
|
+
- Update `.gitignore` from a blanket `.shepherd/` ignore to a pattern that
|
|
185
|
+
keeps runtime sessions ignored while allowing an explicit
|
|
186
|
+
`.shepherd/config.json` exception.
|
|
187
|
+
- Verify the exception with `git check-ignore` and a temporary fresh checkout.
|
|
188
|
+
- Document the migration behavior for existing user scope pointers and
|
|
189
|
+
keyless project deltas.
|
|
190
|
+
- Document that committing `.shepherd/config.json` is deliberate because it
|
|
191
|
+
can affect project-agent discovery and lifecycle defaults, but cannot disable
|
|
192
|
+
the user-owned project-agent confirmation gate.
|
|
193
|
+
- Add an explicit security/trust-boundary section for repository-controlled
|
|
194
|
+
agent definitions.
|
|
195
|
+
|
|
196
|
+
## Phase 6 — Verification and live rollout
|
|
197
|
+
|
|
198
|
+
Run static and automated checks:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
git diff --check
|
|
202
|
+
npm run settings:test
|
|
203
|
+
npm test
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Perform live checks in a temporary project and a second independent cwd:
|
|
207
|
+
|
|
208
|
+
1. Open `/shepherd settings` with no project file; confirm `user` display.
|
|
209
|
+
2. Select project; confirm `.shepherd/config.json` is created with all
|
|
210
|
+
project-overridable values (but not `confirmProjectAgents`) and
|
|
211
|
+
`projectScope: true`.
|
|
212
|
+
3. Change a project value; confirm the project file remains self-contained.
|
|
213
|
+
4. Open settings from another cwd; confirm it still uses user settings.
|
|
214
|
+
5. Deactivate project scope; confirm `projectScope: false`, preserved values,
|
|
215
|
+
and immediate user-layer behavior.
|
|
216
|
+
6. Re-enable project scope; confirm parked project values return.
|
|
217
|
+
7. Hand-edit a project file, confirm mtime-based reload, and document or
|
|
218
|
+
address the existing same-mtime cache limitation.
|
|
219
|
+
8. Confirm fieldnotes still require a new Shepherd session after changing the
|
|
220
|
+
setting.
|
|
221
|
+
9. Confirm timeout, stale-wait, agent discovery, and widget behavior resolve
|
|
222
|
+
from the active workspace layer; confirm the project file cannot disable
|
|
223
|
+
the user-owned project-agent confirmation gate.
|
|
224
|
+
10. Run a child/task with a cwd different from the parent process cwd and
|
|
225
|
+
confirm its timeout and stale-wait settings come from the child/task cwd.
|
|
226
|
+
11. Confirm a committed-style project config does not cause other workspaces
|
|
227
|
+
to change.
|
|
228
|
+
|
|
229
|
+
After implementation and verification, update the status in `spec.md` and
|
|
230
|
+
record any intentional deviations.
|
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
# Per-workspace self-contained Shepherd settings
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Implemented. The per-workspace configuration model, security boundary,
|
|
6
|
+
lifecycle cwd fixes, documentation, and automated tests are complete. Live
|
|
7
|
+
interactive `/shepherd settings` verification remains an operational follow-up.
|
|
8
|
+
|
|
9
|
+
## Confirmed decisions
|
|
10
|
+
|
|
11
|
+
- `confirmProjectAgents` remains user-owned. A committed project config cannot
|
|
12
|
+
disable the project-agent confirmation gate; a user's explicit user-level
|
|
13
|
+
opt-out remains effective.
|
|
14
|
+
- Existing keyless project deltas remain dormant until explicitly activated.
|
|
15
|
+
The old global `settingsScope: "project"` preference is not automatically
|
|
16
|
+
converted across workspaces.
|
|
17
|
+
- `.shepherd/config.json` is intended to be optionally committed and shared,
|
|
18
|
+
while runtime fieldnote sessions remain ignored.
|
|
19
|
+
- The existing workspace-cwd bugs in reply deadlines and stale-wait monitoring
|
|
20
|
+
are included in this implementation.
|
|
21
|
+
- The settings UI will clearly describe `confirmProjectAgents` as user-only.
|
|
22
|
+
|
|
23
|
+
## Summary
|
|
24
|
+
|
|
25
|
+
Replace pi-shepherd's machine-global `settingsScope` plus sparse project-delta
|
|
26
|
+
model with the per-workspace, self-contained project configuration model used
|
|
27
|
+
by pi-zvec-grep.
|
|
28
|
+
|
|
29
|
+
The new model keeps personal defaults in the user configuration and puts a
|
|
30
|
+
boolean activation flag in each project's configuration file. A project can
|
|
31
|
+
therefore opt into its own committed settings without changing the behavior of
|
|
32
|
+
any other workspace or relying on each user's private configuration.
|
|
33
|
+
|
|
34
|
+
The existing Shepherd setting fields and their runtime behavior remain. This
|
|
35
|
+
feature changes configuration ownership, activation, persistence, migration,
|
|
36
|
+
and the settings menu—not the meaning of agent, lifecycle, fieldnotes, or
|
|
37
|
+
watcher settings.
|
|
38
|
+
|
|
39
|
+
## Goals
|
|
40
|
+
|
|
41
|
+
- Make project settings independently activatable per workspace.
|
|
42
|
+
- Make an active project configuration self-contained and reproducible across
|
|
43
|
+
machines.
|
|
44
|
+
- Prevent a project from changing the settings source for unrelated projects.
|
|
45
|
+
- Preserve all existing Shepherd settings and defaults.
|
|
46
|
+
- Preserve the existing user-file rename migration from `settings.json` to
|
|
47
|
+
`config.json`.
|
|
48
|
+
- Preserve legacy project files using `settingsScope: "project"` as a
|
|
49
|
+
read-only compatibility format.
|
|
50
|
+
- Make dormant project settings reversible without deleting their stored
|
|
51
|
+
values.
|
|
52
|
+
- Allow a committed `.shepherd/config.json` to carry team-wide Shepherd
|
|
53
|
+
defaults while keeping runtime fieldnote sessions ignored.
|
|
54
|
+
- Keep model-facing lifecycle APIs and opaque id semantics unchanged.
|
|
55
|
+
- Preserve `confirmProjectAgents` as a user-owned security control so a
|
|
56
|
+
committed project file cannot suppress confirmation for project-local agents.
|
|
57
|
+
|
|
58
|
+
## Non-goals
|
|
59
|
+
|
|
60
|
+
- Do not change the set or meaning of the existing Shepherd settings.
|
|
61
|
+
- Do not add a second configuration root or walk up parent directories.
|
|
62
|
+
- Do not automatically activate every existing keyless project delta. Such a
|
|
63
|
+
conversion could silently enable repository-controlled settings and cannot
|
|
64
|
+
safely translate one global user preference to all workspaces.
|
|
65
|
+
- Do not change explicit tool-call or lifecycle arguments that already override
|
|
66
|
+
configured defaults.
|
|
67
|
+
- Do not delete old configuration files automatically except for the existing
|
|
68
|
+
one-shot `settings.json` → `config.json` rename migration.
|
|
69
|
+
- Do not change fieldnote session snapshot semantics: `fieldnotes` still takes
|
|
70
|
+
effect for a new Shepherd session.
|
|
71
|
+
|
|
72
|
+
## Configuration model
|
|
73
|
+
|
|
74
|
+
### Files
|
|
75
|
+
|
|
76
|
+
| Layer | Path | Contents |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| User | `~/.pi/agent/pi-shepherd/config.json`, resolved through `getAgentDir()` | Value fields only; personal defaults for workspaces without active project scope. |
|
|
79
|
+
| Project | `<cwd>/.shepherd/config.json`, anchored at the current cwd | All project-overridable fields plus boolean `projectScope`; self-contained when active. |
|
|
80
|
+
|
|
81
|
+
Both files continue to use the active pi agent directory and
|
|
82
|
+
`PI_CODING_AGENT_DIR` override. Project lookup remains cwd-anchored with no
|
|
83
|
+
walk-up. The per-file mtime cache remains in place.
|
|
84
|
+
|
|
85
|
+
### Value fields
|
|
86
|
+
|
|
87
|
+
The effective settings retain the current `ShepherdSettings` value fields.
|
|
88
|
+
All are project-overridable except `confirmProjectAgents`, which remains a
|
|
89
|
+
user-owned security control and is never written to or read from the project
|
|
90
|
+
file:
|
|
91
|
+
|
|
92
|
+
- `agentScope` — default `user`
|
|
93
|
+
- `includeBundledAgents` — default `true`
|
|
94
|
+
- `confirmProjectAgents` — default `true`; user-owned and not project-overridable
|
|
95
|
+
- `keepOpen` — default `true`
|
|
96
|
+
- `stayOpen` — default `false`
|
|
97
|
+
- `fieldnotes` — default `true`
|
|
98
|
+
- `emojiSheep` — default `true`
|
|
99
|
+
- `timeout` — default `20` minutes
|
|
100
|
+
- `staleWaitThreshold` — default `5` minutes; zero or a negative value disables
|
|
101
|
+
stale-wait reminders
|
|
102
|
+
|
|
103
|
+
The effective settings object returned by `loadSettings(cwd)` gains:
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
projectScope: boolean
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`projectScope` is derived from the current workspace's project file. It is not
|
|
110
|
+
stored in the user file and is false when no project scope is active.
|
|
111
|
+
|
|
112
|
+
### User file
|
|
113
|
+
|
|
114
|
+
The user file stores the value fields only:
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"agentScope": "both",
|
|
119
|
+
"includeBundledAgents": true,
|
|
120
|
+
"confirmProjectAgents": true,
|
|
121
|
+
"keepOpen": true,
|
|
122
|
+
"stayOpen": false,
|
|
123
|
+
"fieldnotes": true,
|
|
124
|
+
"emojiSheep": true,
|
|
125
|
+
"timeout": 20,
|
|
126
|
+
"staleWaitThreshold": 5
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
A stray `projectScope` or legacy `settingsScope` key in the user file is
|
|
131
|
+
ignored for resolution. The next user-layer save strips both keys.
|
|
132
|
+
|
|
133
|
+
### Project file
|
|
134
|
+
|
|
135
|
+
A project file managed by Shepherd stores every project-overridable value
|
|
136
|
+
and the activation flag. It does not store `confirmProjectAgents`, because
|
|
137
|
+
that setting is user-owned:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"agentScope": "project",
|
|
142
|
+
"includeBundledAgents": true,
|
|
143
|
+
"keepOpen": false,
|
|
144
|
+
"stayOpen": false,
|
|
145
|
+
"fieldnotes": true,
|
|
146
|
+
"emojiSheep": true,
|
|
147
|
+
"timeout": 30,
|
|
148
|
+
"staleWaitThreshold": 5,
|
|
149
|
+
"projectScope": true
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
When `projectScope` is `true`, the project file is authoritative for that
|
|
154
|
+
workspace's project-overridable settings. User values are not mixed into those
|
|
155
|
+
settings. Missing or invalid project-overridable fields in an active project
|
|
156
|
+
file fall back to the built-in defaults, not to the user layer.
|
|
157
|
+
|
|
158
|
+
`confirmProjectAgents` is the deliberate security exception: it always comes
|
|
159
|
+
from the trusted user layer. A committed project file may select project agents
|
|
160
|
+
through `agentScope`, but it cannot disable the interactive confirmation gate.
|
|
161
|
+
A user may still explicitly disable that gate in their own user configuration.
|
|
162
|
+
This is the only user value mixed into an active project result.
|
|
163
|
+
|
|
164
|
+
When `projectScope` is `false`, the project values remain stored but dormant;
|
|
165
|
+
the user layer applies. A missing, keyless, invalid, or malformed project file
|
|
166
|
+
also leaves project scope inactive and falls back to the user layer.
|
|
167
|
+
|
|
168
|
+
A legacy project file containing `settingsScope: "project"` and no boolean
|
|
169
|
+
flag is treated as active for compatibility. The legacy string is never
|
|
170
|
+
written by Shepherd. If both keys are present, a real boolean `projectScope`
|
|
171
|
+
takes precedence.
|
|
172
|
+
|
|
173
|
+
## Resolution behavior
|
|
174
|
+
|
|
175
|
+
`loadSettings(cwd?)` must resolve as follows:
|
|
176
|
+
|
|
177
|
+
1. Load built-in defaults and overlay validated values from the user file.
|
|
178
|
+
2. Force the effective `projectScope` to `false` for the user-only result.
|
|
179
|
+
3. If no cwd is supplied, return that user-layer result.
|
|
180
|
+
4. Read `<cwd>/.shepherd/config.json`.
|
|
181
|
+
5. If the project file is active (`projectScope: true`, or the supported legacy
|
|
182
|
+
string), create the effective result from built-in defaults and overlay only
|
|
183
|
+
the validated project values; set `projectScope: true`.
|
|
184
|
+
6. For an active project, retain the trusted user-layer
|
|
185
|
+
`confirmProjectAgents` value while keeping all other settings project-owned.
|
|
186
|
+
7. Otherwise, return the user-layer result with `projectScope: false`.
|
|
187
|
+
|
|
188
|
+
This means a project file with `{ "timeout": 30, "projectScope": true }`
|
|
189
|
+
uses the built-in defaults for every other project-overridable setting, while a
|
|
190
|
+
dormant project file with the same value leaves the user's timeout in effect.
|
|
191
|
+
The effective `confirmProjectAgents` value always comes from the user layer.
|
|
192
|
+
|
|
193
|
+
## Persistence behavior
|
|
194
|
+
|
|
195
|
+
Replace the current `ConfigScope`/`settingsScope` persistence contract with a
|
|
196
|
+
plain target scope (`"user" | "project"`) while keeping the scope argument
|
|
197
|
+
internal to the settings UI and config module.
|
|
198
|
+
|
|
199
|
+
### User save
|
|
200
|
+
|
|
201
|
+
`saveSettings(next, "user")` writes only the value fields. It strips
|
|
202
|
+
`settingsScope` and `projectScope` from legacy user files and updates the mtime
|
|
203
|
+
cache.
|
|
204
|
+
|
|
205
|
+
### Project save
|
|
206
|
+
|
|
207
|
+
`saveSettings(next, "project", cwd)` writes all project-overridable fields and
|
|
208
|
+
`projectScope: next.projectScope`; it never writes `confirmProjectAgents`. It
|
|
209
|
+
creates `.shepherd/` and reports whether the file was newly created.
|
|
210
|
+
|
|
211
|
+
Project saves are never deltas. This guarantees that an active committed
|
|
212
|
+
project config has the same meaning on every machine.
|
|
213
|
+
|
|
214
|
+
### Deactivation
|
|
215
|
+
|
|
216
|
+
Add `deactivateProjectScope(cwd)` with the following behavior:
|
|
217
|
+
|
|
218
|
+
- If the project file is missing or malformed, report no change.
|
|
219
|
+
- If it is a valid object with `projectScope: false`, report no change.
|
|
220
|
+
- A valid keyless, legacy-string, or `projectScope: true` object is considered
|
|
221
|
+
a normalization/deactivation change and receives `projectScope: false`.
|
|
222
|
+
- Otherwise set `projectScope` to `false`.
|
|
223
|
+
- Preserve all stored project values.
|
|
224
|
+
- Remove a legacy `settingsScope` key when touching the file.
|
|
225
|
+
- Never delete the project file or its stored values.
|
|
226
|
+
- Make the user layer effective immediately.
|
|
227
|
+
|
|
228
|
+
Add `loadProjectFileValues(cwd)` so activating a dormant project preserves its
|
|
229
|
+
parked values instead of replacing them with the current user's values. Missing
|
|
230
|
+
parked fields use built-in defaults.
|
|
231
|
+
|
|
232
|
+
## Settings menu behavior
|
|
233
|
+
|
|
234
|
+
The existing `/shepherd` and `/shepherd settings` commands remain. The menu
|
|
235
|
+
continues to use the inline `SettingsList`/`DynamicBorder` presentation and
|
|
236
|
+
fuzzy search.
|
|
237
|
+
|
|
238
|
+
Change the first item from `settingsScope` to `projectScope`:
|
|
239
|
+
|
|
240
|
+
- `project` when this workspace's project file is active.
|
|
241
|
+
- `user (project file dormant)` when a project file exists but is inactive.
|
|
242
|
+
- `user` when no project file exists.
|
|
243
|
+
|
|
244
|
+
The scope item must keep its current display value inside its cycle values so
|
|
245
|
+
that the third dormant state cycles correctly.
|
|
246
|
+
|
|
247
|
+
Selecting `project`:
|
|
248
|
+
|
|
249
|
+
1. Read parked project values with `loadProjectFileValues(cwd)`.
|
|
250
|
+
2. Preserve the trusted user-layer `confirmProjectAgents` value.
|
|
251
|
+
3. Save the complete project settings with `projectScope: true`.
|
|
252
|
+
4. Create `.shepherd/config.json` if it does not exist and notify the user.
|
|
253
|
+
5. Resync the menu from `loadSettings(cwd)`.
|
|
254
|
+
|
|
255
|
+
Selecting `user` calls `deactivateProjectScope(cwd)`, preserving the project
|
|
256
|
+
file and values while making the user layer effective.
|
|
257
|
+
|
|
258
|
+
Changing any other setting saves to the user file when project scope is
|
|
259
|
+
inactive and to the complete project file when project scope is active.
|
|
260
|
+
`confirmProjectAgents` is always saved to the user file, even while the menu is
|
|
261
|
+
showing active project settings. The existing notifications for `fieldnotes`
|
|
262
|
+
(next session) and `agentScope` (repo-controlled agents) remain.
|
|
263
|
+
|
|
264
|
+
## Migration and compatibility
|
|
265
|
+
|
|
266
|
+
### User file rename
|
|
267
|
+
|
|
268
|
+
Keep the current one-shot migration:
|
|
269
|
+
|
|
270
|
+
```text
|
|
271
|
+
~/.pi/agent/pi-shepherd/settings.json
|
|
272
|
+
→ ~/.pi/agent/pi-shepherd/config.json
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
When both files exist, `config.json` wins and the legacy file remains in place.
|
|
276
|
+
The existing timeout millisecond-to-minute migration remains.
|
|
277
|
+
|
|
278
|
+
### Existing user scope key
|
|
279
|
+
|
|
280
|
+
After migration, a user-file `settingsScope` value is no longer authoritative.
|
|
281
|
+
It is ignored immediately and removed on the next user-layer save. There is no
|
|
282
|
+
safe automatic way to turn one machine-global `"project"` preference into
|
|
283
|
+
per-workspace activation for every directory, so existing workspaces must be
|
|
284
|
+
explicitly activated through `/shepherd settings` or by adding
|
|
285
|
+
`projectScope: true` to their project file.
|
|
286
|
+
|
|
287
|
+
This is a deliberate safety behavior: visiting a repository must not silently
|
|
288
|
+
activate repository-controlled settings merely because a private global flag
|
|
289
|
+
used to be set.
|
|
290
|
+
|
|
291
|
+
### Existing project deltas
|
|
292
|
+
|
|
293
|
+
Existing `.shepherd/config.json` files without `projectScope` are treated as
|
|
294
|
+
dormant. Their values are not deleted. Selecting `project` in the menu converts
|
|
295
|
+
the file to a complete self-contained configuration, preserving any stored
|
|
296
|
+
fields and filling missing fields from built-in defaults.
|
|
297
|
+
|
|
298
|
+
An existing project file with `settingsScope: "project"` remains active through
|
|
299
|
+
legacy compatibility and is normalized to the boolean form when saved or
|
|
300
|
+
deactivated. Any legacy `confirmProjectAgents` value found in a project file is
|
|
301
|
+
ignored; confirmation remains user-owned.
|
|
302
|
+
|
|
303
|
+
### Security boundary
|
|
304
|
+
|
|
305
|
+
Project files are repository-controlled input. They may select project agent
|
|
306
|
+
sources through `agentScope`, but they cannot turn off `confirmProjectAgents`.
|
|
307
|
+
The confirmation setting is loaded from the user file even when project scope is
|
|
308
|
+
active. A user who deliberately disables confirmation accepts responsibility for
|
|
309
|
+
that choice across workspaces, and the setting should be clearly labeled as a
|
|
310
|
+
trust decision in the menu and documentation.
|
|
311
|
+
|
|
312
|
+
### Repository tracking
|
|
313
|
+
|
|
314
|
+
Because `.shepherd/` currently ignores both settings and runtime fieldnotes,
|
|
315
|
+
update `.gitignore` so a project config can be committed without tracking
|
|
316
|
+
session artifacts:
|
|
317
|
+
|
|
318
|
+
```gitignore
|
|
319
|
+
.shepherd/*
|
|
320
|
+
!.shepherd/config.json
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Document that committing `.shepherd/config.json` is an explicit choice
|
|
324
|
+
because it can contain project-controlled settings such as agent discovery and
|
|
325
|
+
agent lifecycle defaults. It must not be able to disable the user-owned
|
|
326
|
+
project-agent confirmation gate.
|
|
327
|
+
|
|
328
|
+
## Runtime integration
|
|
329
|
+
|
|
330
|
+
All existing consumers must continue to use the effective result from
|
|
331
|
+
`loadSettings(cwd)`:
|
|
332
|
+
|
|
333
|
+
- lifecycle prompt/delegation timeout resolution;
|
|
334
|
+
- stale-wait threshold resolution;
|
|
335
|
+
- agent discovery scope and bundled-agent inclusion;
|
|
336
|
+
- project-agent confirmation, using the trusted user-layer setting rather
|
|
337
|
+
than a project-controlled value;
|
|
338
|
+
- tab/process retention;
|
|
339
|
+
- fieldnote session initialization;
|
|
340
|
+
- status widget sheep rendering;
|
|
341
|
+
- settings command completion and rendering.
|
|
342
|
+
|
|
343
|
+
No public lifecycle tool schema changes are required. Explicit tool arguments
|
|
344
|
+
continue to take precedence over configuration defaults.
|
|
345
|
+
|
|
346
|
+
## Verification requirements
|
|
347
|
+
|
|
348
|
+
The implementation is complete only when:
|
|
349
|
+
|
|
350
|
+
- the new config-layer contract is covered by filesystem tests;
|
|
351
|
+
- all existing settings consumers use per-workspace resolution;
|
|
352
|
+
- `sendParentMessage()` and the stale-wait monitor use the owning agent/task
|
|
353
|
+
workspace cwd rather than the Shepherd process cwd;
|
|
354
|
+
- status-widget and command-UX fixtures use the new project activation flag;
|
|
355
|
+
- legacy user-file rename and timeout migration still pass;
|
|
356
|
+
- legacy project `settingsScope: "project"` compatibility passes;
|
|
357
|
+
- malformed, keyless, false, and invalid project files remain dormant;
|
|
358
|
+
- active project files do not inherit user values for missing fields;
|
|
359
|
+
- activation preserves dormant project values;
|
|
360
|
+
- deactivation writes `false` without deleting values;
|
|
361
|
+
- project files can be committed independently of fieldnote sessions;
|
|
362
|
+
- `npm test` passes; and
|
|
363
|
+
- live `/shepherd settings` verification confirms activation, deactivation,
|
|
364
|
+
creation notification, and effective runtime behavior;
|
|
365
|
+
- a committed project file cannot suppress `confirmProjectAgents` and an
|
|
366
|
+
explicit user opt-out remains user-owned;
|
|
367
|
+
- timeout and stale-wait behavior is tested with agents/tasks whose cwd differs
|
|
368
|
+
from the parent process cwd.
|