@granular-software/fractory 0.1.24 → 0.1.25
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/dist/annotations.d.ts +4 -0
- package/dist/compiler.js +161 -4
- package/dist/core.d.ts +1 -0
- package/dist/core.js +1 -0
- package/dist/declared-graph.js +2 -1
- package/dist/factory-graph.d.ts +4 -1
- package/dist/factory-graph.js +77 -6
- package/dist/factory-model.d.ts +14 -0
- package/dist/git-code.js +1 -1
- package/dist/interface-map.d.ts +15 -0
- package/dist/interface-map.js +125 -0
- package/dist/map-quality.d.ts +6 -0
- package/dist/map-quality.js +5 -0
- package/dist/model.d.ts +6 -2
- package/dist/product-map.d.ts +2 -0
- package/dist/product-map.js +33 -4
- package/dist/public-boundaries.d.ts +13 -0
- package/dist/public-boundaries.js +115 -0
- package/dist/repository-map.js +3 -1
- package/dist/scope.d.ts +2 -0
- package/dist/scope.js +77 -3
- package/dist/source-index.js +4 -0
- package/dist/source-review-git.js +3 -1
- package/dist/source-review.d.ts +3 -1
- package/dist/source-review.js +94 -14
- package/dist/work-check.d.ts +1 -0
- package/dist/work-check.js +6 -1
- package/dist/work-cli.js +29 -1
- package/dist/work-context.d.ts +2 -0
- package/dist/work-context.js +30 -4
- package/dist/work-lock-check.d.ts +12 -0
- package/dist/work-lock-check.js +339 -0
- package/dist/work-locks.d.ts +10 -0
- package/dist/work-locks.js +98 -0
- package/dist/work-model.d.ts +9 -0
- package/dist/work-model.js +50 -1
- package/package.json +1 -1
- package/src/annotations.ts +4 -0
- package/src/compiler.ts +190 -4
- package/src/core.ts +4 -0
- package/src/declared-graph.ts +2 -1
- package/src/factory-graph.ts +89 -5
- package/src/factory-model.ts +9 -0
- package/src/git-code.ts +1 -1
- package/src/interface-map.ts +166 -0
- package/src/map-quality.ts +5 -0
- package/src/model.ts +10 -3
- package/src/product-map.ts +51 -16
- package/src/public-boundaries.ts +143 -0
- package/src/repository-map.ts +3 -1
- package/src/scope.ts +92 -3
- package/src/source-index.ts +3 -0
- package/src/source-review-git.ts +3 -1
- package/src/source-review.ts +112 -13
- package/src/work-check.ts +7 -1
- package/src/work-cli.ts +35 -1
- package/src/work-context.ts +43 -3
- package/src/work-lock-check.ts +549 -0
- package/src/work-locks.ts +108 -0
- package/src/work-model.ts +67 -1
- package/toolkit/GUIDE.md +72 -23
- package/toolkit/SKILL.md +16 -5
- package/toolkit/build.json +1 -1
package/src/work-model.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { DefinitionGraph, Element } from "./model";
|
|
2
|
+
import { publicConnectionError, boundaryViolations } from "./public-boundaries";
|
|
2
3
|
|
|
3
4
|
export interface WorkProposal {
|
|
4
5
|
id: string;
|
|
@@ -27,6 +28,12 @@ export interface WorkIntentState {
|
|
|
27
28
|
implementation?: string;
|
|
28
29
|
reason?: string;
|
|
29
30
|
}
|
|
31
|
+
/** Constraints are independent of editable scope and temporary canvas selection. */
|
|
32
|
+
export interface WorkLock {
|
|
33
|
+
target: string;
|
|
34
|
+
kind: "subtree" | "contract";
|
|
35
|
+
note?: string;
|
|
36
|
+
}
|
|
30
37
|
export interface WorkPlan {
|
|
31
38
|
schema: "fractory.work.v1";
|
|
32
39
|
id: string;
|
|
@@ -38,6 +45,7 @@ export interface WorkPlan {
|
|
|
38
45
|
scope: string[];
|
|
39
46
|
/** Explicit subtree exceptions. The nearest include/exclude rule wins. */
|
|
40
47
|
excluded?: string[];
|
|
48
|
+
locks?: WorkLock[];
|
|
41
49
|
proposals: WorkProposal[];
|
|
42
50
|
bootstrapRevision?: string;
|
|
43
51
|
pullRequest?: { url: string; title: string };
|
|
@@ -322,6 +330,40 @@ export function validateProposals(
|
|
|
322
330
|
cursor = parents.get(cursor);
|
|
323
331
|
}
|
|
324
332
|
}
|
|
333
|
+
const candidate: DefinitionGraph = {
|
|
334
|
+
...graph,
|
|
335
|
+
elements: [
|
|
336
|
+
...graph.elements,
|
|
337
|
+
...result
|
|
338
|
+
.filter((item) => item.kind === "block")
|
|
339
|
+
.map(
|
|
340
|
+
(item): Element => ({
|
|
341
|
+
id: item.id,
|
|
342
|
+
parent: item.parent,
|
|
343
|
+
kind: item.blockKind || "block",
|
|
344
|
+
label: item.label,
|
|
345
|
+
provenance: "proposed",
|
|
346
|
+
}),
|
|
347
|
+
),
|
|
348
|
+
],
|
|
349
|
+
};
|
|
350
|
+
for (const item of result.filter((item) => item.kind === "connection")) {
|
|
351
|
+
// An unchanged historical request remains editable as a record. New links
|
|
352
|
+
// and endpoint edits must obey the same public contract as compiled maps.
|
|
353
|
+
const old = previous.find(
|
|
354
|
+
(entry) => entry.id === item.id && entry.kind === "connection",
|
|
355
|
+
);
|
|
356
|
+
if (old?.source === item.source && old?.target === item.target) continue;
|
|
357
|
+
const error = publicConnectionError(candidate, {
|
|
358
|
+
id: item.id,
|
|
359
|
+
source: item.source!,
|
|
360
|
+
target: item.target!,
|
|
361
|
+
relation: "calls",
|
|
362
|
+
label: item.label,
|
|
363
|
+
provenance: "proposed",
|
|
364
|
+
});
|
|
365
|
+
if (error) throw Error(error);
|
|
366
|
+
}
|
|
325
367
|
return result;
|
|
326
368
|
}
|
|
327
369
|
|
|
@@ -358,7 +400,7 @@ export function workDisplayGraph(
|
|
|
358
400
|
(p) => p.kind !== "annotation" && needed.has(p.id),
|
|
359
401
|
);
|
|
360
402
|
if (!visual.length) return graph;
|
|
361
|
-
|
|
403
|
+
const scene: DefinitionGraph = {
|
|
362
404
|
...graph,
|
|
363
405
|
revision: `${graph.revision}:plan:${JSON.stringify(visual)}`,
|
|
364
406
|
elements: [
|
|
@@ -397,4 +439,28 @@ export function workDisplayGraph(
|
|
|
397
439
|
),
|
|
398
440
|
],
|
|
399
441
|
};
|
|
442
|
+
const invalid = new Set(
|
|
443
|
+
boundaryViolations(scene).map((issue) => issue.connection),
|
|
444
|
+
);
|
|
445
|
+
scene.connections = scene.connections.filter(
|
|
446
|
+
(edge) => edge.provenance !== "proposed" || !invalid.has(edge.id),
|
|
447
|
+
);
|
|
448
|
+
return scene;
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/** Legacy requests remain readable as intentions, not as invalid callable wires. */
|
|
452
|
+
export function proposalConnectionError(
|
|
453
|
+
graph: DefinitionGraph,
|
|
454
|
+
plan: WorkPlan | undefined,
|
|
455
|
+
proposal: WorkProposal,
|
|
456
|
+
) {
|
|
457
|
+
if (proposal.kind !== "connection") return undefined;
|
|
458
|
+
return publicConnectionError(workDisplayGraph(graph, plan), {
|
|
459
|
+
id: proposal.id,
|
|
460
|
+
source: proposal.source!,
|
|
461
|
+
target: proposal.target!,
|
|
462
|
+
label: proposal.label,
|
|
463
|
+
relation: "calls",
|
|
464
|
+
provenance: "proposed",
|
|
465
|
+
});
|
|
400
466
|
}
|
package/toolkit/GUIDE.md
CHANGED
|
@@ -41,47 +41,89 @@ Use only the existing annotations: **Block** for a black box, **Interface** for
|
|
|
41
41
|
Annotate existing classes and methods. TypeScript does not support decorators on standalone function declarations; use the equivalent function wrapper there. Do not introduce classes solely to make the map, list children manually, duplicate interface method lists, or maintain an independent graph.
|
|
42
42
|
|
|
43
43
|
```ts
|
|
44
|
-
import {
|
|
45
|
-
|
|
44
|
+
import {
|
|
45
|
+
Block,
|
|
46
|
+
Interface,
|
|
47
|
+
Method,
|
|
48
|
+
Process,
|
|
49
|
+
type InterfaceRef,
|
|
50
|
+
} from "@granular-software/fractory/annotations";
|
|
46
51
|
|
|
47
52
|
// Existing application class: its name and implementation remain yours.
|
|
48
|
-
@Block(
|
|
53
|
+
@Block("catalog", {
|
|
54
|
+
label: "Catalog",
|
|
55
|
+
description: "Store and retrieve products.",
|
|
56
|
+
})
|
|
49
57
|
export class Catalog {
|
|
50
|
-
@Interface({
|
|
58
|
+
@Interface({
|
|
59
|
+
label: "Read products",
|
|
60
|
+
docs: "./catalog.md",
|
|
61
|
+
tests: ["./catalog.test.ts"],
|
|
62
|
+
})
|
|
51
63
|
static readonly read: InterfaceRef;
|
|
52
64
|
|
|
53
|
-
@Interface({ label:
|
|
65
|
+
@Interface({ label: "Update products" })
|
|
54
66
|
static readonly write: InterfaceRef;
|
|
55
67
|
|
|
56
68
|
@Method(() => Catalog.read)
|
|
57
|
-
async get(id: string) {
|
|
69
|
+
async get(id: string) {
|
|
70
|
+
/* existing implementation */ return { id };
|
|
71
|
+
}
|
|
58
72
|
|
|
59
73
|
@Method(() => Catalog.write)
|
|
60
|
-
async save(id: string) {
|
|
74
|
+
async save(id: string) {
|
|
75
|
+
/* existing implementation */ return { id };
|
|
76
|
+
}
|
|
61
77
|
}
|
|
62
78
|
```
|
|
63
79
|
|
|
64
80
|
In a different file, keep an existing standalone operation and give it a typed parent:
|
|
65
81
|
|
|
66
82
|
```ts
|
|
67
|
-
import { Method, Process } from
|
|
68
|
-
import { Catalog } from
|
|
83
|
+
import { Method, Process } from "@granular-software/fractory/annotations";
|
|
84
|
+
import { Catalog } from "./catalog";
|
|
69
85
|
|
|
70
|
-
export const importProducts = Process(
|
|
86
|
+
export const importProducts = Process("catalog/import", {
|
|
71
87
|
parent: () => Catalog,
|
|
72
|
-
label:
|
|
73
|
-
description:
|
|
88
|
+
label: "Import products",
|
|
89
|
+
description: "Validate and save an incoming product batch.",
|
|
74
90
|
})(async function importProducts(catalog: Catalog, ids: string[]) {
|
|
75
91
|
for (const id of ids) await catalog.save(id);
|
|
76
92
|
});
|
|
77
93
|
|
|
78
94
|
export const findProduct = Method(() => Catalog.read)(
|
|
79
|
-
async function findProduct(catalog: Catalog, id: string) {
|
|
95
|
+
async function findProduct(catalog: Catalog, id: string) {
|
|
96
|
+
return catalog.get(id);
|
|
97
|
+
},
|
|
80
98
|
);
|
|
81
99
|
```
|
|
82
100
|
|
|
83
101
|
Use stable IDs that survive file moves. Parent references and interface references may cross files. The compiler reconstructs membership, contracts and statically resolvable calls without importing application modules. Dynamic dispatch, HTTP, queues and WebSockets may not resolve automatically. Leave unverified relationships as gaps; a typed contract alone is not proof that two services communicate. Document evidence and limits rather than inventing arrows.
|
|
84
102
|
|
|
103
|
+
Every incoming connection from outside a black box must target a public interface. Direct links to a block or an internal method are rejected by compilation, map checks and worktree planning. The exact implementation member remains attached to the interface link as source evidence. Public constructors and callable blocks publish their actual signatures as entry interfaces; this does not change runtime authorization or validation.
|
|
104
|
+
|
|
105
|
+
An interface belongs to its immediate owner. Publish a nested contract through an enclosing box explicitly:
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
@Block("catalog/cache", {
|
|
109
|
+
parent: () => Catalog,
|
|
110
|
+
exposedBy: [() => Catalog],
|
|
111
|
+
label: "Product cache",
|
|
112
|
+
})
|
|
113
|
+
export class ProductCache {
|
|
114
|
+
@Interface({ label: "Read cached products" })
|
|
115
|
+
static readonly read: InterfaceRef;
|
|
116
|
+
@Method(() => ProductCache.read)
|
|
117
|
+
async get(id: string) {
|
|
118
|
+
return { id };
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`exposedBy` on a block publishes its public surfaces through the named enclosing boxes; put it on one interface to publish only that contract. It declares a real API boundary, not a new runtime wrapper. Keep private implementation private. Fix missing-contract diagnostics at the declaration or call site instead of drawing a fake facade. Source inventory adapters may group actual module exports into an interface, preserving their declarations and exact call-site evidence.
|
|
124
|
+
|
|
125
|
+
Interfaces use a rectangular shape with small symmetric beveled corners, a single outline and a plug mark. Normal blocks retain their rounded box shape and the same selection/change colors. On a block view, its exposed interfaces occupy the boundary. Open an interface to see outside callers on the left and the implementation on the right. In worktree sketches, choose **Interface** or set `blockKind: "interface"` on a proposed block; new connections must enter an interface.
|
|
126
|
+
|
|
85
127
|
Runtime argument/result validation is optional and explicit: `@Method(() => Catalog.write, { contract: { args: argumentSchema, result: resultSchema } })`. Both schemas implement synchronous `parse`. Interface `auth` receives `{ receiver, args, context }`; retain existing authorization and use trusted host context if adding a policy. TypeScript contracts describe shapes; runtime validation and application tests enforce behavior. Do not silently add a different auth policy during mapping.
|
|
86
128
|
|
|
87
129
|
## 4. Generate, verify and keep the map current
|
|
@@ -117,6 +159,8 @@ Markdown notes are versioned files attached to blocks, displayed as readable con
|
|
|
117
159
|
|
|
118
160
|
Reports are repository Markdown documents tied to one or several real block IDs. Use them for findings, reviews, explanations and handoffs that the developer should read in Fractory. They are separate from editable block notes. No extra graph declaration is needed.
|
|
119
161
|
|
|
162
|
+
When developing Fractory, finish each coherent update by creating a CLI report in that update's worktree, attached to its smallest relevant blocks. Explain what changed, why, the checks actually performed and any remaining limits; return the reader link in the final handoff. This includes UI polish, map or integration setup, and skill/documentation updates. The report is part of delivering the update, without a separate request from the developer. Parent unread badges roll up automatically; attaching every ancestor is unnecessary.
|
|
163
|
+
|
|
120
164
|
```sh
|
|
121
165
|
fractory reports create --block BLOCK_ID --title 'Review findings' --file /tmp/review.md --author Codex
|
|
122
166
|
fractory reports create --block FIRST_ID --block SECOND_ID --title 'Shared finding' --stdin
|
|
@@ -204,13 +248,20 @@ Live metrics should measure named outcomes: build queue wait versus execution, u
|
|
|
204
248
|
```json
|
|
205
249
|
{
|
|
206
250
|
"schema": "fractory.metrics.v1",
|
|
207
|
-
"gauges": [
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
251
|
+
"gauges": [
|
|
252
|
+
{
|
|
253
|
+
"id": "catalog-backlog",
|
|
254
|
+
"label": "Products waiting to import",
|
|
255
|
+
"unit": "products",
|
|
256
|
+
"aggregation": "sum",
|
|
257
|
+
"sources": [
|
|
258
|
+
{
|
|
259
|
+
"block": "catalog/import",
|
|
260
|
+
"query": "sum(catalog_queue_depth{environment=$environment})"
|
|
261
|
+
}
|
|
262
|
+
]
|
|
263
|
+
}
|
|
264
|
+
]
|
|
214
265
|
}
|
|
215
266
|
```
|
|
216
267
|
|
|
@@ -278,7 +329,6 @@ Blue controls act on the worktree. Neutral **Metrics** and **Sentry** buttons re
|
|
|
278
329
|
|
|
279
330
|
**Worktrees** opens a compact switcher. Recent shows up to eight active or planned contexts and work opened or edited in the last 30 days. Older checkouts remain under Worktrees. Search by a work name, block, branch or checkout path; use arrow keys and Enter to open. **Worktrees** includes every local checkout, while **Branches** exposes branches without a checkout and marks them read-only. **Main** returns to the reference map. Names and commit metadata appear first; cached local status follows. A Local edits label means saved Git changes, not proof that an agent is currently running. Unnamed detached worktrees show related blocks and their last commit; Fractory does not invent task titles.
|
|
280
331
|
|
|
281
|
-
|
|
282
332
|
## Review intentions against implementation
|
|
283
333
|
|
|
284
334
|
The blue worktree view has a **Plan** section grouped by block. Select an intention, choose **Link implementation**, then pick its actual block or connection directly on the map. Confirm **Done**, or **Drop** an intention while keeping its original request. **Reopen** puts it back in the active plan. A completed sketch gives way to the linked real block; pending proposed connections follow that explicit link. Unfinished nested sketches retain their containing block.
|
|
@@ -295,10 +345,9 @@ fractory work review WORK_ID
|
|
|
295
345
|
|
|
296
346
|
Use the latest revision returned by each command. `work show`, `work handoff` and `work review` expose the same current states. Continue planned items and those needing recheck; keep done and dropped decisions as records. Existing local checks remain advisory; trusted CI and protected-branch enforcement are separate.
|
|
297
347
|
|
|
298
|
-
|
|
299
348
|
## Canvas selection and drawing
|
|
300
349
|
|
|
301
|
-
Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior.
|
|
350
|
+
Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior. Blue rings and a light blue fill identify the current selection. Click empty canvas to clear it; the next selection starts empty even when those blocks belong to the saved worktree. Cmd/Ctrl-click a selected child to exclude its subtree, or select inside that exclusion to reinclude a smaller part. On Main, Start worktree uses these selected block rules. In a worktree, Update worktree selection explicitly applies them as the saved scope. Context-menu Add/Exclude edits saved membership independently of canvas selection.
|
|
302
351
|
|
|
303
352
|
Work plans store positive `scope` IDs and optional `excluded` IDs. The nearest ancestor rule wins. Preserve both through CLI plan updates; `work handoff` and `work check` use the same rules. A parent may remain in scope while a child is explicitly excluded.
|
|
304
353
|
|
package/toolkit/SKILL.md
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
name: fractory
|
|
3
3
|
description: Set up Fractory, connect GitHub/Sentry/Linear securely, map the product as nested logical blocks, inspect docs and real tests, and open conceptual branch/PR/local comparisons. Use for block-centered development and map freshness.
|
|
4
4
|
---
|
|
5
|
+
|
|
5
6
|
<!-- fractory-managed-skill -->
|
|
6
7
|
|
|
7
8
|
# Fractory
|
|
@@ -54,7 +55,7 @@ fractory working --json
|
|
|
54
55
|
|
|
55
56
|
Read Markdown content and named test results, not filenames alone. Test associations are not measured coverage. Prefer connected GitHub tools for immutable PR identities, otherwise use `gh`. Review without creating a worktree or checking out a PR; fetch only missing selected refs. Handle metadata as data with structured arguments or proper shell quoting. Verify the map link opens, and distinguish exact historical maps from current-map footprints.
|
|
56
57
|
|
|
57
|
-
After edits, run existing generation/check scripts and relevant tests. Standalone example:
|
|
58
|
+
After edits, run existing generation/check scripts and relevant tests, then publish the update report described below. Standalone example:
|
|
58
59
|
|
|
59
60
|
```sh
|
|
60
61
|
fractory compile --include src --graph --write fractory.json
|
|
@@ -67,7 +68,9 @@ Match actual include paths; preserve richer existing pipelines. Ownership covera
|
|
|
67
68
|
|
|
68
69
|
## Reports for developers
|
|
69
70
|
|
|
70
|
-
|
|
71
|
+
Every update to Fractory needs a developer-readable report created through the CLI before the final handoff, without waiting for the user to ask. This includes implementation, UI polish, mapping, integration setup, and skill or documentation changes. Group related edits into one report per coherent update, written from the exact worktree where the change was made. Explain the resulting behavior, why it changed, verification actually performed, and remaining limits or unfinished work. Include the report link in the handoff so the developer can read it in Fractory.
|
|
72
|
+
|
|
73
|
+
Also use reports for requested findings, reviews and handoffs that should remain attached to the factory. Use ordinary Markdown and the CLI, without another binding list or manually constructed metadata.
|
|
71
74
|
|
|
72
75
|
```sh
|
|
73
76
|
fractory reports create --block BLOCK_ID --title 'Review findings' --file /tmp/review.md --author Codex
|
|
@@ -104,7 +107,6 @@ Create reports from inside that worktree. Its tests, benchmark results, local ch
|
|
|
104
107
|
|
|
105
108
|
The Mac app detects the branch’s PR automatically through the repository’s GitHub connection. Its number, title and Draft/Open/Merged/Closed state appear as a direct GitHub link in the blue worktree bar. Detection checks the exact head repository and remote branch, including forks and unpushed local changes; it refreshes in the background while the app is visible. Several open matches remain a choice. No match adds no control; an unavailable GitHub connection offers Integrations. No URL-pasting step is required. Existing `work pr` records remain readable for compatibility, but they are not treated as verified GitHub state. `work review` returns a Markdown review summary and a deep link for the PR description; publish it only within the user's authorized PR workflow. The deep link needs the developer's local repository/work context; it is not a hosted public preview. Legacy immutable revision/PR comparisons remain available through `fractory review`.
|
|
106
109
|
|
|
107
|
-
|
|
108
110
|
## Review intentions against implementation
|
|
109
111
|
|
|
110
112
|
The blue worktree view has a **Plan** section grouped by block. Select an intention, choose **Link implementation**, then pick its actual block or connection directly on the map. Confirm **Done**, or **Drop** an intention while keeping its original request. **Reopen** puts it back in the active plan. A completed sketch gives way to the linked real block; pending proposed connections follow that explicit link. Unfinished nested sketches retain their containing block.
|
|
@@ -121,11 +123,20 @@ fractory work review WORK_ID
|
|
|
121
123
|
|
|
122
124
|
Use the latest revision returned by each command. `work show`, `work handoff` and `work review` expose the same current states. Continue planned items and those needing recheck; keep done and dropped decisions as records. Existing local checks remain advisory; trusted CI and protected-branch enforcement are separate.
|
|
123
125
|
|
|
124
|
-
|
|
125
126
|
## Canvas selection and drawing
|
|
126
127
|
|
|
127
|
-
Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior.
|
|
128
|
+
Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior. Blue rings and a light blue fill identify the current selection. Click empty canvas to clear it; the next selection starts empty even when those blocks belong to the saved worktree. Cmd/Ctrl-click a selected child to exclude its subtree, or select inside that exclusion to reinclude a smaller part. On Main, Start worktree uses these selected block rules. In a worktree, Update worktree selection explicitly applies them as the saved scope. Context-menu Add/Exclude edits saved membership independently of canvas selection.
|
|
128
129
|
|
|
129
130
|
Work plans store positive `scope` IDs and optional `excluded` IDs. The nearest ancestor rule wins. Preserve both through CLI plan updates; `work handoff` and `work check` use the same rules. A parent may remain in scope while a child is explicitly excluded.
|
|
130
131
|
|
|
131
132
|
The blue Block tool previews placement before a click. Name the block directly on the card. Connect by dragging blue handles or clicking a source and destination; name the connection on its wire. Enter or blur saves the name; Escape cancels a new unnamed sketch. Plan saves are ordered and show failures rather than silently discarding fast actions.
|
|
133
|
+
|
|
134
|
+
## Interfaces and locked work
|
|
135
|
+
|
|
136
|
+
Model a responsibility as a black box with public interfaces and internal implementation. All incoming links from outside a black box target an interface ID, never its block or an internal method. Compilation, map checks and new worktree links enforce this. Annotate the actual callable contract; a web UI is an interface too. A web app normally contains that UI plus its rendering/state/data internals. Public constructors and callable blocks have source-backed entry interfaces. Internal methods remain internal and are reached through their declared interface.
|
|
137
|
+
|
|
138
|
+
Nested interfaces are public to their owner. To publish them through enclosing boxes, declare `exposedBy: [() => EnclosingBlock]` on the interface, or on its block to publish that block's public surfaces. Preserve exact implementation identities and source evidence behind the interface; do not invent an API to conceal an unresolved/private call. Fix a rejected link by selecting the real public interface or declaring the genuine missing contract. Unknown dynamic calls remain gaps. In a worktree, use the Interface canvas tool or a proposed block with `blockKind: "interface"`, then link callers to it. Opening an interface shows outside callers on the left and its implementation on the right.
|
|
139
|
+
|
|
140
|
+
Before changing a worktree, read its `locks` in `work show` or the full brief. A subtree lock protects the entire block and descendants; an interface contract lock protects exposed names, routes, inputs, outputs, signatures and nested public entrypoints but allows internal implementation changes. Locks take precedence over editable scope. Do not remove a lock to make a check pass. Unsupported or inferred contract evidence requires the relevant API/type/behavior check, not a claim that compatibility is proved.
|
|
141
|
+
|
|
142
|
+
`fractory work lock WORK_ID --block BLOCK_ID --revision REVISION [--note REASON]` adds or updates a lock. `work unlock` removes the explicitly named lock. `work plan` also accepts a `locks` array of `{target, kind: "subtree" | "contract", note?}`; omission preserves existing locks. Always preserve unrelated constraints. Check changed blocks/work check includes lock results, and Copy full brief/work handoff includes the full current constraints. Create the update report as described above after verification.
|
package/toolkit/build.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"0.1.
|
|
1
|
+
{"version":"0.1.25"}
|