Skip to content
7 changes: 7 additions & 0 deletions packages/workforce/src/loader/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,13 @@
* that never denote anything, and `validateSegment` is the one rule for what a
* name in this tree may be. What a reader does inside a team is its own.
*
* **One rule binds every reader here, and the next one added beside them.**
* Anything the published convention tells an author they may write is either
* consumed or refused loudly, naming it — never passed over in silence, because
* an author who followed the docs and got no seat and no error has no way left
* to find out. `test/published-tree-surface.test.ts` enforces it and carries the
* reasoning, the exclusions, and whatever is still silent.
*
* Kept behind a subpath so importing the package root does not pull a consumer
* onto `node:fs`.
*/
Expand Down
17 changes: 15 additions & 2 deletions packages/workforce/src/seat-capabilities.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@
* entry, `(ctx) => refs`, which the framework resolves per execution off
* `ctx.flow.config`.
*
* That path carries **context and tools only**. Resources, state schemas and
* That path carries **context and tools** — catalog tools and controls alike;
* {@link DYNAMIC_KEYS} is the list. Resources, state schemas and
* the generator singletons have to exist before a block runs, so the framework
* resolves them at build time from static entries alone. Two consequences run
* through this whole file:
Expand Down Expand Up @@ -103,8 +104,20 @@ const BUILD_TIME_ONLY_KEYS = [
* The surface keys the dynamic path DOES carry, as the framework resolves it.
*
* Kept only so the two lists can be checked against `PresetDef` together.
*
* `controlTools` (FIX-1393) is dynamic because core makes it so —
* `resolveDynamicCapSurface` collects it alongside `tools` — not as a
* preference. Build-time-only would refuse a seat naming a control-bearing
* preset, which inverts what a control is for.
*
* Being dynamic is not being unfenced: a selected preset's catalog `tools`
* still stop at the seat's own `tools:`. See `PresetDef.controlTools` for the
* distinction, and the paired tests in `test/seat-capabilities.test.ts` for
* the behaviour — *"carries a selected preset's context but not its tool past

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linking behaviour to exact it("…") strings in this file will rot when someone renames tests. The fence vs control distinction is worth documenting; I'd describe the invariant in prose and point at seat-capabilities.test.ts without quoting titles.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not mine to act on — flagging rather than silently ignoring.

seat-capabilities.ts came from #1880 (fix/classify-control-tools-seat-selection), which I merged into this branch only because main was red on its TS2344 and this branch wouldn't typecheck without it. #1880 has since merged to main, so that file is no longer in this PR's diff — which is now 2 files, loader/index.ts and the test.

The point itself looks sound (quoting it("…") titles rots on rename; describe the invariant and point at the file). It just belongs to whoever owns that code, not to a defect-class detector — editing it here would put an unrelated change back into a diff that just shrank to the thing under review.


Generated by Claude Code

* the seat's fence"* and *"lets a selected preset's CONTROL tool through the
* same empty tools list"*, one key apart on the same seat.
*/
const DYNAMIC_KEYS = ["context", "tools"] as const satisfies readonly (keyof PresetDef)[];
const DYNAMIC_KEYS = ["context", "tools", "controlTools"] as const satisfies readonly (keyof PresetDef)[];

/**
* Compile-time proof that every `PresetDef` key is classified as one or the
Expand Down
Loading
Loading