@alisio/plugin-wayfinder 0.1.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 (62) hide show
  1. package/.agents/agents/archivist.md +18 -0
  2. package/.agents/agents/coordinator.md +16 -0
  3. package/.agents/agents/designer.md +18 -0
  4. package/.agents/agents/discoverer.md +18 -0
  5. package/.agents/agents/implementer.md +18 -0
  6. package/.agents/agents/mutationist.md +18 -0
  7. package/.agents/agents/planner.md +18 -0
  8. package/.agents/agents/proposer.md +18 -0
  9. package/.agents/agents/specifier.md +18 -0
  10. package/.agents/agents/verifier.md +18 -0
  11. package/.agents/skills/wayfinder-archive/SKILL.md +43 -0
  12. package/.agents/skills/wayfinder-coordinate/SKILL.md +44 -0
  13. package/.agents/skills/wayfinder-design/SKILL.md +42 -0
  14. package/.agents/skills/wayfinder-discover/SKILL.md +42 -0
  15. package/.agents/skills/wayfinder-implement/SKILL.md +53 -0
  16. package/.agents/skills/wayfinder-mutate/SKILL.md +44 -0
  17. package/.agents/skills/wayfinder-plan/SKILL.md +48 -0
  18. package/.agents/skills/wayfinder-propose/SKILL.md +42 -0
  19. package/.agents/skills/wayfinder-specify/SKILL.md +43 -0
  20. package/.agents/skills/wayfinder-test-design/SKILL.md +48 -0
  21. package/.agents/skills/wayfinder-verify/SKILL.md +48 -0
  22. package/LICENSE +21 -0
  23. package/README.md +396 -0
  24. package/assets/agent-communication.svg +1 -0
  25. package/assets/methodology-flow.svg +1 -0
  26. package/dist/coordinator.d.ts +46 -0
  27. package/dist/coordinator.d.ts.map +1 -0
  28. package/dist/coordinator.js +978 -0
  29. package/dist/coordinator.js.map +1 -0
  30. package/dist/index.d.ts +18 -0
  31. package/dist/index.d.ts.map +1 -0
  32. package/dist/index.js +36 -0
  33. package/dist/index.js.map +1 -0
  34. package/dist/mutation.d.ts +67 -0
  35. package/dist/mutation.d.ts.map +1 -0
  36. package/dist/mutation.js +398 -0
  37. package/dist/mutation.js.map +1 -0
  38. package/dist/resources.d.ts +14 -0
  39. package/dist/resources.d.ts.map +1 -0
  40. package/dist/resources.js +142 -0
  41. package/dist/resources.js.map +1 -0
  42. package/dist/storage.d.ts +15 -0
  43. package/dist/storage.d.ts.map +1 -0
  44. package/dist/storage.js +282 -0
  45. package/dist/storage.js.map +1 -0
  46. package/dist/testing-rules.d.ts +3 -0
  47. package/dist/testing-rules.d.ts.map +1 -0
  48. package/dist/testing-rules.js +33 -0
  49. package/dist/testing-rules.js.map +1 -0
  50. package/dist/types.d.ts +214 -0
  51. package/dist/types.d.ts.map +1 -0
  52. package/dist/types.js +25 -0
  53. package/dist/types.js.map +1 -0
  54. package/dist/validation.d.ts +17 -0
  55. package/dist/validation.d.ts.map +1 -0
  56. package/dist/validation.js +357 -0
  57. package/dist/validation.js.map +1 -0
  58. package/dist/version.d.ts +2 -0
  59. package/dist/version.d.ts.map +1 -0
  60. package/dist/version.js +3 -0
  61. package/dist/version.js.map +1 -0
  62. package/package.json +50 -0
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: wayfinder-verify
3
+ description: "Trigger: wayfinder verify, independent verification. Inspect reality and cover every requirement exactly once."
4
+ license: MIT
5
+ metadata:
6
+ author: alisio-contributors
7
+ version: 1.0
8
+ ---
9
+
10
+ ## Activation Contract
11
+
12
+ Load after all approved work units report completion.
13
+
14
+ ## Hard Rules
15
+
16
+ - Treat implementation reports as context, never proof.
17
+ - Inspect actual files and execute focused checks independently.
18
+ - Cover every requirement the coordinator assigns exactly once with non-empty evidence.
19
+ - When a targeted requirement subset is supplied, cover exactly that subset and no others.
20
+ - Check each functional scenario has a happy-path and an unhappy-path test; fail a scenario covered on only one side.
21
+ - For UI changes, check tests avoid fragile selectors and use semantic, convention-matching ids.
22
+ - Fail on missing evidence, failed behavior, or any blocker.
23
+ - Never write or delegate.
24
+
25
+ ## Decision Gates
26
+
27
+ | Evidence | Result |
28
+ | --- | --- |
29
+ | Repository plus command evidence agree | Requirement may pass |
30
+ | A scenario has only happy or only unhappy tests | Requirement fails |
31
+ | UI tests rely on implementation classes or deep DOM chains | Requirement fails |
32
+ | Evidence is narrative only | Requirement fails |
33
+ | Any blocker remains | Overall result fails |
34
+
35
+ ## Execution Steps
36
+
37
+ 1. Map each requirement to observable repository evidence.
38
+ 2. Run focused commands, including tests where available.
39
+ 3. Record one verdict per requirement.
40
+ 4. Return consistent overall status and blockers.
41
+
42
+ ## Output Contract
43
+
44
+ Return overall status, requirement verdicts, passed command evidence, and blockers.
45
+
46
+ ## References
47
+
48
+ - `../../../README.md`
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alisio contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,396 @@
1
+ # Wayfinder
2
+
3
+ Wayfinder is a self-contained Alisio plugin for running resumable, specification-driven changes.
4
+ A deterministic coordinator owns transitions, gates, and durable state. Fresh child sessions
5
+ perform bounded analysis, implementation, and verification from package-owned agent and skill
6
+ resources.
7
+
8
+ Wayfinder is independent of other plugins, but it is not a standalone executable. It requires
9
+ Alisio, an active Alisio session, and a configured model.
10
+
11
+ ## Quick path
12
+
13
+ Install it persistently through Alisio:
14
+
15
+ ```bash
16
+ alisio install npm:@alisio/plugin-wayfinder
17
+ ```
18
+
19
+ For project-local development instead:
20
+
21
+ ```bash
22
+ npm install --save-dev @alisio/plugin-wayfinder
23
+ alisio --plugin @alisio/plugin-wayfinder
24
+ ```
25
+
26
+ ```text
27
+ /wayfinder:new add-health-check -- Expose a health endpoint for load balancers
28
+ /wayfinder:next add-health-check
29
+ /wayfinder:status add-health-check
30
+ ```
31
+
32
+ Each `next` invocation runs at most one phase. Follow the command shown by `status`. Open questions
33
+ use `/wayfinder:answer <change> -- <clarification>`. Proposal and plan approval use
34
+ `/wayfinder:approve <change> <proposal|plan>`.
35
+
36
+ ## Complete workflow
37
+
38
+ ```text
39
+ /wayfinder:new add-health-check -- Expose a health endpoint for load balancers
40
+ /wayfinder:next add-health-check # discovery
41
+ /wayfinder:next add-health-check # proposal
42
+ /wayfinder:approve add-health-check proposal
43
+ /wayfinder:next add-health-check # specification
44
+ /wayfinder:next add-health-check # design
45
+ /wayfinder:next add-health-check # plan
46
+ /wayfinder:tdd add-health-check strict -- drive the new behavior test-first
47
+ /wayfinder:approve add-health-check plan
48
+ /wayfinder:build add-health-check # repeat once per pending unit
49
+ /wayfinder:verify add-health-check # verification passes, mutation decision required
50
+ /wayfinder:mutate add-health-check run -- cover the new branch
51
+ /wayfinder:verify add-health-check # runs the bounded mutation check
52
+ /wayfinder:close add-health-check
53
+ ```
54
+
55
+ Mutation testing is recommended, but the developer decides. Record `run` or `skip` with a reason
56
+ before archive; the decision is immutable per change. Skipping is fine when justified.
57
+
58
+ Test-first is also recommended and developer-decided. Record `strict` or `off` with a reason before
59
+ approving the plan; the decision is immutable per change.
60
+
61
+ Use `/wayfinder:status add-health-check` at any point to recover the next action. If a phase reports
62
+ a critical question, answer it and retry the same phase:
63
+
64
+ ```text
65
+ /wayfinder:answer add-health-check -- Only authenticated internal load balancers may access it
66
+ /wayfinder:next add-health-check
67
+ ```
68
+
69
+ ## Architecture
70
+
71
+ The TypeScript `WayfinderCoordinator` is the workflow authority. It validates child JSON, enforces
72
+ gates, replaces each persisted file atomically, and advances durable state under
73
+ `.alisio/wayfinder/changes/<change>/`. Artifact and state updates are separate writes rather than one
74
+ cross-file transaction.
75
+
76
+ Runtime role instructions live in `.agents/agents`, while focused phase contracts live in
77
+ `.agents/skills`. Direct child sessions load and inline those canonical files, so execution does
78
+ not depend on skill discovery. TypeScript profiles define the effective permissions and limits for
79
+ this direct execution path; agent frontmatter describes the equivalent catalog-facing contract.
80
+
81
+ | Agent | Responsibility | Capabilities |
82
+ | --- | --- | --- |
83
+ | `coordinator` | Inspectable catalog-facing guidance; it is not the TypeScript workflow authority | Read-only, no process |
84
+ | `discoverer` | Repository evidence and critical questions | Read-only, no process |
85
+ | `proposer` | Approval-ready outcome and boundaries | Read-only, no process |
86
+ | `specifier` | Observable requirements | Read-only, no process |
87
+ | `designer` | Lean technical approach | Read-only, no process |
88
+ | `planner` | Ordered units and complete coverage | Read-only, no process |
89
+ | `implementer` | One approved work unit | Write and process |
90
+ | `verifier` | Independent evidence and checks | Read-only, process allowed |
91
+ | `mutationist` | One bounded mutation run on already-installed tooling | Read-only, process allowed |
92
+ | `archivist` | Archive-readiness inventory | Read-only, no process |
93
+
94
+ Each agent links one or more focused skills drawn from `wayfinder-coordinate`,
95
+ `wayfinder-discover`, `wayfinder-propose`, `wayfinder-specify`, `wayfinder-design`,
96
+ `wayfinder-plan`, `wayfinder-implement`, `wayfinder-verify`, `wayfinder-mutate`,
97
+ `wayfinder-archive`, and `wayfinder-test-design`. The planner, implementer, and verifier load both
98
+ their phase skill and `wayfinder-test-design`; a role loads every mapped skill in order. Child phases
99
+ cannot delegate.
100
+
101
+ ## How agents communicate
102
+
103
+ Agents never call each other directly and do not inherit another agent's conversation. Every phase
104
+ communicates through the TypeScript `WayfinderCoordinator` and durable artifacts:
105
+
106
+ ```text
107
+ User command
108
+ -> WayfinderCoordinator loads one agent and all its mapped skills
109
+ -> coordinator creates a fresh, capability-narrowed child session
110
+ -> child returns one phase-specific JSON result
111
+ -> coordinator validates the complete result
112
+ -> coordinator renders the validated result as a Markdown artifact
113
+ -> coordinator updates state.json
114
+ -> a later phase receives the relevant persisted artifacts as context
115
+ ```
116
+
117
+ The coordinator uses `api.sessions.create` and `api.sessions.run` for each phase. A malformed,
118
+ partial, turn-limited, or schema-invalid response is rejected before state advances. The child
119
+ session cannot write lifecycle state directly; even the implementer may modify only the assigned
120
+ workspace unit and must return evidence to the coordinator.
121
+
122
+ This artifact-mediated handoff keeps phases independently resumable. For example, the specifier
123
+ works from the approved proposal, the planner works from the specification and design, and the
124
+ verifier checks the implemented workspace against the persisted requirements. Agent definitions
125
+ also deny `task`, `delegate`, `subagent`, and `sessions_create`, so no phase can create a hidden
126
+ delegation chain.
127
+
128
+ ## Methodology diagrams
129
+
130
+ ![Wayfinder lifecycle, phase pipeline, and gates](./assets/methodology-flow.svg)
131
+
132
+ `methodology-flow.svg` maps the full lifecycle: user commands drive the deterministic
133
+ `WayfinderCoordinator`, which runs each phase in a fresh child session, persists every artifact
134
+ under `.alisio/wayfinder/changes/<change>/`, and enforces the proposal, plan, TDD, and mutation
135
+ gates together with the verification and mutation feedback loops.
136
+
137
+ ![One phase handoff between the coordinator and a child session](./assets/agent-communication.svg)
138
+
139
+ `agent-communication.svg` shows a single phase handoff: the coordinator loads one agent and its
140
+ mapped skills, creates a capability-narrowed child session, validates the one JSON result,
141
+ persists the Markdown artifact and `state.json`, and rejects malformed, partial, or turn-limited
142
+ output without advancing state.
143
+
144
+ The Mermaid sources live in `diagrams/wayfinder/` at the repository root and are rendered with
145
+ `pnpm diagrams`. The SVGs are generated output; never edit them by hand.
146
+
147
+ ## Lifecycle and gates
148
+
149
+ ```text
150
+ intent -> discovery -> proposal -> proposal approval -> specification -> design
151
+ -> plan -> plan approval -> one-unit implementation -> independent verification
152
+ -> archive readiness -> archive
153
+ ```
154
+
155
+ Advancement stops on critical questions, malformed or turn-limited output, incomplete plan or
156
+ verification coverage, missing implementation paths/check evidence, unfinished units, failed
157
+ verification, or incomplete archive inventory. Failed verification creates at most two resumable
158
+ remediation units. Implementation reports are context only; the verifier must inspect current files
159
+ and run focused commands independently. Wayfinder does not claim immutable Git provenance.
160
+
161
+ Passing verification no longer advances straight to archive: it exposes an explicit mutation-testing
162
+ decision gate. There is no implicit skip. In an interactive UI the coordinator asks one concise
163
+ question and persists the answer; headless use returns an actionable blocked status naming
164
+ `/wayfinder:mutate`. Verification that passes without a recorded decision cannot reach archive.
165
+
166
+ Proposal and plan approval are explicit. In an interactive UI, `next` asks one concise confirmation.
167
+ In headless use, it returns an actionable blocked status and requires `approve`; scope is never
168
+ silently accepted. Plan approval additionally requires a recorded test-first decision for changes
169
+ created by the current code; without it, the transition to implementation is blocked and
170
+ `/wayfinder:tdd` is named. A change already past plan approval from an earlier version is
171
+ grandfathered and is not retroactively gated (see the TDD section).
172
+
173
+ ## Mutation testing
174
+
175
+ Mutation testing is recommended, but the developer decides. The decision, mode, tool, stack, and
176
+ reason are persisted per change and are immutable.
177
+
178
+ | Topic | Behavior |
179
+ | --- | --- |
180
+ | Decision gate | `verify` cannot advance to archive until `/wayfinder:mutate <change> run\|skip -- <reason>` is recorded |
181
+ | `skip` | Verification passed → advance to archive. Verification pending → archive after it passes |
182
+ | `run` | Instructs `/wayfinder:verify`, which runs the bounded mutation check |
183
+ | Tooling | Only tooling already present in the project; never installed, never added as a dependency |
184
+ | Unavailable | Persists `unavailableReason` and advances to archive without blocking |
185
+ | Survivors | Only non-equivalent survivors fail; an equivalent survivor needs a written justification |
186
+ | Failure | Creates one `test-strengthening` unit for the affected requirements and survivor files |
187
+ | Targeted recovery | Re-runs mutation over the prior scope, then re-verifies only the affected requirement ids |
188
+ | Budget | Mutation remediation is separate and bounded to two attempts, then stops for human reassessment |
189
+
190
+ Bounds: changed-scope cap `20` files, reported-survivor cap `50`, child timeout `600000` ms, and the
191
+ concurrency bound `2` applied only where the tool supports it. Survivor text is never interpolated
192
+ into a command; the mutationist receives an argument list and never edits files.
193
+
194
+ Scope capability: some tools accept a bounded file scope, others can only mutate the whole
195
+ repository. A bounded (`--mode changed`) decision never silently expands to whole-repo.
196
+
197
+ | Tool | Bounded scope | Concurrency bound |
198
+ | --- | --- | --- |
199
+ | Stryker (JS/TS) | `--mutate` paths | applied (`--concurrency 2`) |
200
+ | `cargo-mutants` (Rust) | `--file` paths | applied (`--jobs 2`) |
201
+ | `gremlins` (Go) | positional package/path patterns | applied (`--workers 2`) |
202
+ | `go-mutesting` (Go) | positional patterns | not applied |
203
+ | `mutmut` (Python) | `--paths-to-mutate` | not applied |
204
+ | `cosmic-ray` (Python) | whole repository only | not applied |
205
+ | `pitest` (Java) | whole repository only | not applied |
206
+
207
+ For a whole-repository-only tool, a `changed`-mode run is refused rather than silently expanded;
208
+ re-run with `--mode full` to allow it explicitly. The refusal is non-blocking: the reason is
209
+ persisted and the change advances to archive.
210
+
211
+ Test-strengthening enforcement: a `test-strengthening` unit is accepted only when every reported
212
+ changed path is a test path (`test/`, `tests/`, or `__tests__/` segments, a bare `test`/`tests`/
213
+ `spec`/`specs` filename, or `.test.`, `.spec.`, `_test.`, `Test.`, `Spec.` filenames). A production
214
+ edit is rejected and the unit stays pending.
215
+
216
+ This guardrail applies only to the paths the implementing child reports and uses a filename/directory
217
+ heuristic, so a production file placed under a `test`-style directory or named `*Test.*`/`*Spec.*`
218
+ can pass it. The independent verifier still inspects the workspace, so this is a guardrail, not a
219
+ hard sandbox.
220
+
221
+ Detection uses the project's own manifests and lockfiles:
222
+
223
+ | Stack | Marker | Already-installed tools |
224
+ | --- | --- | --- |
225
+ | JavaScript/TypeScript | `package.json` | Stryker (`@stryker-mutator/*` or local binary/config) |
226
+ | Rust | `Cargo.toml` | `cargo-mutants` |
227
+ | Python | `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `tox.ini` | `mutmut`, `cosmic-ray` |
228
+ | Go | `go.mod` | `gremlins`, `go-mutesting` |
229
+ | Java | `pom.xml`, `build.gradle`, `build.gradle.kts` | `pitest` |
230
+
231
+ When nothing is detected, the coordinator recommends and continues without blocking.
232
+
233
+ ## Test-first (TDD)
234
+
235
+ TDD is recommended, but the developer decides. The decision is persisted per change, is immutable,
236
+ and gates plan approval. There is no implicit default.
237
+
238
+ | Topic | Behavior |
239
+ | --- | --- |
240
+ | Gate position | Approving the plan cannot transition to implementation until `/wayfinder:tdd <change> strict\|off -- <reason>` is recorded |
241
+ | Recommendation | `strict` when the plan has non-exempt units; `off` only when every unit is exempt |
242
+ | `off` | No test-first evidence is required for any unit |
243
+ | `strict` | Non-exempt units must provide test-first evidence (see below) |
244
+ | Exemption | A unit marked `tddExempt: true` must carry a non-blank `tddExemptReason` (whitespace-only is rejected); exemptions are irrelevant when the decision is `off` |
245
+ | Grandfathering | A change already past plan approval without a decision predates this gate and is not retroactively gated; every change created by the current code must record a decision at plan approval |
246
+ | Immutability | A second `/wayfinder:tdd` call is rejected |
247
+
248
+ Under `strict`, an implementation result for a non-exempt unit is rejected (the unit stays pending and
249
+ no state advances) unless it reports all of:
250
+
251
+ - at least one test path in `changedPaths`;
252
+ - a `testFirst` object with a failing run before the change and a passing run after;
253
+ - the failing and passing runs referencing the same test scope (identical command).
254
+
255
+ The rejection message names the required scope and the next command. Mutation-generated
256
+ `test-strengthening` units are already test-scoped, so they are exempt from the test-first evidence.
257
+
258
+ Enforcement is report-based and applies only to the paths and commands the implementing child
259
+ returns, using a filename/directory heuristic: a production file placed under a `test`-style directory
260
+ or named `*Test.*`/`*Spec.*` can pass, and a fabricated failing run is not independently detected.
261
+ The independent verifier still inspects the workspace and runs focused checks, so this is a guardrail,
262
+ not a sandbox.
263
+
264
+ Legacy grandfather policy: a change that reached implementation before this gate existed has no
265
+ recorded decision and is intentionally neither blocked nor retroactively gated; it proceeds through
266
+ implementation and verification without test-first enforcement. Every change created by the current
267
+ code must record a decision at plan approval. This policy is pinned by a test so it cannot drift.
268
+
269
+ ## Test design and UI testability
270
+
271
+ Two methodological rule sets ship in the `wayfinder-test-design` skill, which the planner,
272
+ implementer, and verifier load alongside their own skill:
273
+
274
+ - **Test case design.** Every functional scenario gets at least one happy-path (positive) test and
275
+ one unhappy-path (negative, error, boundary, or valid-alternative) test, derived from requirements
276
+ and use cases (functional black-box), combinable with white-box path coverage.
277
+ - **UI testability.** Query as a user would, in priority order: role/accessible name > label >
278
+ placeholder > visible text/display value > alt/title > `data-testid` last. Name ids
279
+ `feature-element-variant` (`login-email-input`); follow the project's existing test attribute and
280
+ id module; never anchor on implementation classes or deep DOM chains; keep ids out of business
281
+ logic; accessibility comes first.
282
+
283
+ Evidence contract:
284
+
285
+ | Field | Where | Meaning |
286
+ | --- | --- | --- |
287
+ | `requiresTests` | plan unit | Planner marks units that must carry tests |
288
+ | `testDesign` | implementation | `{ scenario, happy[], unhappy[] }` per functional scenario |
289
+ | `testability` | implementation | `{ testIds[], accessibleOnlyReason? }`, required when the unit changes UI paths |
290
+
291
+ The coordinator rejects a unit, keeping it pending, when a `requiresTests` unit omits `testDesign`,
292
+ when a scenario has no happy or no unhappy test, when scenario names are blank or duplicated, when a
293
+ declaring unit reports no test file, or when a UI change omits `testability`, uses non-convention ids,
294
+ or declares no ids without an `accessibleOnlyReason`.
295
+
296
+ UI detection is extension-based, but a UI-extension file that is a test path (for example
297
+ `src/App.test.tsx`) is treated as a test, not a UI path; a unit touching both `src/App.tsx` and
298
+ `src/App.test.tsx` still requires `testability`.
299
+
300
+ Enforcement is report-based and heuristic: a fragile selector, a missing negative test, or a
301
+ misleading scenario name cannot be fully proven from the returned report. The independent verifier
302
+ re-inspects the workspace and the tests, and remains the backstop.
303
+
304
+ ## Commands
305
+
306
+ | Command | Purpose |
307
+ | --- | --- |
308
+ | `/wayfinder:new <name> -- <intent>` | Create durable intent and state |
309
+ | `/wayfinder:status [name]` | List changes, or show detailed progress and the next action when a name is provided |
310
+ | `/wayfinder:answer <name> -- <text>` | Append clarification during discovery, proposal, or specification |
311
+ | `/wayfinder:next <name>` | Run exactly one analytical phase, or request a pending approval |
312
+ | `/wayfinder:approve <name> <proposal\|plan>` | Record explicit approval |
313
+ | `/wayfinder:tdd <name> <strict\|off> -- <reason>` | Record the immutable test-first decision before plan approval |
314
+ | `/wayfinder:mutate <name> <run\|skip> [--mode changed\|full] -- <reason>` | Record the immutable mutation-testing decision |
315
+ | `/wayfinder:build <name>` | Implement exactly one pending unit |
316
+ | `/wayfinder:verify <name>` | Independently verify every requirement exactly once |
317
+ | `/wayfinder:close <name>` | Validate readiness and move the change to archive |
318
+
319
+ Change names must contain 1–48 lowercase letters, digits, or hyphens and must start with a letter or
320
+ digit.
321
+
322
+ ## Persistence and recovery
323
+
324
+ Active changes use:
325
+
326
+ ```text
327
+ .alisio/wayfinder/changes/<change>/
328
+ ├── state.json
329
+ ├── intent.md
330
+ ├── clarifications.md # when needed
331
+ ├── discovery.md
332
+ ├── proposal.md
333
+ ├── specification.md
334
+ ├── design.md
335
+ ├── plan.md
336
+ ├── progress.md
337
+ ├── verification.md
338
+ ├── verification-targeted.md # after mutation remediation
339
+ ├── mutation.md # when a decision or run is recorded
340
+ └── archive-readiness.md
341
+ ```
342
+
343
+ Closed changes move to `.alisio/wayfinder/archive/YYYY-MM-DD-<change>/` and no longer appear in the
344
+ active change list. Individual files use temporary-file replacement with mode `0600`. Archive uses
345
+ a directory rename followed by a closed-state write with best-effort rollback if that write fails;
346
+ it is not a crash-proof multi-operation transaction.
347
+
348
+ Do not edit these files while commands are running. Wayfinder does not currently lock a change
349
+ against concurrent commands, so run only one Wayfinder command for a given change at a time.
350
+
351
+ Recovery rules:
352
+
353
+ - For malformed or turn-limited child output, retry the same phase after correcting the cause.
354
+ - For critical questions, run `answer` and then retry `next`.
355
+ - Run `build` repeatedly until every planned unit is complete.
356
+ - Failed verification may create up to two resumable remediation units.
357
+ - After the remediation limit is exhausted, the change remains in verification and requires human
358
+ reassessment rather than another automatic loop.
359
+ - Mutation testing requires an explicit `/wayfinder:mutate` decision before archive.
360
+ - Non-equivalent survivors create a `test-strengthening` unit; strengthen tests only, never change
361
+ production behavior to satisfy the tool.
362
+ - Mutation remediation has its own budget of two attempts, separate from verification remediation.
363
+
364
+ ## Requirements and capability boundaries
365
+
366
+ | Requirement | Value |
367
+ | --- | --- |
368
+ | Node.js | `>=22.16` |
369
+ | Alisio SDK peer | `>=0.1.0-alpha.9 <0.2.0` |
370
+ | Runtime dependencies | Node.js built-ins and `@alisio/sdk` only |
371
+
372
+ Child capabilities can only narrow the active parent session. The implementer needs parent write and
373
+ process capabilities; the verifier and mutationist need process capability. Without them, those
374
+ phases cannot complete.
375
+
376
+ ## Standalone behavior
377
+
378
+ The package imports only `@alisio/sdk` and Node built-ins; it never imports another plugin or
379
+ `@alisio/core`. It registers `../.agents/agents` and `../.agents/skills` for inspection and future
380
+ catalog interoperability. Current Alisio activation order can prevent newly registered external
381
+ agents from appearing in the built-in subagents catalog. Wayfinder therefore treats direct
382
+ `api.sessions.create/run` execution as primary and loads the same packaged resources itself.
383
+
384
+ Memory support is optional, fail-open, and read-only. If `memory_search` and `memory_get` survive
385
+ Alisio's parent-capability intersection, a child may use privacy-safe high-level context. Memory is
386
+ never lifecycle authority, required evidence, or a destination for source, secrets, prompts,
387
+ personal data, or absolute paths.
388
+
389
+ External plugins execute inside the Alisio process with the user's privileges. Agent permissions,
390
+ read-only profiles, and tool allowlists reduce model capabilities but are not an operating-system
391
+ sandbox. Review the package before loading it.
392
+
393
+ ## Links
394
+
395
+ - [Source](https://github.com/GustavoGutierrez/alisio-plugins/tree/main/packages/wayfinder)
396
+ - [Issues](https://github.com/GustavoGutierrez/alisio-plugins/issues)
@@ -0,0 +1 @@
1
+ <svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="max-width: 1593.5px; background-color: transparent;" viewBox="-50 -10 1593.5 914" role="graphics-document document" aria-roledescription="sequence"><g><rect x="1315.5" y="828" fill="#eaeaea" stroke="#666" width="178" height="65" name="Next" rx="3" ry="3" class="actor actor-bottom"/><text x="1404.5" y="860.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="1404.5" dy="0">Next phase child session</tspan></text></g><g><rect x="941.5" y="828" fill="#eaeaea" stroke="#666" width="324" height="65" name="Child" rx="3" ry="3" class="actor actor-bottom"/><text x="1103.5" y="860.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="1103.5" dy="0">Fresh child session (one agent + mapped skills)</tspan></text></g><g><rect x="624.5" y="828" fill="#eaeaea" stroke="#666" width="267" height="65" name="Store" rx="3" ry="3" class="actor actor-bottom"/><text x="758" y="860.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="758" dy="0">Artifact store (state.json + Markdown)</tspan></text></g><g><rect x="296.5" y="828" fill="#eaeaea" stroke="#666" width="237" height="65" name="Coord" rx="3" ry="3" class="actor actor-bottom"/><text x="415" y="860.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="415" dy="0">WayfinderCoordinator (authority)</tspan></text></g><g/><g><line id="actor4" x1="1404.5" y1="65" x2="1404.5" y2="828" class="actor-line 200" stroke-width="0.5px" stroke="#999" name="Next" data-et="life-line" data-id="Next"/><g id="root-4" data-et="participant" data-type="participant" data-id="Next"><rect x="1315.5" y="0" fill="#eaeaea" stroke="#666" width="178" height="65" name="Next" rx="3" ry="3" class="actor actor-top"/><text x="1404.5" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="1404.5" dy="0">Next phase child session</tspan></text></g></g><g><line id="actor3" x1="1103.5" y1="65" x2="1103.5" y2="828" class="actor-line 200" stroke-width="0.5px" stroke="#999" name="Child" data-et="life-line" data-id="Child"/><g id="root-3" data-et="participant" data-type="participant" data-id="Child"><rect x="941.5" y="0" fill="#eaeaea" stroke="#666" width="324" height="65" name="Child" rx="3" ry="3" class="actor actor-top"/><text x="1103.5" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="1103.5" dy="0">Fresh child session (one agent + mapped skills)</tspan></text></g></g><g><line id="actor2" x1="758" y1="65" x2="758" y2="828" class="actor-line 200" stroke-width="0.5px" stroke="#999" name="Store" data-et="life-line" data-id="Store"/><g id="root-2" data-et="participant" data-type="participant" data-id="Store"><rect x="624.5" y="0" fill="#eaeaea" stroke="#666" width="267" height="65" name="Store" rx="3" ry="3" class="actor actor-top"/><text x="758" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="758" dy="0">Artifact store (state.json + Markdown)</tspan></text></g></g><g><line id="actor1" x1="415" y1="65" x2="415" y2="828" class="actor-line 200" stroke-width="0.5px" stroke="#999" name="Coord" data-et="life-line" data-id="Coord"/><g id="root-1" data-et="participant" data-type="participant" data-id="Coord"><rect x="296.5" y="0" fill="#eaeaea" stroke="#666" width="237" height="65" name="Coord" rx="3" ry="3" class="actor actor-top"/><text x="415" y="32.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-box" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="415" dy="0">WayfinderCoordinator (authority)</tspan></text></g></g><g><line id="actor0" x1="75" y1="80" x2="75" y2="828" class="actor-line 200" stroke-width="0.5px" stroke="#999" name="User" data-et="life-line" data-id="User"/></g><style>#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#333333;stroke:#333333;}#my-svg .marker.cross{stroke:#333333;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .actor{stroke:#9370DB;fill:#ECECFF;stroke-width:1;}#my-svg rect.actor.outer-path[data-look="neo"]{filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg rect.note[data-look="neo"]{stroke:#aaaa33;fill:#fff5ad;filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg text.actor&gt;tspan{fill:black;stroke:none;}#my-svg .actor-line{stroke:#9370DB;}#my-svg .innerArc{stroke-width:1.5;stroke-dasharray:none;}#my-svg .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#my-svg .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#my-svg [id$="-arrowhead"] path{fill:#333;stroke:#333;}#my-svg .sequenceNumber{fill:white;}#my-svg [id$="-sequencenumber"]{fill:#333;}#my-svg [id$="-crosshead"] path{fill:#333;stroke:#333;}#my-svg .messageText{fill:#333;stroke:none;}#my-svg .labelBox{stroke:#9370DB;fill:#ECECFF;filter:none;}#my-svg .labelText,#my-svg .labelText&gt;tspan{fill:black;stroke:none;}#my-svg .loopText,#my-svg .loopText&gt;tspan{fill:black;stroke:none;}#my-svg .sectionTitle,#my-svg .sectionTitle&gt;tspan{fill:black;stroke:none;}#my-svg .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:#9370DB;fill:#9370DB;}#my-svg .note{stroke:#aaaa33;fill:#fff5ad;}#my-svg .noteText,#my-svg .noteText&gt;tspan{fill:black;stroke:none;}#my-svg .activation0{fill:#f4f4f4;stroke:#666;}#my-svg .activation1{fill:#f4f4f4;stroke:#666;}#my-svg .activation2{fill:#f4f4f4;stroke:#666;}#my-svg .actorPopupMenu{position:absolute;}#my-svg .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#my-svg .actor-man circle,#my-svg line{fill:#ECECFF;stroke-width:2px;}#my-svg g rect.rect{filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));stroke:#9370DB;}#my-svg .node .neo-node{stroke:#9370DB;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:#9370DB;filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg [data-look="neo"].swimlane.cluster rect{filter:none;}#my-svg [data-look="neo"].node path{stroke:#9370DB;stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#9370DB;filter:none;}#my-svg [data-look="neo"].node circle{stroke:#9370DB;filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:#9370DB;filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:#9370DB;filter:drop-shadow(1px 2px 2px rgba(185, 185, 185, 1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g/><defs><symbol id="my-svg-computer" width="24" height="24"><path transform="scale(.5)" d="M2 2v13h20v-13h-20zm18 11h-16v-9h16v9zm-10.228 6l.466-1h3.524l.467 1h-4.457zm14.228 3h-24l2-6h2.104l-1.33 4h18.45l-1.297-4h2.073l2 6zm-5-10h-14v-7h14v7z"/></symbol></defs><defs><symbol id="my-svg-database" fill-rule="evenodd" clip-rule="evenodd"><path transform="scale(.5)" d="M12.258.001l.256.004.255.005.253.008.251.01.249.012.247.015.246.016.242.019.241.02.239.023.236.024.233.027.231.028.229.031.225.032.223.034.22.036.217.038.214.04.211.041.208.043.205.045.201.046.198.048.194.05.191.051.187.053.183.054.18.056.175.057.172.059.168.06.163.061.16.063.155.064.15.066.074.033.073.033.071.034.07.034.069.035.068.035.067.035.066.035.064.036.064.036.062.036.06.036.06.037.058.037.058.037.055.038.055.038.053.038.052.038.051.039.05.039.048.039.047.039.045.04.044.04.043.04.041.04.04.041.039.041.037.041.036.041.034.041.033.042.032.042.03.042.029.042.027.042.026.043.024.043.023.043.021.043.02.043.018.044.017.043.015.044.013.044.012.044.011.045.009.044.007.045.006.045.004.045.002.045.001.045v17l-.001.045-.002.045-.004.045-.006.045-.007.045-.009.044-.011.045-.012.044-.013.044-.015.044-.017.043-.018.044-.02.043-.021.043-.023.043-.024.043-.026.043-.027.042-.029.042-.03.042-.032.042-.033.042-.034.041-.036.041-.037.041-.039.041-.04.041-.041.04-.043.04-.044.04-.045.04-.047.039-.048.039-.05.039-.051.039-.052.038-.053.038-.055.038-.055.038-.058.037-.058.037-.06.037-.06.036-.062.036-.064.036-.064.036-.066.035-.067.035-.068.035-.069.035-.07.034-.071.034-.073.033-.074.033-.15.066-.155.064-.16.063-.163.061-.168.06-.172.059-.175.057-.18.056-.183.054-.187.053-.191.051-.194.05-.198.048-.201.046-.205.045-.208.043-.211.041-.214.04-.217.038-.22.036-.223.034-.225.032-.229.031-.231.028-.233.027-.236.024-.239.023-.241.02-.242.019-.246.016-.247.015-.249.012-.251.01-.253.008-.255.005-.256.004-.258.001-.258-.001-.256-.004-.255-.005-.253-.008-.251-.01-.249-.012-.247-.015-.245-.016-.243-.019-.241-.02-.238-.023-.236-.024-.234-.027-.231-.028-.228-.031-.226-.032-.223-.034-.22-.036-.217-.038-.214-.04-.211-.041-.208-.043-.204-.045-.201-.046-.198-.048-.195-.05-.19-.051-.187-.053-.184-.054-.179-.056-.176-.057-.172-.059-.167-.06-.164-.061-.159-.063-.155-.064-.151-.066-.074-.033-.072-.033-.072-.034-.07-.034-.069-.035-.068-.035-.067-.035-.066-.035-.064-.036-.063-.036-.062-.036-.061-.036-.06-.037-.058-.037-.057-.037-.056-.038-.055-.038-.053-.038-.052-.038-.051-.039-.049-.039-.049-.039-.046-.039-.046-.04-.044-.04-.043-.04-.041-.04-.04-.041-.039-.041-.037-.041-.036-.041-.034-.041-.033-.042-.032-.042-.03-.042-.029-.042-.027-.042-.026-.043-.024-.043-.023-.043-.021-.043-.02-.043-.018-.044-.017-.043-.015-.044-.013-.044-.012-.044-.011-.045-.009-.044-.007-.045-.006-.045-.004-.045-.002-.045-.001-.045v-17l.001-.045.002-.045.004-.045.006-.045.007-.045.009-.044.011-.045.012-.044.013-.044.015-.044.017-.043.018-.044.02-.043.021-.043.023-.043.024-.043.026-.043.027-.042.029-.042.03-.042.032-.042.033-.042.034-.041.036-.041.037-.041.039-.041.04-.041.041-.04.043-.04.044-.04.046-.04.046-.039.049-.039.049-.039.051-.039.052-.038.053-.038.055-.038.056-.038.057-.037.058-.037.06-.037.061-.036.062-.036.063-.036.064-.036.066-.035.067-.035.068-.035.069-.035.07-.034.072-.034.072-.033.074-.033.151-.066.155-.064.159-.063.164-.061.167-.06.172-.059.176-.057.179-.056.184-.054.187-.053.19-.051.195-.05.198-.048.201-.046.204-.045.208-.043.211-.041.214-.04.217-.038.22-.036.223-.034.226-.032.228-.031.231-.028.234-.027.236-.024.238-.023.241-.02.243-.019.245-.016.247-.015.249-.012.251-.01.253-.008.255-.005.256-.004.258-.001.258.001zm-9.258 20.499v.01l.001.021.003.021.004.022.005.021.006.022.007.022.009.023.01.022.011.023.012.023.013.023.015.023.016.024.017.023.018.024.019.024.021.024.022.025.023.024.024.025.052.049.056.05.061.051.066.051.07.051.075.051.079.052.084.052.088.052.092.052.097.052.102.051.105.052.11.052.114.051.119.051.123.051.127.05.131.05.135.05.139.048.144.049.147.047.152.047.155.047.16.045.163.045.167.043.171.043.176.041.178.041.183.039.187.039.19.037.194.035.197.035.202.033.204.031.209.03.212.029.216.027.219.025.222.024.226.021.23.02.233.018.236.016.24.015.243.012.246.01.249.008.253.005.256.004.259.001.26-.001.257-.004.254-.005.25-.008.247-.011.244-.012.241-.014.237-.016.233-.018.231-.021.226-.021.224-.024.22-.026.216-.027.212-.028.21-.031.205-.031.202-.034.198-.034.194-.036.191-.037.187-.039.183-.04.179-.04.175-.042.172-.043.168-.044.163-.045.16-.046.155-.046.152-.047.148-.048.143-.049.139-.049.136-.05.131-.05.126-.05.123-.051.118-.052.114-.051.11-.052.106-.052.101-.052.096-.052.092-.052.088-.053.083-.051.079-.052.074-.052.07-.051.065-.051.06-.051.056-.05.051-.05.023-.024.023-.025.021-.024.02-.024.019-.024.018-.024.017-.024.015-.023.014-.024.013-.023.012-.023.01-.023.01-.022.008-.022.006-.022.006-.022.004-.022.004-.021.001-.021.001-.021v-4.127l-.077.055-.08.053-.083.054-.085.053-.087.052-.09.052-.093.051-.095.05-.097.05-.1.049-.102.049-.105.048-.106.047-.109.047-.111.046-.114.045-.115.045-.118.044-.12.043-.122.042-.124.042-.126.041-.128.04-.13.04-.132.038-.134.038-.135.037-.138.037-.139.035-.142.035-.143.034-.144.033-.147.032-.148.031-.15.03-.151.03-.153.029-.154.027-.156.027-.158.026-.159.025-.161.024-.162.023-.163.022-.165.021-.166.02-.167.019-.169.018-.169.017-.171.016-.173.015-.173.014-.175.013-.175.012-.177.011-.178.01-.179.008-.179.008-.181.006-.182.005-.182.004-.184.003-.184.002h-.37l-.184-.002-.184-.003-.182-.004-.182-.005-.181-.006-.179-.008-.179-.008-.178-.01-.176-.011-.176-.012-.175-.013-.173-.014-.172-.015-.171-.016-.17-.017-.169-.018-.167-.019-.166-.02-.165-.021-.163-.022-.162-.023-.161-.024-.159-.025-.157-.026-.156-.027-.155-.027-.153-.029-.151-.03-.15-.03-.148-.031-.146-.032-.145-.033-.143-.034-.141-.035-.14-.035-.137-.037-.136-.037-.134-.038-.132-.038-.13-.04-.128-.04-.126-.041-.124-.042-.122-.042-.12-.044-.117-.043-.116-.045-.113-.045-.112-.046-.109-.047-.106-.047-.105-.048-.102-.049-.1-.049-.097-.05-.095-.05-.093-.052-.09-.051-.087-.052-.085-.053-.083-.054-.08-.054-.077-.054v4.127zm0-5.654v.011l.001.021.003.021.004.021.005.022.006.022.007.022.009.022.01.022.011.023.012.023.013.023.015.024.016.023.017.024.018.024.019.024.021.024.022.024.023.025.024.024.052.05.056.05.061.05.066.051.07.051.075.052.079.051.084.052.088.052.092.052.097.052.102.052.105.052.11.051.114.051.119.052.123.05.127.051.131.05.135.049.139.049.144.048.147.048.152.047.155.046.16.045.163.045.167.044.171.042.176.042.178.04.183.04.187.038.19.037.194.036.197.034.202.033.204.032.209.03.212.028.216.027.219.025.222.024.226.022.23.02.233.018.236.016.24.014.243.012.246.01.249.008.253.006.256.003.259.001.26-.001.257-.003.254-.006.25-.008.247-.01.244-.012.241-.015.237-.016.233-.018.231-.02.226-.022.224-.024.22-.025.216-.027.212-.029.21-.03.205-.032.202-.033.198-.035.194-.036.191-.037.187-.039.183-.039.179-.041.175-.042.172-.043.168-.044.163-.045.16-.045.155-.047.152-.047.148-.048.143-.048.139-.05.136-.049.131-.05.126-.051.123-.051.118-.051.114-.052.11-.052.106-.052.101-.052.096-.052.092-.052.088-.052.083-.052.079-.052.074-.051.07-.052.065-.051.06-.05.056-.051.051-.049.023-.025.023-.024.021-.025.02-.024.019-.024.018-.024.017-.024.015-.023.014-.023.013-.024.012-.022.01-.023.01-.023.008-.022.006-.022.006-.022.004-.021.004-.022.001-.021.001-.021v-4.139l-.077.054-.08.054-.083.054-.085.052-.087.053-.09.051-.093.051-.095.051-.097.05-.1.049-.102.049-.105.048-.106.047-.109.047-.111.046-.114.045-.115.044-.118.044-.12.044-.122.042-.124.042-.126.041-.128.04-.13.039-.132.039-.134.038-.135.037-.138.036-.139.036-.142.035-.143.033-.144.033-.147.033-.148.031-.15.03-.151.03-.153.028-.154.028-.156.027-.158.026-.159.025-.161.024-.162.023-.163.022-.165.021-.166.02-.167.019-.169.018-.169.017-.171.016-.173.015-.173.014-.175.013-.175.012-.177.011-.178.009-.179.009-.179.007-.181.007-.182.005-.182.004-.184.003-.184.002h-.37l-.184-.002-.184-.003-.182-.004-.182-.005-.181-.007-.179-.007-.179-.009-.178-.009-.176-.011-.176-.012-.175-.013-.173-.014-.172-.015-.171-.016-.17-.017-.169-.018-.167-.019-.166-.02-.165-.021-.163-.022-.162-.023-.161-.024-.159-.025-.157-.026-.156-.027-.155-.028-.153-.028-.151-.03-.15-.03-.148-.031-.146-.033-.145-.033-.143-.033-.141-.035-.14-.036-.137-.036-.136-.037-.134-.038-.132-.039-.13-.039-.128-.04-.126-.041-.124-.042-.122-.043-.12-.043-.117-.044-.116-.044-.113-.046-.112-.046-.109-.046-.106-.047-.105-.048-.102-.049-.1-.049-.097-.05-.095-.051-.093-.051-.09-.051-.087-.053-.085-.052-.083-.054-.08-.054-.077-.054v4.139zm0-5.666v.011l.001.02.003.022.004.021.005.022.006.021.007.022.009.023.01.022.011.023.012.023.013.023.015.023.016.024.017.024.018.023.019.024.021.025.022.024.023.024.024.025.052.05.056.05.061.05.066.051.07.051.075.052.079.051.084.052.088.052.092.052.097.052.102.052.105.051.11.052.114.051.119.051.123.051.127.05.131.05.135.05.139.049.144.048.147.048.152.047.155.046.16.045.163.045.167.043.171.043.176.042.178.04.183.04.187.038.19.037.194.036.197.034.202.033.204.032.209.03.212.028.216.027.219.025.222.024.226.021.23.02.233.018.236.017.24.014.243.012.246.01.249.008.253.006.256.003.259.001.26-.001.257-.003.254-.006.25-.008.247-.01.244-.013.241-.014.237-.016.233-.018.231-.02.226-.022.224-.024.22-.025.216-.027.212-.029.21-.03.205-.032.202-.033.198-.035.194-.036.191-.037.187-.039.183-.039.179-.041.175-.042.172-.043.168-.044.163-.045.16-.045.155-.047.152-.047.148-.048.143-.049.139-.049.136-.049.131-.051.126-.05.123-.051.118-.052.114-.051.11-.052.106-.052.101-.052.096-.052.092-.052.088-.052.083-.052.079-.052.074-.052.07-.051.065-.051.06-.051.056-.05.051-.049.023-.025.023-.025.021-.024.02-.024.019-.024.018-.024.017-.024.015-.023.014-.024.013-.023.012-.023.01-.022.01-.023.008-.022.006-.022.006-.022.004-.022.004-.021.001-.021.001-.021v-4.153l-.077.054-.08.054-.083.053-.085.053-.087.053-.09.051-.093.051-.095.051-.097.05-.1.049-.102.048-.105.048-.106.048-.109.046-.111.046-.114.046-.115.044-.118.044-.12.043-.122.043-.124.042-.126.041-.128.04-.13.039-.132.039-.134.038-.135.037-.138.036-.139.036-.142.034-.143.034-.144.033-.147.032-.148.032-.15.03-.151.03-.153.028-.154.028-.156.027-.158.026-.159.024-.161.024-.162.023-.163.023-.165.021-.166.02-.167.019-.169.018-.169.017-.171.016-.173.015-.173.014-.175.013-.175.012-.177.01-.178.01-.179.009-.179.007-.181.006-.182.006-.182.004-.184.003-.184.001-.185.001-.185-.001-.184-.001-.184-.003-.182-.004-.182-.006-.181-.006-.179-.007-.179-.009-.178-.01-.176-.01-.176-.012-.175-.013-.173-.014-.172-.015-.171-.016-.17-.017-.169-.018-.167-.019-.166-.02-.165-.021-.163-.023-.162-.023-.161-.024-.159-.024-.157-.026-.156-.027-.155-.028-.153-.028-.151-.03-.15-.03-.148-.032-.146-.032-.145-.033-.143-.034-.141-.034-.14-.036-.137-.036-.136-.037-.134-.038-.132-.039-.13-.039-.128-.041-.126-.041-.124-.041-.122-.043-.12-.043-.117-.044-.116-.044-.113-.046-.112-.046-.109-.046-.106-.048-.105-.048-.102-.048-.1-.05-.097-.049-.095-.051-.093-.051-.09-.052-.087-.052-.085-.053-.083-.053-.08-.054-.077-.054v4.153zm8.74-8.179l-.257.004-.254.005-.25.008-.247.011-.244.012-.241.014-.237.016-.233.018-.231.021-.226.022-.224.023-.22.026-.216.027-.212.028-.21.031-.205.032-.202.033-.198.034-.194.036-.191.038-.187.038-.183.04-.179.041-.175.042-.172.043-.168.043-.163.045-.16.046-.155.046-.152.048-.148.048-.143.048-.139.049-.136.05-.131.05-.126.051-.123.051-.118.051-.114.052-.11.052-.106.052-.101.052-.096.052-.092.052-.088.052-.083.052-.079.052-.074.051-.07.052-.065.051-.06.05-.056.05-.051.05-.023.025-.023.024-.021.024-.02.025-.019.024-.018.024-.017.023-.015.024-.014.023-.013.023-.012.023-.01.023-.01.022-.008.022-.006.023-.006.021-.004.022-.004.021-.001.021-.001.021.001.021.001.021.004.021.004.022.006.021.006.023.008.022.01.022.01.023.012.023.013.023.014.023.015.024.017.023.018.024.019.024.02.025.021.024.023.024.023.025.051.05.056.05.06.05.065.051.07.052.074.051.079.052.083.052.088.052.092.052.096.052.101.052.106.052.11.052.114.052.118.051.123.051.126.051.131.05.136.05.139.049.143.048.148.048.152.048.155.046.16.046.163.045.168.043.172.043.175.042.179.041.183.04.187.038.191.038.194.036.198.034.202.033.205.032.21.031.212.028.216.027.22.026.224.023.226.022.231.021.233.018.237.016.241.014.244.012.247.011.25.008.254.005.257.004.26.001.26-.001.257-.004.254-.005.25-.008.247-.011.244-.012.241-.014.237-.016.233-.018.231-.021.226-.022.224-.023.22-.026.216-.027.212-.028.21-.031.205-.032.202-.033.198-.034.194-.036.191-.038.187-.038.183-.04.179-.041.175-.042.172-.043.168-.043.163-.045.16-.046.155-.046.152-.048.148-.048.143-.048.139-.049.136-.05.131-.05.126-.051.123-.051.118-.051.114-.052.11-.052.106-.052.101-.052.096-.052.092-.052.088-.052.083-.052.079-.052.074-.051.07-.052.065-.051.06-.05.056-.05.051-.05.023-.025.023-.024.021-.024.02-.025.019-.024.018-.024.017-.023.015-.024.014-.023.013-.023.012-.023.01-.023.01-.022.008-.022.006-.023.006-.021.004-.022.004-.021.001-.021.001-.021-.001-.021-.001-.021-.004-.021-.004-.022-.006-.021-.006-.023-.008-.022-.01-.022-.01-.023-.012-.023-.013-.023-.014-.023-.015-.024-.017-.023-.018-.024-.019-.024-.02-.025-.021-.024-.023-.024-.023-.025-.051-.05-.056-.05-.06-.05-.065-.051-.07-.052-.074-.051-.079-.052-.083-.052-.088-.052-.092-.052-.096-.052-.101-.052-.106-.052-.11-.052-.114-.052-.118-.051-.123-.051-.126-.051-.131-.05-.136-.05-.139-.049-.143-.048-.148-.048-.152-.048-.155-.046-.16-.046-.163-.045-.168-.043-.172-.043-.175-.042-.179-.041-.183-.04-.187-.038-.191-.038-.194-.036-.198-.034-.202-.033-.205-.032-.21-.031-.212-.028-.216-.027-.22-.026-.224-.023-.226-.022-.231-.021-.233-.018-.237-.016-.241-.014-.244-.012-.247-.011-.25-.008-.254-.005-.257-.004-.26-.001-.26.001z"/></symbol></defs><defs><symbol id="my-svg-clock" width="24" height="24"><path transform="scale(.5)" d="M12 2c5.514 0 10 4.486 10 10s-4.486 10-10 10-10-4.486-10-10 4.486-10 10-10zm0-2c-6.627 0-12 5.373-12 12s5.373 12 12 12 12-5.373 12-12-5.373-12-12-12zm5.848 12.459c.202.038.202.333.001.372-1.907.361-6.045 1.111-6.547 1.111-.719 0-1.301-.582-1.301-1.301 0-.512.77-5.447 1.125-7.445.034-.192.312-.181.343.014l.985 6.238 5.394 1.011z"/></symbol></defs><defs><marker id="my-svg-arrowhead" refX="7.9" refY="5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto-start-reverse"><path d="M -1 0 L 10 5 L 0 10 z"/></marker></defs><defs><marker id="my-svg-crosshead" markerWidth="15" markerHeight="8" orient="auto" refX="4" refY="4.5"><path fill="none" stroke="#000000" stroke-width="1pt" d="M 1,2 L 6,7 M 6,2 L 1,7" style="stroke-dasharray: 0, 0;"/></marker></defs><defs><marker id="my-svg-filled-head" refX="15.5" refY="7" markerWidth="20" markerHeight="28" orient="auto"><path d="M 18,7 L9,13 L14,7 L9,1 Z"/></marker></defs><defs><marker id="my-svg-sequencenumber" refX="15" refY="15" markerWidth="60" markerHeight="40" orient="auto"><circle cx="15" cy="15" r="6"/></marker></defs><defs><marker id="my-svg-solidTopArrowHead" refX="7.9" refY="7.25" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto-start-reverse"><path d="M 0 0 L 10 8 L 0 8 z"/></marker></defs><defs><marker id="my-svg-solidBottomArrowHead" refX="7.9" refY="0.75" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto-start-reverse"><path d="M 0 0 L 10 0 L 0 8 z"/></marker></defs><defs><marker id="my-svg-stickTopArrowHead" refX="7.5" refY="7" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto-start-reverse"><path d="M 0 0 L 7 7" stroke="black" stroke-width="1.5" fill="none"/></marker></defs><defs><marker id="my-svg-stickBottomArrowHead" refX="7.5" refY="0" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto-start-reverse"><path d="M 0 7 L 7 0" stroke="black" stroke-width="1.5" fill="none"/></marker></defs><g data-et="note" data-id="i4"><rect x="941.5" y="243" fill="#EDF2AE" stroke="#666" width="324" height="37" class="note"/><text x="1104" y="248" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="noteText" dy="1em" style="font-size: 16px; font-weight: 400;"><tspan x="1104">one phase, one result schema, no delegation</tspan></text></g><g data-et="control-structure" data-id="i15"><line x1="64" y1="336" x2="1415.5" y2="336" class="loopLine"/><line x1="1415.5" y1="336" x2="1415.5" y2="808" class="loopLine"/><line x1="64" y1="808" x2="1415.5" y2="808" class="loopLine"/><line x1="64" y1="336" x2="64" y2="808" class="loopLine"/><line x1="64" y1="646" x2="1415.5" y2="646" class="loopLine" style="stroke-dasharray: 3, 3;"/><polygon points="64,336 114,336 114,349 105.6,356 64,356" class="labelBox"/><text x="89" y="349" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="labelText" style="font-size: 16px; font-weight: 400;">alt</text><text x="764.75" y="354" text-anchor="middle" class="loopText" style="font-size: 16px; font-weight: 400;"><tspan x="764.75">[Valid and complete result]</tspan></text><text x="739.75" y="664" text-anchor="middle" class="sectionTitle" style="font-size: 16px; font-weight: 400;">[Malformed, partial, or turn-limited]</text></g><g class="actor-man actor-top" name="User" data-et="participant" data-type="actor" data-id="User" style="stroke: rgb(147, 112, 219);"><line id="actor-man-torso0" x1="75" y1="25" x2="75" y2="45"/><line id="actor-man-arms0" x1="57" y1="33" x2="93" y2="33"/><line x1="57" y1="60" x2="75" y2="45"/><line x1="75" y1="45" x2="91" y2="60"/><circle cx="75" cy="10" r="15" width="150" height="65"/><text x="75" y="67.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-man" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="75" dy="0">User</tspan></text></g><text x="244" y="80" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">/wayfinder:next [change]</text><line x1="82" y1="111" x2="411" y2="111" class="messageLine0" data-et="message" data-id="i1" data-from="User" data-to="Coord" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="fill: none;"/><line x1="75" y1="111" x2="75" y2="111" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="75" y="115" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">1</text><text x="416" y="126" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">load agent definition and every mapped skill</text><path d="M 416,157 C 476,147 476,187 416,177" class="messageLine0" data-et="message" data-id="i2" data-from="Coord" data-to="Coord" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" x1="422" style="fill: none;"/><line x1="415" y1="157" x2="415" y2="157" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="161" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">2</text><text x="758" y="202" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">create capability-narrowed session</text><line x1="422" y1="233" x2="1099.5" y2="233" class="messageLine0" data-et="message" data-id="i3" data-from="Coord" data-to="Child" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="fill: none;"/><line x1="415" y1="233" x2="415" y2="233" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="237" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">3</text><text x="761" y="295" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">one phase-specific JSON result</text><line x1="1108.5" y1="326" x2="419" y2="326" class="messageLine1" data-et="message" data-id="i5" data-from="Child" data-to="Coord" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="stroke-dasharray: 3, 3; fill: none;"/><line x1="1103.5" y1="326" x2="1103.5" y2="326" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="1103.5" y="330" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">4</text><text x="416" y="386" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">validate against the phase schema</text><path d="M 416,417 C 476,407 476,447 416,437" class="messageLine0" data-et="message" data-id="i7" data-from="Coord" data-to="Coord" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" x1="422" style="fill: none;"/><line x1="415" y1="417" x2="415" y2="417" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="421" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">5</text><text x="585" y="462" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">render Markdown artifact (atomic replace)</text><line x1="422" y1="493" x2="754" y2="493" class="messageLine0" data-et="message" data-id="i8" data-from="Coord" data-to="Store" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="fill: none;"/><line x1="415" y1="493" x2="415" y2="493" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="497" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">6</text><text x="585" y="508" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">update state.json (atomic replace)</text><line x1="422" y1="539" x2="754" y2="539" class="messageLine0" data-et="message" data-id="i9" data-from="Coord" data-to="Store" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="fill: none;"/><line x1="415" y1="539" x2="415" y2="539" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="543" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">7</text><text x="247" y="554" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">phase complete, next action</text><line x1="420" y1="585" x2="79" y2="585" class="messageLine1" data-et="message" data-id="i10" data-from="Coord" data-to="User" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="stroke-dasharray: 3, 3; fill: none;"/><line x1="415" y1="585" x2="415" y2="585" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="589" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">8</text><text x="1080" y="600" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">persisted artifacts as phase context</text><line x1="765" y1="631" x2="1400.5" y2="631" class="messageLine1" data-et="message" data-id="i11" data-from="Store" data-to="Next" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="stroke-dasharray: 3, 3; fill: none;"/><line x1="758" y1="631" x2="758" y2="631" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="758" y="635" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">9</text><text x="416" y="691" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">reject and keep state unchanged</text><path d="M 416,722 C 476,712 476,752 416,742" class="messageLine0" data-et="message" data-id="i13" data-from="Coord" data-to="Coord" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" x1="422" style="fill: none;"/><line x1="415" y1="722" x2="415" y2="722" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="726" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">10</text><text x="247" y="767" text-anchor="middle" dominant-baseline="middle" alignment-baseline="middle" class="messageText" dy="1em" style="font-size: 16px; font-weight: 400;">retry the same phase after fixing the cause</text><line x1="420" y1="798" x2="79" y2="798" class="messageLine1" data-et="message" data-id="i14" data-from="Coord" data-to="User" stroke-width="2" stroke="none" marker-end="url(#my-svg-arrowhead)" style="stroke-dasharray: 3, 3; fill: none;"/><line x1="415" y1="798" x2="415" y2="798" stroke-width="0" marker-start="url(#my-svg-sequencenumber)"/><text x="415" y="802" font-family="sans-serif" font-size="12px" text-anchor="middle" class="sequenceNumber">11</text><g class="actor-man actor-bottom" name="User" style="stroke: rgb(147, 112, 219);"><line id="actor-man-torso4" x1="75" y1="853" x2="75" y2="873"/><line id="actor-man-arms4" x1="57" y1="861" x2="93" y2="861"/><line x1="57" y1="888" x2="75" y2="873"/><line x1="75" y1="873" x2="91" y2="888"/><circle cx="75" cy="838" r="15" width="150" height="65"/><text x="75" y="895.5" dominant-baseline="central" alignment-baseline="central" class="actor actor-man" style="text-anchor: middle; font-size: 16px; font-weight: 400;"><tspan x="75" dy="0">User</tspan></text></g></svg>