Skip to content

Commit 99fe43a

Browse files
committed
📝 Say what this workflow does, now that it does it
The living workflow, its two specifications and `architecture.md` still read like construction notes: a status line calling the whole thing an end-goal target and an inventory measured against `main`, a paragraph saying #301 slice 2 owes the composition, table rows calling the adversarial loop and mutation-proposal admission unbuilt, a Workspace specification saying the Git operations of §7 are not built, a runtime document opening with the claim that the repository, worktree, process and working-directory capabilities are not there yet, an Agent ceiling described as a read/search permission bridge inside a native read-only sandbox, replay re-registering Agent directories that are never registered, and four documents insisting that nothing schedules a resume. Every one of those was true of an earlier revision and is false of this one, which #299 certified from outside the process that runs it. So the documents describe the revision containing them. The composition, the Repository and Worktree topology, the generated observation and mutation admission, the Git and Git-host effects and the durable checkpoints are stated as built — with the one real exclusion beside them, which is that a generated fragment admits no workflow-bundled Markdown component. The Agent ceiling is the profile that ships: an empty provider-owned directory, no additional directory, no MCP server, an empty requested tool set, deny-all, and a native permission request denied and failing its turn, with #496 kept as the explicit nonclaim about portable adapter-level tool absence. Replay reattaches that profile's own session arrangement rather than a directory nobody registered. Delivery executes nothing, and a continuation is asked for — by a person, or by a trusted host deciding *when* through the scheduler #300 built. Both take the same executor lock and run the same path, and no watcher, delivery-to-resume wiring, unattended arbitration or second executor exists. The specification's last construction-era section goes with them. What stood under "Open" was four boundaries this composition already runs inside and one question about somebody else's filesystem; they are recorded as settled boundaries, generated Git, Git-host, issue, process, execution, credential and external-write effects are stated as outside admission rather than as a class still to be decided, and the exercise framing that asked a reader to resolve enough of them for one vertical slice is gone. What this workflow does not do is now written down as such. Worker Shell stays #363's; actor attestation, a remote-host selector, configured watchers, an out-of-band inspector and a lab or `xmd play` surface are nonclaims with their reasons, not roadmap promises; #227 owns the host filesystem's validate-then-use guarantee, which a provider-owned Workspace namespace never races, and #327 owns the outer `<PrintErrors>`/`<Output>` correction, which this workflow writes no region for. The issue map records what each issue delivered: #290 and #301 implemented on PR #181 and closing with its merge, #300's explicit scheduling shipped beside the exclusion it is not, undefined-prop omission shipped by #537 and #541, and #299 PASS at the certified head and base. Two corrections are about ownership rather than status. `<Worktree>` is self-closing: it creates or restores the named checkout and binds its path, renders no children and establishes no working directory, and the lexical `<Dir>` consumes that binding and owns cwd. The shared Git-host reconciliation stands behind Push and PullRequest, while `<Issue>` reconciles through its own provider-neutral `IssueApi`. `SYNC1` keeps them honest, beside AC0–AC7 rather than inside them. It is a source-truth case: a small table of what each owned document must say and the claims none of them may make again, matched against the flattened text so it is about sentences rather than line breaks. Restoring any one of those claims fails it. It supplements semantic review and does not replace it. SCH9's reviewed blobs move with the documents this synchronization edited, under independent Planner review, and its `525efaa7` over `170a021d` provenance is untouched. Claude-Session: https://claude.ai/code/session_01MNztk1fikXUnD2FW4yS6Kr
1 parent e85479c commit 99fe43a

12 files changed

Lines changed: 470 additions & 189 deletions

‎architecture.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1051,7 +1051,9 @@ workflow capability is absent.
10511051
Replay rehydrates the Effection tree. A completed durable effect restores its
10521052
recorded result without executing again. Ephemeral operations run again only to
10531053
rebuild live structure: attach the Workspace, enter lexical working-directory
1054-
scopes, attach providers and re-register Agent directories. A completed root
1054+
scopes, and attach providers — including the Agent profile's own session
1055+
arrangement, which is a provider-owned empty directory and a retained session
1056+
mapping rather than a directory registered with an Agent. A completed root
10551057
result returns without attaching any provider.
10561058

10571059
The Workspace stores the current frontier state. The journal stores the
@@ -1694,9 +1696,12 @@ identities and the constraint travels with the pinned one, decided in the
16941696
whole-fragment preflight rather than inside the component after earlier elements
16951697
have run.
16961698

1697-
Mutation-proposal admission and workflow-bundled Markdown component admission
1698-
remain unbuilt. Directory registration is not among them: a workflow Agent is
1699-
given no directory to register.
1699+
Mutation-proposal admission is built (#369, delivered by #572): a generated
1700+
fragment's paired `<File>`, lexical `<Dir>` and self-closing `<File.Delete>` are
1701+
admitted by class and authored form, and each admitted element runs as the
1702+
ordinary component it is. What remains unbuilt beside it is workflow-bundled
1703+
Markdown component admission — a generated fragment names none. Directory
1704+
registration is neither: a workflow Agent is given no directory to register.
17001705

17011706
## Local Workspace topology
17021707

@@ -3188,7 +3193,7 @@ durable is written.
31883193

31893194
## Construct inventory
31903195

3191-
Status is measured against main.
3196+
Status is measured against the revision containing this document.
31923197

31933198
| Construct | Does | Status |
31943199
| --- | --- | --- |
@@ -3203,7 +3208,7 @@ Status is measured against main.
32033208
| document-aware `xmd run … --help` | describes what one document declares and every target it addresses, each as a full document reference with the description its section states, by inspection alone | built on the #463 stack |
32043209
| targeted `xmd run` | reads a file argument as a document reference and executes the one exact target its selector resolved to, replacing the selector before execution rereads the file | built on the #412 stack |
32053210
| targeted workflow definition | the V1 workflow definition optionally carries the exact canonical document target, which takes part in definition identity and in compatible reuse | built on the #412 stack; the workflow CLI does not supply one yet |
3206-
| workflow component bundle | a workflow root declares a closed set of authored Markdown components; the V1 workflow definition optionally carries them as one array sorted by component name, each entry holding the name, its canonical repository-relative path inside the pinned commit and that blob's object ID, and an absent member identifies a run closed over no components — so a definition retained before the member existed reads unchanged. `start` and `resume` read every component from the definition's own pinned commit; the array takes part in definition identity and is compared as part of the same V1 descriptor in compatible reuse; and canonical core resolves those names and holds both live import and retained history to that exact bundle | built on the #301 stack; the full adversarial implementation loop remains unbuilt, and explicit host scheduling of its ordinary resume is built by #300, and generated XMD admits no bundled Markdown component (#369) |
3211+
| workflow component bundle | a workflow root declares a closed set of authored Markdown components; the V1 workflow definition optionally carries them as one array sorted by component name, each entry holding the name, its canonical repository-relative path inside the pinned commit and that blob's object ID, and an absent member identifies a run closed over no components — so a definition retained before the member existed reads unchanged. `start` and `resume` read every component from the definition's own pinned commit; the array takes part in definition identity and is compared as part of the same V1 descriptor in compatible reuse; and canonical core resolves those names and holds both live import and retained history to that exact bundle | built on the #301 stack, which is also where the complete adversarial implementation loop is built; explicit host scheduling of its ordinary resume is built by #300, and generated XMD admits no bundled Markdown component (#369) |
32073212
| `workflowInstallation()` / `getWorkflowRun()` | associates one document execution with a workflow run, through an `ExecutionInstallation` the trusted host passes to `executeInstalled()` | built on the #366 stack |
32083213
| `retainedWorkflowInstallation()` | associates one document execution with a run storage already created, requiring exact journal agreement | built on the #366 stack |
32093214
| `Git.revParse()` | verifies and resolves one Git revision expression contextually | built on main |
@@ -3228,7 +3233,7 @@ Status is measured against main.
32283233
| `ephemeral eval` | reconstructs live middleware and bindings without a journal entry | built on main |
32293234
| `useWorkflowServiceDenial()` | provides a non-delegating workflow service denial provider, installed inside every start and resume execution scope | built on the #366 stack |
32303235
| `xmd workflow start` / `xmd workflow resume` | starts or resumes a workflow run from the CLI, under the Deno entrypoints only | built on the #366 stack; both acquire #367's executor lock before any lifecycle transition |
3231-
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack and Repository/Worktree composition on the #293 stack; process capabilities unbuilt (#218) |
3236+
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack and Repository/Worktree composition on the #293 stack; a command the document runs executes under the run and its result is retained with it, so a continuation reads the result back rather than running the command again |
32323237
| `<Repository>` / `<Worktree>` / `<Dir>` composition | names a Git repository and its linked checkouts inside the run-owned Workspace, installs each as contextual working directory, and retains creation identity beside the retained Git bytes | built on the #293 stack, Deno provider only |
32333238
| transactional Git effects (`Git.Switch` / `Git.Add` / `Git.Commit`) | publish local Git mutations with their journal result; the enclosing Repository and the contextual working directory select which retained checkout one runs in, and neither observation carries authority — the observed record is compared with the retained row and the directory with the checkouts that row holds, so a failure of authority, of retained state or of an unrecognized native condition fails the run instead of publishing a result | built on the #294 stack, Deno provider only |
32343239
| `Git.Push` | publishes the selected checkout's exact current named branch and commit to the same branch on the retained Repository's canonical `origin`, reconciled through the shared Git-host state machine rather than through a Workspace transaction: no props and no component result, no force, no upstream mutation and no implicit staging or committing; the durable request and record carry the Repository's filtered identity without its checkout path, and the transport runs in a provider-owned isolated control repository reading the checkout's objects through an object-source attachment whose alternates chain and object tree are proven contained before the first remote observation, aimed at the exact private retained locator. A destination proven absent is published to once and one already naming this exact commit is adopted; one naming a distinct commit that same authenticated source proves is in this commit's ancestry is a performable pre-state, published over by the same exact non-force refspec and retained as the predecessor with the attested relation, while a divergent commit and one the source cannot read are both conflicts and nothing is fetched to decide either; a completed Push is reconstructed from the Workspace root its own journal event was appended against, read without publishing it or moving the run's frontier, so a branch published more than once resumes | built on the #370 stack, Deno provider only |

‎packages/cli/tests/workflow-scheduling.test.ts‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1014,40 +1014,41 @@ const REVIEWED_CONSUMER_ROOTS = [
10141014
* name the base at all.
10151015
*
10161016
* The provenance below is unchanged: this slice was reviewed on PR #181 head
1017-
* `525efaa7` over `170a021d`, and it still is. Two of these blobs have moved
1018-
* since, and only through a repair reviewed in its own right — #299's R3
1019-
* corrected the observation instruction the Implementation stage renders, and
1020-
* extended AC2 to send it, so the workflow document and the composition suite
1021-
* each hold one approved change. Pinning what they hold now is what keeps this
1022-
* case a statement about *this* slice changing them rather than a statement
1023-
* about nobody changing them.
1017+
* `525efaa7` over `170a021d`, and it still is. What has moved since are blobs,
1018+
* and only through work reviewed in its own right — #299's R3 corrected the
1019+
* observation instruction the Implementation stage renders and extended AC2 to
1020+
* send it, and #292's final synchronization then made the workflow documents
1021+
* describe the delivered revision and added `SYNC1` beside AC0–AC7, each under
1022+
* independent Planner review. Pinning what those files hold now is what keeps
1023+
* this case a statement about *this* slice changing them rather than a
1024+
* statement about nobody changing them.
10241025
*/
10251026
const REVIEWED_CONSUMER: readonly (readonly [string, string])[] = [
10261027
[
10271028
"scripts/tests/adversarial-composition-workflow.test.ts",
1028-
"bb942b506d67431b1621c99ea3e08242a62f77cf",
1029+
"adf7e58e609c116e2f93fb97e3592bc70756f24b",
10291030
],
10301031
["workflows/adversarial-implementation/Discovery.md", "eea1c650fe5a9d417595b9b457b73dc51485f05a"],
10311032
[
10321033
"workflows/adversarial-implementation/Implementation.md",
1033-
"c38076574eae1b55304eade578480f8efbdf3f4b",
1034+
"65333321a163f125d6021f807ac14108e049deac",
10341035
],
10351036
[
10361037
"workflows/adversarial-implementation/InstructionFiles.md",
10371038
"7ce93d7c1b7f79c560c9a861f27e7597697724d9",
10381039
],
1039-
["workflows/adversarial-implementation/Planning.md", "cc3b3f473da35c94a8fba541afc20536a8fe3d19"],
1040+
["workflows/adversarial-implementation/Planning.md", "943cb9701e3f4a464f13606547ca319e770aecf3"],
10401041
[
10411042
"workflows/adversarial-implementation/UserCheckpoint.md",
1042-
"54f1e97bbee1890fe77ec7b3e19277031cc101d3",
1043+
"576e352ac232426c157a33be964402d600a545bc",
10431044
],
1044-
["workflows/adversarial-implementation/artifacts.md", "dd8462a76d604f14cd9eeeb618faa8f6bfa24664"],
1045+
["workflows/adversarial-implementation/artifacts.md", "98899d95b70286851c08b5ccb10e26fd7b20e17e"],
10451046
[
10461047
"workflows/adversarial-implementation/primitives.md",
1047-
"17a89b9c5474a8ebb41964a016213ecfcc032b96",
1048+
"9e66ca0df27608a3c2a6f2887db5b7cb4ed1e34a",
10481049
],
1049-
["workflows/adversarial-implementation/runtime.md", "f13cb034b1321860916a48e5c80d205b3f7bcb6a"],
1050-
["workflows/adversarial-implementation/start.md", "0e248182f89a3b4fe3a1d1e316e239c4195ce3f0"],
1050+
["workflows/adversarial-implementation/runtime.md", "128fb2c1337b5d78890ebc05dcfe79f7416d7f3c"],
1051+
["workflows/adversarial-implementation/start.md", "b898f95188e5e1940e0e483a9ce74e69c49a53f2"],
10511052
[
10521053
"workflows/adversarial-implementation/tests/agents/checkpoint-material-choice.md",
10531054
"c126bdfe64c227c381317bf12338e235c52e78b5",

‎scripts/tests/adversarial-composition-workflow.test.ts‎

Lines changed: 179 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -84,13 +84,10 @@ import type {
8484
RepositoryHost,
8585
} from "../../packages/workflow/src/deno/composition/host.ts";
8686

87-
const WORKFLOW = join(
88-
dirname(fileURLToPath(import.meta.url)),
89-
"..",
90-
"..",
91-
"workflows",
92-
"adversarial-implementation",
93-
);
87+
/** The checkout this suite reads its subject out of. */
88+
const REPOSITORY_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
89+
90+
const WORKFLOW = join(REPOSITORY_ROOT, "workflows", "adversarial-implementation");
9491

9592
const ROOT_PATH = "workflows/adversarial-implementation/start.md";
9693

@@ -2319,3 +2316,178 @@ describe("Tier AC — the adversarial workflow, composed", () => {
23192316
expect(otherForge.calls.filter((made) => made === "git:push")).toHaveLength(1);
23202317
});
23212318
});
2319+
2320+
/**
2321+
* The claims each owned document must make, and the ones it must not.
2322+
*
2323+
* `SYNC1` is a source-truth case, not a behavioural one: what it holds is that
2324+
* the documents describe the revision containing them. It is deliberately
2325+
* small. Every entry is a statement whose return would make a settled contract
2326+
* false — a loop called unbuilt that is built, an Agent ceiling described as a
2327+
* read/search bridge, a scheduler said not to exist — rather than a snapshot of
2328+
* how a paragraph happens to be worded, which would make every edit a failure.
2329+
*
2330+
* Semantic review is still the Planner's. This catches the exact regressions
2331+
* #292 repaired, and claims nothing about the prose around them.
2332+
*/
2333+
interface OwnedDocument {
2334+
readonly path: string;
2335+
/** Statements this revision makes, which a stale document would not. */
2336+
readonly requires: readonly string[];
2337+
/** Statements only this document could make again, beyond the shared list. */
2338+
readonly refuses?: readonly string[];
2339+
}
2340+
2341+
const OWNED_DOCUMENTS: readonly OwnedDocument[] = [
2342+
{
2343+
path: "architecture.md",
2344+
requires: [
2345+
"which is also where the complete adversarial implementation loop is built",
2346+
"Status is measured against the revision containing this document",
2347+
"Mutation-proposal admission is built",
2348+
"workflow-bundled Markdown component admission",
2349+
],
2350+
},
2351+
{
2352+
path: "specs/adversarial-implementation-workflow.md",
2353+
requires: [
2354+
"PR #181 delivers it, and #299 certified it",
2355+
"asks for an empty native tool set and runs deny-all",
2356+
"The portable adapter-level proof is #496's",
2357+
"a trusted host that has observed the delivery and decides the run should continue now",
2358+
"Runtime intervention is a nonclaim",
2359+
"#299 certified the following end to end",
2360+
"Settled by exclusion",
2361+
"A nonclaim: who answered",
2362+
"Settled composition boundaries",
2363+
"stay outside admission, and a fragment naming one performs nothing at all",
2364+
"#227 owns it, for ordinary `xmd run` against a host directory",
2365+
"#327 owns it, and this workflow writes no `<PrintErrors>` region",
2366+
],
2367+
},
2368+
{
2369+
path: "specs/workflow-workspace-spec.md",
2370+
requires: ["and so are the Git operations of §7"],
2371+
},
2372+
{
2373+
path: "workflows/adversarial-implementation/start.md",
2374+
requires: [
2375+
"#299 certified it end to end",
2376+
"takes the same executor lock and runs the same path",
2377+
],
2378+
},
2379+
{
2380+
path: "workflows/adversarial-implementation/runtime.md",
2381+
requires: [
2382+
'<Worktree name="implementation" branch={props.branch} as="worktree" />',
2383+
"<Dir path={worktree}>",
2384+
"asks for an empty native tool set, and runs deny-all",
2385+
"It renders no children and establishes no working directory",
2386+
"`<Dir>` consumes that binding and owns cwd",
2387+
],
2388+
},
2389+
{
2390+
path: "workflows/adversarial-implementation/primitives.md",
2391+
requires: [
2392+
"What this workflow does not claim",
2393+
"excluded from this delivery",
2394+
"#299 certified them from outside the process that runs them",
2395+
"`<Issue>` has its own `IssueApi` boundary",
2396+
"implemented on PR #181; closes with its merge",
2397+
"delivered by #537 and #541",
2398+
"PASS at head `e85479c33ce4c91d821e0eaf195150db374ae4a6`",
2399+
"`<Discovery>` is the text component of the four",
2400+
],
2401+
},
2402+
{
2403+
path: "workflows/adversarial-implementation/UserCheckpoint.md",
2404+
requires: ["delivery executes nothing, and a continuation is asked for"],
2405+
},
2406+
{
2407+
path: "workflows/adversarial-implementation/Implementation.md",
2408+
requires: [
2409+
"shared Git-host reconciliation behind push and pull request",
2410+
"`<Issue>` reconciles through its own provider-neutral `IssueApi`",
2411+
],
2412+
refuses: ["reconciliation behind push, pull request and issue"],
2413+
},
2414+
{
2415+
path: "workflows/adversarial-implementation/Planning.md",
2416+
requires: ["#300 built the one thing a trusted host may decide about it"],
2417+
},
2418+
{
2419+
path: "workflows/adversarial-implementation/artifacts.md",
2420+
requires: [
2421+
"A nonclaim: who answered",
2422+
"reattach the Agent session arrangement the strict profile uses",
2423+
],
2424+
},
2425+
];
2426+
2427+
/**
2428+
* Claims no owned document may make again, whichever one made it.
2429+
*
2430+
* Each of these was true of an earlier revision and is false of this one, so a
2431+
* document that says it again is describing something that is not here.
2432+
*/
2433+
const OBSOLETE = [
2434+
"Living end-goal target",
2435+
"What #301 slice 2 owes",
2436+
"the full adversarial implementation loop remains unbuilt",
2437+
"Git operations of §7 are not",
2438+
"process capabilities unbuilt (#218)",
2439+
"no scheduler resumes a run",
2440+
"nothing schedules a resume",
2441+
"automatic scheduling is not shipped",
2442+
"allows only read and search operations",
2443+
"provider runs in its native read-only sandbox",
2444+
"the scheduling slice is #300's",
2445+
"Status is measured against main",
2446+
"re-register Agent directories",
2447+
"Still missing: who answered",
2448+
"Mutation-proposal admission and workflow-bundled Markdown component admission remain unbuilt",
2449+
"capabilities the stages want are composition it does not have yet",
2450+
"The exercise succeeds when",
2451+
"The first implementation need not answer every question",
2452+
"### Open",
2453+
"The exercise must resolve enough of these to implement one vertical slice",
2454+
"What remains open is not admission but its class",
2455+
] as const;
2456+
2457+
/**
2458+
* One document's text, with its wrapping removed.
2459+
*
2460+
* A claim is a sentence, and a sentence in Markdown is wrapped wherever the
2461+
* column ran out. Matching the flattened text is what keeps this case about
2462+
* what a document says rather than about where its lines break.
2463+
*/
2464+
function* flattened(path: string): Operation<string> {
2465+
return (yield* readTextFile(join(REPOSITORY_ROOT, path))).replace(/\s+/g, " ");
2466+
}
2467+
2468+
/** The same, for a claim written with the same wrapping freedom. */
2469+
function claim(written: string): string {
2470+
return written.replace(/\s+/g, " ");
2471+
}
2472+
2473+
describe("Tier AC — the living workflow against the delivered composition", () => {
2474+
it("SYNC1: the living workflow describes the delivered composition", function* () {
2475+
for (const document of OWNED_DOCUMENTS) {
2476+
const source = yield* flattened(document.path);
2477+
2478+
// What this revision does, said where a reader meets it.
2479+
for (const required of document.requires) {
2480+
expect([document.path, source.includes(claim(required))]).toEqual([document.path, true]);
2481+
}
2482+
2483+
// And what it no longer does, wherever that was written.
2484+
for (const refused of [...OBSOLETE, ...(document.refuses ?? [])]) {
2485+
expect([document.path, refused, source.includes(claim(refused))]).toEqual([
2486+
document.path,
2487+
refused,
2488+
false,
2489+
]);
2490+
}
2491+
}
2492+
});
2493+
});

0 commit comments

Comments
 (0)