@luminascale/shepherd 0.0.0-stage → 0.6.0

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.
Files changed (203) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. 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.