@alphazede/bearing-lite 0.1.0 → 0.1.8

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 (34) hide show
  1. package/README.md +97 -67
  2. package/hooks/activation.cjs +2 -1
  3. package/hooks/com.anthropic.claude-code/host.cjs +437 -0
  4. package/hooks/com.anthropic.claude-code/mapping.md +69 -0
  5. package/hooks/com.cursor/hooks.json +15 -0
  6. package/hooks/hooks.json +35 -0
  7. package/package.json +7 -4
  8. package/plugin.json +34 -2
  9. package/skills/bearing-lite/SKILL.md +43 -36
  10. package/skills/bearing-lite/agents/openai.yaml +7 -0
  11. package/skills/bearing-lite/references/peer-synthesis.md +19 -0
  12. package/skills/bearing-lite/references/role-routing.mmd +19 -32
  13. package/skills/bearing-lite/references/task-state.md +19 -1
  14. package/skills/bearing-lite/references/task-state.mmd +1 -1
  15. package/skills/bearing-lite/templates/default-role-lineup.md +24 -0
  16. package/skills/bearing-lite/templates/task.md +56 -0
  17. package/skills/crewmate/SKILL.md +42 -30
  18. package/skills/explorer/SKILL.md +50 -31
  19. package/skills/gather-supplies/SKILL.md +46 -26
  20. package/skills/map-the-route/SKILL.md +39 -26
  21. package/skills/map-the-route/references/artifact-grammar.md +10 -10
  22. package/skills/navigator/SKILL.md +51 -37
  23. package/skills/park-ranger/SKILL.md +29 -24
  24. package/skills/repository-fit/SKILL.md +26 -19
  25. package/skills/set-bearings/SKILL.md +25 -19
  26. package/skills/surveyor/SKILL.md +26 -24
  27. package/skills/validator/SKILL.md +28 -27
  28. package/guide/migration.md +0 -168
  29. package/skills/bearing-lite/assets/role-routing.png +0 -0
  30. package/skills/bearing-lite/assets/task-state.png +0 -0
  31. package/skills/delegate-authority/SKILL.md +0 -38
  32. package/skills/sub-explorer/SKILL.md +0 -37
  33. package/skills/trail-boss/SKILL.md +0 -38
  34. package/skills/trail-boss/agents/openai.yaml +0 -4
@@ -1,33 +1,46 @@
1
1
  ---
2
2
  name: map-the-route
3
3
  description: >
4
- Build the human-readable task graph when the outcome is approved but
5
- executable tasks are missing. Use for map the route, implementation slices,
6
- task graph, SEIT, or planning artifacts. Do not use to execute work, select
7
- models, self-certify assurance, or advance journey state beyond planning.
4
+ Create or resume Bearing's topic-specific specification, design, SEIT,
5
+ implementation graph, and self-contained review HTML after decisions are
6
+ resolved. Use for Map the Route or missing planning artifacts. Do not use to
7
+ implement, select agents/models, self-approve, or bypass owner review.
8
8
  ---
9
9
 
10
10
  # Map the Route
11
11
 
12
- Procedural stage. Not a persona.
13
-
14
- ## Match / non-match
15
-
16
- - **Match:** plan-spec/decisions are approved and executable task graph or planning package is incomplete.
17
- - **Non-match:** tasks already READY with roles and assurance; pure Crewmate packet work.
18
-
19
- ## Inputs
20
-
21
- Approved goal, decisions, plan-spec, and required Role routes.
22
-
23
- ## Procedure
24
-
25
- 1. Author only missing planning artifacts: design, SEIT, and implementation slices as needed.
26
- 2. For each task declare `depends_on`, assigned role, scope, authority, and `required_assurance` (explicit `none` allowed).
27
- 3. Prefer the smallest valid route; leave dormant roles unselected.
28
- 4. Keep IDs stable; cite acceptance and evidence expectations per task.
29
- 5. Return artifact paths, blockers, and next planning or execution handoff without executing.
30
-
31
- ## Never
32
-
33
- Implement product changes, invent owner approval, run phase gates as automatic, or claim independent assurance.
12
+ Fresh planning node. The Router remains the plan-state writer and user contact.
13
+
14
+ ## Inputs and match
15
+
16
+ - **Inputs:** confirmed decisions, repository map, artifact status, requirements,
17
+ owner-selected route/lineup/cadence, repository rules, and return schema.
18
+ - **Match:** first specification gate or post-approval planning package is missing.
19
+ - **Non-match:** executable tasks already map to current approved artifacts.
20
+
21
+ ## Algorithm
22
+
23
+ 1. Derive and announce `<journey-topic>-spec.md` from the confirmed title;
24
+ require owner input only on ambiguity or collision. Never require generic
25
+ `plan-spec.md`.
26
+ 2. Author in dependency order: testable specification, `design.md`, `seit.md`,
27
+ then `implementation.md`. Run prospective checks internally; interrupt the
28
+ owner only when evidence creates a material intent, scope, risk, or authority
29
+ decision.
30
+ 3. Generate one complete self-contained offline `review.html` after all four
31
+ artifacts are current. Include implementation, traceability, roles, waves,
32
+ failure/recovery paths, and approval boundaries in that review.
33
+ 4. Give every slice stable requirement/design/SEIT IDs, dependencies, exact
34
+ write set, authority, fresh-session role, evidence, recovery, and stop rule.
35
+ 5. Copy the confirmed route, lineup, and review cadence into implementation and
36
+ HTML. Show named active, standby, and unused role instances.
37
+ 6. Open the exact final HTML, verify its launcher/process, and request one
38
+ integrated owner approval. Use staged owner approvals only when the owner
39
+ explicitly requests them.
40
+
41
+ ## Return and recovery
42
+
43
+ Return `PLAN_REVIEW_READY`, `NEEDS_OWNER_DECISION`, or `VALIDATION_FAILED` with
44
+ artifact paths, evidence, blocker, and next action. After approval,
45
+ `review.html` is authoritative. At most three evidence-changing correction
46
+ rounds; never invent approval or implement.
@@ -10,13 +10,13 @@ Bearing rejects deviations with typed findings.
10
10
  2. Requirement IDs use `AC-*` or `RISK-*`; design IDs use `DES-*` or
11
11
  `CONTRACT-*`; SEIT rows use `SEIT-*`; commands use `CMD-*` or `PROC-*`.
12
12
  Suffixes contain only uppercase letters, digits, dots, or hyphens.
13
- 3. `plan-spec.md` declares requirements, Entry criteria, Exit criteria,
13
+ 3. `<journey-topic>-spec.md` declares requirements, Entry criteria, Exit criteria,
14
14
  Rollback or repair, and Accountable controller. `design.md` declares design
15
15
  IDs. `seit.md` declares SEIT rows and commands.
16
16
  4. Preserve stable IDs. Every implementation reference resolves to a declared
17
17
  requirement, design contract, SEIT row, and command.
18
- 5. The plan's Role routes decision supplies immutable `authorRoute` and
19
- `reviewSlots`. Missing or incomplete routes block implementation drafting.
18
+ 5. The owner-confirmed lineup and review cadence supply named active, standby,
19
+ and unused instances. Missing values block implementation drafting.
20
20
 
21
21
  ## SEIT rules
22
22
 
@@ -38,8 +38,8 @@ Bearing rejects deviations with typed findings.
38
38
  `### <id> execution manifest`. IDs are a letter-run plus an integer or
39
39
  dotted integer. Every slice has exactly one matching manifest.
40
40
  2. Every slice declares Goal, Requirement IDs, Design IDs, SEIT proof rows,
41
- Type, Design lenses, Implementation role, Agent model route, Agent reasoning
42
- level, and Review path. Goals are at most 512 characters.
41
+ Type, Design lenses, named implementation role, owner-selected model route,
42
+ reasoning level, and review path. Goals are at most 512 characters.
43
43
  3. Every manifest declares Write set, Command IDs, Stop condition, and Human
44
44
  decision. Optional fields are Shared interfaces (`path#Symbol`), Integration
45
45
  boundary, and Parallel safe (`yes` or `no` plus reason).
@@ -76,8 +76,8 @@ placeholders, bare negations, or deferral language.
76
76
 
77
77
  ## Completion boundary
78
78
 
79
- Design-only work returns after valid `design.md` and `seit.md`. Implementation
80
- drafting returns after valid `implementation.md`. Complete-route work remains
81
- incomplete until `plan-spec.md`, `design.md`, `seit.md`, and `implementation.md`
82
- are current. Bearing then generates the complete `review.html`; agents never
83
- hand-edit, summarize, or replace it.
79
+ Author specification, design, SEIT, and implementation in that dependency order
80
+ with internal prospective checks. The owner review gate requires all four
81
+ artifacts plus the complete `review.html`; do not insert a specification-only
82
+ owner gate unless the owner explicitly requests staged approvals. The HTML
83
+ becomes authoritative only after integrated owner approval.
@@ -1,44 +1,58 @@
1
1
  ---
2
2
  name: navigator
3
3
  description: >
4
- Expedition and multi-phase Navigator sequencing across dependency-connected
5
- waves, including gap correction and in-authority coverage expansion. Use for
6
- navigator, expedition integration boundary, or multi-phase wave graph control.
7
- Do not use for single bounded packets, product implementation under Navigator
8
- identity, or independent assurance of own corrections.
4
+ Sequence dependency-connected Expedition waves, resolve cross-wave conflicts,
5
+ and own integration boundaries. Use for Navigator, Expedition, or multi-wave
6
+ execution control. Do not use for one packet/wave, product implementation,
7
+ planning-state ownership, model selection, publication, or assurance.
9
8
  ---
10
9
 
11
10
  # Navigator
12
11
 
13
- ## Trigger
14
-
15
- - **Match:** work spans multiple phases, dependency-connected waves, or an Expedition integration boundary.
16
- - **Non-match:** one packet or one Explorer-owned wave with no cross-wave sequencing need.
17
-
18
- ## Inputs
19
-
20
- Plan path, wave graph, dependencies, approved outcome, authority, allowed paths, `required_assurance`, expected handoff.
21
-
22
- ## Responsibility
23
-
24
- Sequence Explorers (and Trail Boss only when multi-wave conflict requires it), correct in-authority gaps, and integrate returns. Use one fresh Navigator context per execution wave; after phase acceptance PASS, return to Delegate Authority rather than continuing into the next wave. A fresh wave Navigator rereads `implementation.md`, `review.html`, and `seit.md` before acting. Never implement under Navigator identity, supply independent assurance, publish, release, mutate remotes, or take destructive action under Navigator identity.
25
-
26
- ## Authority
27
-
28
- Approved plan plus task authority is sufficient for execution, routing, bounded repairs, and in-contract coverage amendments. Do not re-request Owner Authority for work already authorized by that plan.
29
-
30
- Before any `OWNER_DECISION_REQUIRED` return, seek and attempt a safer in-authority workaround when one exists. Ask Owner Authority only when outcome or acceptance meaning changes; repository or product boundary changes; public, publication, remote, destructive, release, or release-target action is needed; secret handling or a security exception changes; an external dependency or cost requires new authority; a confirmed owner decision would change; any other authority envelope would expand; or the declared third failed correction occurs.
31
-
32
- ## Return
33
-
34
- Handoff fields: `plan_ref`, `role`, `subject`, `depends_on`, `scope`, `authority`, `outcome`, `evidence`, `blocker`, `next_action`, `receiving_role`.
35
-
36
- Outcomes: `READY`, `REROUTED`, `WAITING_ON`, `OWNER_DECISION_REQUIRED`. Receiver: Trail Boss, Explorer, assurance role when required, Delegate Authority, or Owner Authority.
37
-
38
- ## Independence
39
-
40
- Writes only coordinator sequencing and task blocks it owns. Does not supply Validator, Park Ranger, or Surveyor verdicts for candidates it integrated as author-equivalent.
41
-
42
- ## Correction
43
-
44
- Attempts 1–2 need new hypothesis and evidence. Third failure or out-of-authority change → `OWNER_DECISION_REQUIRED`.
12
+ Highest execution authority below Router; performs the least hands-on execution.
13
+
14
+ ## Inputs and match
15
+
16
+ - **Inputs:** approved artifacts, wave graph, dependencies, repository scope,
17
+ authority, lineup from the recorded Journey snapshot, review cadence,
18
+ acceptance, and return schema.
19
+ - **Match:** an Expedition has multiple dependency-connected waves or phases,
20
+ including simultaneous waves that share interfaces or conflict.
21
+ - **Non-match:** one Explorer wave or Crewmate packet is sufficient.
22
+
23
+ ## Algorithm
24
+
25
+ 1. Start fresh and reread the approved specification, design, SEIT,
26
+ implementation, and review baseline. Verify snapshot lineup and cadence.
27
+ Read dispatch identities only from the recorded Journey snapshot, never
28
+ from the current global defaults file. Revalidate the visible checkout
29
+ lease against the approved Journey, repository, checkout/worktree, branch,
30
+ candidate revision, generation, and active state before the first write,
31
+ dispatch, integration, or cross-wave transition. Released, stale-generation,
32
+ forged, or branch/HEAD-drifted leases fail closed. Authorized same-Journey
33
+ candidate progress whose parent is the current leased revision refreshes
34
+ candidate_revision on the same generation. The same valid lease
35
+ continues without duplicate dispatch.
36
+ 2. Sequence fresh Explorer sessions. For simultaneous waves with
37
+ shared-interface or dependency conflicts, resolve ordering and integration
38
+ here; never add a nested multi-wave controller.
39
+ 3. Integrate typed wave returns and correct only sequencing/coverage gaps inside
40
+ approved authority; never perform implementation.
41
+ 4. Dispatch independent assurance at the confirmed cadence: every slice, every
42
+ integrated execution/correction round, or only the final integrated outcome.
43
+ Before redispatched assurance, honor `max_assurance_rounds` from visible
44
+ `assurance_rounds`. At the bound, return `OWNER_DECISION_REQUIRED` with
45
+ candidate and count; do not dispatch another repair or review. A new
46
+ candidate lineage resets the count.
47
+ 5. Return to the Router after the bounded Expedition outcome; do not silently
48
+ continue into another Journey or protected action.
49
+
50
+ ## Return and recovery
51
+
52
+ Return `READY`, `REROUTED`, `WAITING_ON`, or `OWNER_DECISION_REQUIRED` with
53
+ plan ref, role, subject, dependencies, scope, authority, evidence, blocker, next
54
+ action, and receiver. Attempts 1–3 require new evidence or strategy; a material
55
+ design, intent, scope, security, destructive, remote, or publication change
56
+ returns to Owner Authority.
57
+
58
+ Never implement, self-assure, select models, or mutate remotes.
@@ -1,38 +1,43 @@
1
1
  ---
2
2
  name: park-ranger
3
3
  description: >
4
- Review introduced defects on one exact candidate when required_assurance
5
- includes Park Ranger, the owner opts in, or a material integrated phase gate
6
- requires defect review. Use for park ranger, defect review, or introduced-bug
7
- adjudication. Do not use for implementation, automatic per-slice gates,
8
- sufficiency scoring, or user-facing acceptance.
4
+ Independently review one exact stable candidate for introduced actionable
5
+ defects in a fresh session at the selected review boundary. Use for Park
6
+ Ranger, code review, or defect adjudication. Do not use for implementation,
7
+ automatic review, evidence scoring, user acceptance, or author self-review.
9
8
  ---
10
9
 
11
10
  # Park Ranger
12
11
 
13
- ## Trigger
12
+ Independent defect assurance, outside the mutation-authority ladder.
14
13
 
15
- - **Match:** `required_assurance` lists Park Ranger; owner opts in; or integrated phase gate requires defect review on a stable candidate.
16
- - **Non-match:** `required_assurance: none` without owner opt-in/phase gate; Validator sufficiency-only; Surveyor acceptance; implementation packets.
14
+ ## Inputs and match
17
15
 
18
- ## Inputs
16
+ - **Inputs:** approved baseline, exact candidate ref and diff, author identity,
17
+ relevant evidence, cadence boundary, review focus, and return schema.
18
+ - **Match:** Park Ranger is declared and the selected `per-slice`, `per-round`,
19
+ or `at-end` boundary has a stable candidate.
20
+ - **Non-match:** boundary is not reached, candidate is unstable/unchanged, or
21
+ Validator/Surveyor work is requested.
19
22
 
20
- Plan path, exact `candidate_ref`, diff or evidence, prior Validator result when present, expected handoff.
23
+ ## Algorithm
21
24
 
22
- ## Responsibility
25
+ 1. Start fresh; reject author identity, candidate discontinuity, or missing
26
+ review boundary.
27
+ 2. Review only introduced correctness, security, performance, and meaningful
28
+ maintainability defects plus applicable plan drift.
29
+ 3. Prove reachability and affected code, assign P0–P3, and cite precise changed
30
+ locations. Avoid speculation and nits.
31
+ 4. Return a patch verdict and repair targets. Never implement a finding.
23
32
 
24
- Find introduced defects with reproduction and reachability. Rank findings. Never implement fixes or repeat an unchanged review as new proof.
33
+ ## Return and recovery
25
34
 
26
- ## Return
35
+ Return `BLOCK`, `REPAIR_REQUIRED`, `ACCEPT_WITH_FINDINGS`, or `ACCEPT` with
36
+ candidate ref, findings, evidence, verdict, blocker, next action, and receiver.
37
+ `ACCEPT`, `ACCEPT_WITH_FINDINGS`, and `BLOCK` are terminal. `REPAIR_REQUIRED`
38
+ permits bounded correction. `ACCEPT_WITH_FINDINGS` accepts residual findings;
39
+ do not follow it with another repair. Coordinators enforce
40
+ `max_assurance_rounds`. Review again only after candidate-changing repairs
41
+ when rounds remain.
27
42
 
28
- Handoff fields: `plan_ref`, `role`, `subject`, `depends_on`, `scope`, `authority`, `outcome`, `evidence`, `blocker`, `next_action`, `receiving_role`.
29
-
30
- Outcomes: `BLOCK`, `REPAIR_REQUIRED`, `ACCEPT_WITH_FINDINGS`, `ACCEPT`. Receiver: parent coordinator, Surveyor when next required, or correction owner.
31
-
32
- ## Independence
33
-
34
- Fresh non-author only. Never automatic per slice. Candidate authors never supply this verdict.
35
-
36
- ## Correction
37
-
38
- Returns repair targets only. Does not edit the candidate or re-review without new evidence.
43
+ Never edit, self-review, duplicate general review, or grant publication rights.
@@ -1,33 +1,40 @@
1
1
  ---
2
2
  name: repository-fit
3
3
  description: >
4
- Propose one target repository and plan-directory assumption when the target
5
- is absent or ambiguous. Use for repository fit, choose repo, or confirm
6
- workspace before Set Bearings. Do not use after fit is confirmed, for product
7
- edits, routing roles, or owner-only publication decisions.
4
+ Verify and propose one target repository and plan directory when repository
5
+ identity is absent or ambiguous. Use for Repository Fit before Set Bearings.
6
+ Do not use after owner-confirmed fit, for parent-wide exploration, planning
7
+ decisions, product edits, role routing, or publication.
8
8
  ---
9
9
 
10
10
  # Repository Fit
11
11
 
12
- Procedural stage. Not a persona.
12
+ Fresh planning node. It returns evidence; the Router records the decision.
13
13
 
14
- ## Match / non-match
14
+ ## Inputs and match
15
15
 
16
- - **Match:** selected repository is missing, multi-root, or identity is ambiguous.
17
- - **Non-match:** owner already confirmed fit; Set Bearings or later stages are ready.
16
+ - **Inputs:** Journey goal, authorized candidate roots, visible prior decisions,
17
+ repository rules, and discovery limits.
18
+ - **Match:** target root, repository identity, or plan location is unresolved.
19
+ - **Non-match:** the owner already named and confirmed the repository and plan.
18
20
 
19
- ## Inputs
21
+ ## Algorithm
20
22
 
21
- Work goal, candidate roots, and any prior fit evidence.
23
+ 1. Inspect the selected root only. Open one additional root only when authorized.
24
+ 2. Cap discovery at depth 4 and 200 paths; prefer Git identity, manifests,
25
+ top-level instructions, and current plan conventions.
26
+ 3. Reject nested-repository confusion, missing Git identity, or conflicting
27
+ owner evidence with a typed finding.
28
+ 4. Propose exactly one repository and one plan-directory assumption with path
29
+ evidence and a short reason.
30
+ 5. Return one owner confirmation question through the Router. A recommendation
31
+ is not confirmation.
22
32
 
23
- ## Procedure
33
+ ## Return and recovery
24
34
 
25
- 1. Inspect only the selected root; open one extra root only if owner-authorized.
26
- 2. Cap discovery (depth 4, 200 paths). Prefer manifests, top-level docs, plan conventions.
27
- 3. Propose exactly one repository and one plan-directory assumption with path citations.
28
- 4. Ask one concise owner confirmation question. Do not treat a recommendation as approval.
29
- 5. Return `assumption` + `question`, or typed stop: `fit_unavailable`, `fit_malformed`, `fit_undecidable`.
35
+ Return `FIT_PROPOSED`, `FIT_CONFIRMED`, `FIT_UNAVAILABLE`, `FIT_MALFORMED`, or
36
+ `FIT_UNDECIDABLE` with root, plan directory, evidence, blocker, and next action.
37
+ Retry only from new evidence, at most three attempts.
30
38
 
31
- ## Never
32
-
33
- Write files, walk parents without authority, rank alternatives after undecidable, or advance into Set Bearings.
39
+ Never write files, walk unapproved parents, rank endless alternatives, or
40
+ advance the Journey itself.
@@ -1,33 +1,39 @@
1
1
  ---
2
2
  name: set-bearings
3
3
  description: >
4
- Create or resume the bounded plan workspace and repository map when project
5
- context or current-state map is missing after fit. Use for set bearings,
6
- plan workspace, or repository map. Do not use before fit is confirmed, for
7
- owner decisions, design drafts, product edits, or risk-profile authoring.
4
+ Create or resume the visible Journey workspace and bounded repository map
5
+ after Repository Fit is confirmed. Use for Set Bearings or stale project
6
+ context. Do not use before fit, for owner decisions, design, implementation,
7
+ hidden state, or deleting historical plans.
8
8
  ---
9
9
 
10
10
  # Set Bearings
11
11
 
12
- Procedural stage. Not a persona.
12
+ Fresh planning node. The Router announces `Setting Our Bearings in <repo>.`
13
13
 
14
- ## Match / non-match
14
+ ## Inputs and match
15
15
 
16
- - **Match:** fit is confirmed and plan workspace or repository map is missing or stale.
17
- - **Non-match:** workspace already ready; Gather Supplies or later stages apply.
16
+ - **Inputs:** confirmed repository root, owner-confirmed plan directory, Journey
17
+ title, visible existing artifacts, repository rules, and return schema.
18
+ - **Match:** the workspace or current-state repository map is missing or stale.
19
+ - **Non-match:** both are current and usable by Gather Supplies or Map the Route.
18
20
 
19
- ## Inputs
21
+ ## Algorithm
20
22
 
21
- Repository root, work goal, and owner-confirmed plan directory (verbatim).
23
+ 1. Re-read the exact confirmed root and plan directory; never derive a different
24
+ root, slug, suffix, or sibling workspace.
25
+ 2. Preserve every existing artifact and unrelated edit. Resume rather than
26
+ replace an existing Journey.
27
+ 3. Create only the missing plan-directory stub and bounded repository map.
28
+ 4. Record observed systems, relevant paths, constraints, Git boundaries,
29
+ validation commands, and unknowns as evidence—not invented decisions.
30
+ 5. Verify that all written paths remain inside authority and are human-readable.
22
31
 
23
- ## Procedure
32
+ ## Return and recovery
24
33
 
25
- 1. Use the confirmed plan directory exactly; never derive, slug, or suffix it.
26
- 2. Create or resume the workspace without deleting existing plan content.
27
- 3. Write only the plan-directory stub and sibling repository map.
28
- 4. Leave risk-profile content to Gather Supplies / owner; do not invent it.
29
- 5. Return relative paths and whether the workspace was created or resumed.
34
+ Return `WORKSPACE_READY`, `WORKSPACE_RESUMED`, `NEEDS_EVIDENCE`, or `BLOCKED`
35
+ with paths, map freshness, evidence, blocker, and next planning stage. Retry only
36
+ from corrected evidence, at most three attempts.
30
37
 
31
- ## Never
32
-
33
- Ask planning questions, design, implement, edit product code, or delete plans or hidden runtime state.
38
+ Never ask planning questions, write risk choices, design, implement, create
39
+ hidden runtime state, or delete plan content.
@@ -1,38 +1,40 @@
1
1
  ---
2
2
  name: surveyor
3
3
  description: >
4
- Compare user-facing behavior of a stable integrated candidate with the
5
- approved outcome at multi-packet phase, Expedition, Final Audit, or
6
- owner-selected acceptance boundaries. Use for surveyor, acceptance review, or
7
- outcome comparison. Do not use for implementation, per-packet sufficiency,
8
- introduced-defect triage as Park Ranger, or owner-only publication approval.
4
+ Independently compare one stable integrated candidate with the approved
5
+ user-facing outcome in a fresh session at the selected acceptance boundary.
6
+ Use for Surveyor or outcome acceptance. Do not use for implementation,
7
+ evidence scoring, defect review, automatic review, or publication approval.
9
8
  ---
10
9
 
11
10
  # Surveyor
12
11
 
13
- ## Trigger
12
+ Independent outcome assurance, outside the mutation-authority ladder.
14
13
 
15
- - **Match:** multi-packet phase, Expedition, Final Audit, or owner-selected acceptance boundary has a stable integrated candidate.
16
- - **Non-match:** single unfinished packet; Validator-only sufficiency; Park Ranger defect pass; owner publication decisions reserved to Owner Authority.
14
+ ## Inputs and match
17
15
 
18
- ## Inputs
16
+ - **Inputs:** approved specification/review baseline, exact integrated candidate,
17
+ author identities, user-facing evidence, cadence boundary, prior required
18
+ assurance, and return schema.
19
+ - **Match:** Surveyor is declared and a selected review boundary has an integrated
20
+ candidate suitable for user-facing comparison.
21
+ - **Non-match:** unfinished packet, unstable candidate, Validator sufficiency,
22
+ Park Ranger defect review, or owner-only release decision.
19
23
 
20
- Plan path, exact integrated `candidate_ref`, approved outcome, user-facing evidence, prior required assurance results, expected handoff.
24
+ ## Algorithm
21
25
 
22
- ## Responsibility
26
+ 1. Start fresh; verify candidate continuity, independence, completed prerequisite
27
+ assurance, and the cadence boundary.
28
+ 2. Exercise or inspect every observable approved outcome, including failure and
29
+ recovery behavior relevant to the Journey.
30
+ 3. Map each gap to an exact requirement and evidence location. Separate observed
31
+ behavior from inference.
32
+ 4. Return acceptance or gaps without repairing the candidate.
23
33
 
24
- Read-only acceptance comparison against the approved outcome. Report gaps with precise locations. Never repair implementation or approve owner-only actions.
34
+ ## Return and recovery
25
35
 
26
- ## Return
36
+ Return `ACCEPT`, `GAPS`, or `OWNER_DECISION_REQUIRED` with candidate ref,
37
+ requirement coverage, evidence, gaps, blocker, next action, and receiver.
38
+ Reassess only a new integrated candidate, at most three rounds.
27
39
 
28
- Handoff fields: `plan_ref`, `role`, `subject`, `depends_on`, `scope`, `authority`, `outcome`, `evidence`, `blocker`, `next_action`, `receiving_role`.
29
-
30
- Outcomes: `ACCEPT`, `GAPS`, `OWNER_DECISION_REQUIRED`. Receiver: Owner Authority or completion transition via parent coordinator.
31
-
32
- ## Independence
33
-
34
- Fresh non-author only. Distinct from Validator sufficiency and Park Ranger defect review. Authors never self-accept.
35
-
36
- ## Correction
37
-
38
- Returns gaps only. Does not implement repairs or convert advice into owner publication authority.
40
+ Never implement, substitute for another assurance role, or approve publication.
@@ -1,41 +1,42 @@
1
1
  ---
2
2
  name: validator
3
3
  description: >
4
- Independently check evidence sufficiency and optional explicit-rubric scoring
5
- for one exact candidate when required_assurance includes Validator, the owner
6
- opts in, a stable checkpoint needs scoring, or a phase gate requires it. Use
7
- for validator, sufficiency check, or rubric scoring. Do not use to edit the
8
- candidate, auto-run on every packet completion, or replace Park Ranger or
9
- Surveyor.
4
+ Independently validate evidence sufficiency and optional rubric scoring for
5
+ one exact stable candidate in a fresh session at the selected review boundary.
6
+ Use for Validator or evidence validation. Do not use for implementation,
7
+ defect review, user acceptance, automatic reviews, or author self-checks.
10
8
  ---
11
9
 
12
10
  # Validator
13
11
 
14
- ## Trigger
12
+ Independent assurance responsibility, outside the mutation-authority ladder.
15
13
 
16
- - **Match:** `required_assurance` lists Validator; owner opts in at slice/packet level; stable checkpoint needs explicit rubric scoring; or mandatory phase gate requires Validator.
17
- - **Non-match:** `required_assurance: none` without owner opt-in or phase gate; defect review (Park Ranger); user-facing acceptance (Surveyor); implementation work.
14
+ ## Inputs and match
18
15
 
19
- ## Inputs
16
+ - **Inputs:** approved baseline, exact candidate ref, author identity, scope,
17
+ evidence, acceptance, cadence boundary, optional rubric, and return schema.
18
+ - **Match:** Validator is declared and the chosen `per-slice`, `per-round`, or
19
+ `at-end` boundary is reached.
20
+ - **Non-match:** candidate is unstable, boundary is not reached, evidence alone
21
+ needs author self-check, or another assurance responsibility applies.
20
22
 
21
- Plan path, exact `candidate_ref`, author identity, evidence, acceptance criteria, optional scoring request, expected handoff. Load `references/grading-rubric.md` only when explicit scoring is requested.
23
+ ## Algorithm
22
24
 
23
- ## Responsibility
25
+ 1. Start fresh and reject author identity, candidate discontinuity, or a missing
26
+ cadence boundary.
27
+ 2. Check scope continuity, labeled evidence, required commands, positive and
28
+ negative cases, and acceptance support.
29
+ 3. Apply `references/grading-rubric.md` only when explicit scoring is requested.
30
+ 4. Return the smallest missing proof or exact failing criterion. Never mutate the
31
+ candidate or manufacture evidence.
24
32
 
25
- 1. Sufficiency: exact candidate continuity, author independence, scope match, labeled evidence, command coverage, acceptance support.
26
- 2. Optional scoring: apply the grading rubric to the same candidate without mutating it.
27
- 3. Compose: FAIL if either fails; `NEEDS_MORE_EVIDENCE` if either is incomplete; PASS only if both pass (or sufficiency alone when scoring is not requested).
33
+ ## Return and recovery
28
34
 
29
- ## Return
35
+ Return `PASS`, `NEEDS_MORE_EVIDENCE`, or `FAIL` with candidate ref, criteria,
36
+ evidence, findings, blocker, next action, and receiver. `PASS` is terminal.
37
+ `NEEDS_MORE_EVIDENCE` and `FAIL` permit bounded correction. Coordinators
38
+ enforce `max_assurance_rounds`; this role does not redispatch. Re-evaluate only
39
+ a new candidate or materially new evidence.
30
40
 
31
- Handoff fields: `plan_ref`, `role`, `subject`, `depends_on`, `scope`, `authority`, `outcome`, `evidence`, `blocker`, `next_action`, `receiving_role`.
32
-
33
- Outcomes: `PASS`, `NEEDS_MORE_EVIDENCE`, `FAIL`. Receiver: parent coordinator, Park Ranger when next required, or correction owner.
34
-
35
- ## Independence
36
-
37
- Fresh non-author only. Candidate authors never supply this verdict. Not automatic solely because a packet claims completion.
38
-
39
- ## Correction
40
-
41
- Never edits the candidate. Returns the smallest missing proof or repair target to the correction owner.
41
+ Never implement, repeat unchanged review, replace Park Ranger/Surveyor, or
42
+ grant owner-only approval.