waypoint-codex 1.0.14 → 1.0.16

package/templates/.agents/skills/verify-codebase-coherence/SKILL.md

@@ -1,36 +1,35 @@
 ---
 name: verify-codebase-coherence
-description: Verify that completed work fits the existing codebase instead of introducing unnecessary parallel patterns. Use after implementation within a defined scope to detect avoidable new components, utilities, abstractions, state paths, design patterns, or conventions that should have reused or extended existing ones. Correct the work so it integrates coherently with the repo's existing architecture, components, naming, contracts, and design language.
+description: Audit completed work in a defined scope for codebase coherence before handoff. Use after implementation to verify the change reuses existing components, utilities, abstractions, state paths, naming, contracts, and design language instead of introducing avoidable parallel patterns. Do not use for redesign, replacement, collapse, or other implementation tasks that belong to foundational/edit-layer skills.
 ---
 
-Review the completed work in the requested scope and check whether it fits the existing codebase.
+# Verify Codebase Coherence
 
-Look for unnecessary parallel patterns such as:
-- new frontend components where an existing component should have been reused or extended
-- new helpers, hooks, utilities, or adapters that duplicate an existing pattern
-- new state paths or data flows that bypass the established architecture
-- new naming, file structure, or API shapes that do not match nearby conventions
-- one-off design, styling, or interaction patterns that do not fit the app
-- local abstractions that solve a problem the codebase already has a standard way to solve
+## Mission
+Audit the finished change for coherence with the existing codebase and report whether it is ready for closeout.
 
-Before keeping a new construct, check whether the repo already has:
-- a reusable component or composition pattern
-- an established state or data-fetching pattern
-- a standard boundary for validation, formatting, permissions, or persistence
-- an existing utility or shared contract
-- a nearby feature that should be extended instead of bypassed
+## Ordered Workflow
+1. Confirm the requested scope and the files actually changed by the implementation.
+2. Inspect the changed code in context of nearby code, shared helpers, and adjacent conventions.
+3. Check for avoidable parallel patterns: duplicate components, helpers, hooks, adapters, state paths, naming, API shapes, styling, or local abstractions.
+4. Check whether the change should have reused an existing component, utility, boundary, or composition pattern instead of introducing a new one.
+5. Classify each issue as either a coherence finding, a deliberate divergence, or out of scope.
+6. Decide closeout status: pass only if no unresolved coherence findings remain.
+7. Report findings with enough detail for the owner to act on them.
 
-If the work introduced a parallel pattern without a clear reason, fix it. Do not just report it.
+## Rules
+- Do not edit files.
+- Do not recommend a redesign, replacement, collapse, or refactor as a substitute for this audit.
+- Do not accept a new component, utility, hook, adapter, state path, or API shape if an existing one already covers the same job.
+- Do not treat faster implementation as a valid reason to fork the architecture, data flow, or design language.
+- Do not expand the review beyond the requested scope unless a change in that scope creates a direct coherence issue outside it.
+- Do not mark a deliberate divergence as a finding when the repo already documents or consistently uses that variant.
 
-When correcting violations:
-- reuse or extend existing components, utilities, and patterns where appropriate
-- remove unnecessary one-off abstractions or duplicate paths
-- align naming, structure, and interfaces with nearby code
-- preserve intended behavior unless the user asked for a behavioral change
+## Exception Rule
+If the codebase already has a sanctioned local variant, feature flag boundary, or documented exception that justifies the divergence, classify it as accepted and do not report it as a coherence defect.
 
-Rules:
-- Do not create a new component, utility, hook, adapter, or pattern if the repo already has one that should be reused or extended.
-- Do not fork the design language or architecture for a local feature without a clear reason.
-- Do not bypass established patterns just because creating a new path is faster.
-- Prefer extending the existing system over creating a parallel mini-system.
-- If divergence is necessary, it must be justified by a real requirement, not convenience.
+## Output Contract
+- Start with `PASS` or `FAIL`.
+- If `FAIL`, list each finding with file path, concise reason, and the specific reuse or alignment that should have happened.
+- If `PASS`, state that the audited scope is coherent and closeout-ready.
+- Include no code changes, no patch plan, and no redesign proposal.

package/templates/.agents/skills/verify-codebase-coherence/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Verify Codebase Coherence"
-  short_description: "Check architectural and structural coherence"
-  default_prompt: "Use $verify-codebase-coherence to audit the current scope for architectural coherence, boundary consistency, duplication, and drift before final handoff."
+  display_name: "Verify Codebase Coherence Audit"
+  short_description: "Audit completed work for coherence and drift"
+  default_prompt: "Use $verify-codebase-coherence to audit the completed scope for codebase coherence, duplication, boundary consistency, and convention drift. Report findings only and do not change files."

package/templates/.agents/skills/verify-completeness/SKILL.md

@@ -1,52 +1,63 @@
 ---
 name: verify-completeness
-description: Use when implementation appears done and before reporting completion. Re-read the original plan and agreed scope, re-read files that were supposed to be created or changed, verify no approved scope was reduced or skipped, and continue working until the scope is truly complete.
+description: Use when implementation appears done and before reporting completion. Re-read the approved plan and final scope, verify every in-scope file and checkpoint, and only then decide whether work can be reported complete.
 ---
 
 # Verify Completeness
 
-Use this skill at final closeout, right before you would report the work complete.
+Use this skill at final closeout, right before you would report work complete. Its job is to gate completion, not to re-open the whole project.
 
-## Required verification loop
+## Rules
 
-1. Re-read the original plan and the latest agreed scope before deciding status.
-2. Re-read `ACTIVE_PLANS.md` and `WORKSPACE.md` for current checklist, phase, blockers, and verification state.
-3. Build the expected file set from plan/scope: files that were supposed to be created, modified, or deleted.
-4. Re-read those files directly. This final re-read is mandatory even if they were read earlier in the session.
-5. Compare expected scope vs actual outcome and list any missing or partially completed items.
-6. Run a scope-discipline pass: identify additions that were not requested or approved. Remove/simplify them before completion, or explicitly ask the user to approve keeping them.
-7. Run a cleanup pass on changed files: remove duplicated logic, unnecessary abstractions/files, and low-value comments that create maintenance bloat.
-8. If changed code is still hard to read or reason about, run `legibility-pass` before completion and apply the resulting readability cleanup.
-9. Run a file-footprint sanity pass: collapse avoidable tiny-file fragmentation and keep code that changes together in the same place when boundary/reuse/size reasons are weak.
-10. Run a test-signal sanity pass: remove redundant or brittle tests and keep the smallest high-signal set that still protects the contract.
-11. Before commit/final handoff, run the full checks required by the plan (for example full typecheck/test/build sweep) once, unless explicitly blocked or the user asks for a different cadence.
-12. If any approved item is missing, incomplete, or silently deferred, do not report completion. Continue working until the agreed scope is fully satisfied or discuss a scope change explicitly.
+1. Re-read the approved plan and the latest agreed scope before deciding status.
+2. Re-read `ACTIVE_PLANS.md` and `WORKSPACE.md` for the current checklist, phase, blockers, and verification state.
+3. Build the expected file set from the approved scope only: files that were supposed to be created, modified, or deleted.
+4. Re-read every file in the expected set directly. This final re-read is mandatory even if the file was read earlier in the session.
+5. Compare expected scope vs actual outcome and identify any missing, partial, or silently deferred items.
+6. Run required plan checkpoints at the required cadence, including the full pre-commit checks when the plan requires them, unless a bounded exception applies.
+7. Do not report completion if any approved item is missing, incomplete, or deferred without explicit approval.
+8. Do not keep unapproved additions, cleanup work, refactors, abstractions, file splits, or test pruning in this skill's core scope; treat them as separate decisions that require explicit approval unless they are needed to finish the approved scope.
+9. If changed code is still hard to read or reason about, run `legibility-pass` and apply only the readability cleanup required to finish the approved scope.
+10. Keep adjacent skills conditional and narrow: use them only when the verification pass exposes that specific need, not as part of the default completion gate.
 
-## Completion gate
+## Exception Rule
+
+You may relax the normal verification loop only when one of these is true:
+
+- required plan artifacts are missing or stale, and you need to reconstruct the approved scope before continuing
+- the task is read-only or review-only, so no code or files are expected to change
+- required checks cannot run because the environment, dependencies, permissions, or upstream blockers make them impossible right now
+
+In these cases, continue only far enough to identify the gap, record the blocker, and report the exact missing verification step or artifact. Do not use the exception to absorb cleanup, refactor, or scope expansion work.
+
+## Completion Gate
 
 You can report complete only when all are true:
 
 - approved scope items are done
 - planned file changes match reality
-- verification/checkpoints required by the plan were run at the required cadence, including full pre-commit checks when required (or explicitly called out as blocked)
+- required verification/checkpoints were run, or each skipped check has a specific blocked reason
 - no hidden scope reduction occurred
 - no unapproved scope expansion remains
 - no obvious duplication or avoidable bloat remains in touched files
 - no avoidable file fragmentation remains in touched feature areas
 - test set remains high-signal and non-redundant for the risk level
 
-## Output contract
+## Output Contract
+
+Before final status, report these items explicitly:
 
-Before final status, summarize briefly:
+- `status`: `complete`, `blocked`, or `incomplete`
+- `scope reviewed`: the plan/scope sources you re-read
+- `files re-read`: the files you re-opened for final verification
+- `missing scope items`: any approved items still absent, or `none`
+- `checks run`: each verification step actually executed
+- `checks skipped`: each omitted check with a reason, or `none`
+- `removed extras`: any unapproved extras, cleanup, or bloat you removed, or `none`
+- `adjacent skill escalation`: any conditional skill you invoked and why, or `none`
+- `next action`: continue execution, request scope approval, or complete
 
-- scope reviewed
-- files re-read for final verification
-- completed items
-- removed unapproved extras or bloat cleanup applied
-- legibility cleanup applied (if run)
-- file-collapsing or test-pruning done during sanity passes
-- remaining gaps (if any)
-- next action (continue execution or complete)
+Do not say the work is complete unless the `status` is `complete` and the completion gate is satisfied.
 
 ## Gotchas
 

package/templates/.agents/skills/verify-completeness/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Verify Completeness"
-  short_description: "Run a strict final scope and file verification pass"
-  default_prompt: "Use $verify-completeness now: re-read the approved plan and scope, re-read all files that were supposed to change, remove unapproved extras and obvious bloat, verify nothing was dropped, and keep working if any approved scope item is still incomplete."
+  short_description: "Gate completion by re-reading scope, files, and required checks before closeout"
+  default_prompt: "Use $verify-completeness now: re-read the approved plan and final scope, re-read every file that was supposed to change, confirm missing scope items and skipped checks with reasons, and only report completion if the approved scope is fully finished."

package/templates/.codex/agents/duplicate_ownership_explorer.toml

@@ -0,0 +1,17 @@
+name = "duplicate_ownership_explorer"
+description = "Read-only explorer for one bounded slice of duplicate ownership. Use one agent per feature or contract slice."
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+nickname_candidates = ["Slice", "Scout", "Trace"]
+developer_instructions = """
+Own one narrow slice only.
+Look for duplicate ownership of rules such as validation, defaults, canonicalization, mapping, repair, persistence policy, and helper semantics.
+For each candidate, decide whether it is:
+- architecture / SSOT bug
+- local dedupe cleanup
+- legitimate boundary adapter
+- legitimate domain constraint
+Return exact files and symbols.
+Do not recommend wrappers, shims, or fallback paths.
+"""

package/templates/.codex/agents/ownership_taxonomy_mapper.toml

@@ -0,0 +1,16 @@
+name = "ownership_taxonomy_mapper"
+description = "Read-only mapper for duplicate-ownership audits. Use first to identify likely SSOT conflicts, ownership boundaries, and exploration slices before deeper review."
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+nickname_candidates = ["Mapper", "Topo", "Surveyor"]
+developer_instructions = """
+Stay in exploration mode.
+Map ownership boundaries, not fixes.
+Find likely places where the same rule is owned twice.
+Return:
+- candidate taxonomy
+- likely hot spots
+- recommended slice boundaries for parallel follow-up
+Do not propose compatibility shims or code changes unless the parent asks.
+"""

package/templates/.codex/agents/ssot_judge.toml

@@ -0,0 +1,17 @@
+name = "ssot_judge"
+description = "Strict read-only judge for duplicate-ownership findings. Use after exploration to decide the winning owner and hard-cut cleanup."
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+nickname_candidates = ["Judge", "Owner", "Verdict"]
+developer_instructions = """
+Act like an architecture owner.
+Given candidate duplicate-ownership findings, decide:
+- is this real duplicate ownership or legitimate boundary work
+- who should be the single owner
+- what should be deleted
+- what should remain
+- what should be renamed for honest semantics
+Bias toward hard-cut cleanup.
+Reject mediator layers, wrappers, compatibility paths, and dual ownership.
+"""

package/templates/.codex/config.toml

@@ -16,3 +16,15 @@ config_file = "agents/code-reviewer.toml"
 [agents."plan-reviewer"]
 description = "Read-only plan validator that checks whether a proposed implementation plan is complete, feasible, and safe to execute."
 config_file = "agents/plan-reviewer.toml"
+
+[agents."ssot_judge"]
+description = "Strict read-only judge for duplicate-ownership findings that selects the canonical owner and hard-cut cleanup."
+config_file = "agents/ssot_judge.toml"
+
+[agents."ownership_taxonomy_mapper"]
+description = "Read-only mapper that identifies ownership boundaries and high-risk SSOT duplicate-ownership slices before deeper audits."
+config_file = "agents/ownership_taxonomy_mapper.toml"
+
+[agents."duplicate_ownership_explorer"]
+description = "Read-only slice explorer that audits one bounded area for duplicate ownership and classifies findings with file-level evidence."
+config_file = "agents/duplicate_ownership_explorer.toml"

package/templates/managed-agents-block.md

@@ -37,6 +37,7 @@ Once the user approves a plan or tells you to proceed, that approved scope is th
 
 `WORKSPACE.md` is the live state file. `ACTIVE_PLANS.md` is the active execution checklist. Keep them current when state, blockers, or verification materially change.
 When durable behavior changes, update the relevant docs during the work. When live execution state changes, update `WORKSPACE.md` or `ACTIVE_PLANS.md` during the work, not only at the end.
+When creating or updating routable docs in `.waypoint/docs/` or `.waypoint/plans/`, include valid YAML frontmatter (`summary`, `last_updated`, `read_when`) so `.waypoint/DOCS_INDEX.md` can parse and route them.
 
 When changing code, do not hesitate to aggressively delete legacy code and rebuild the system when that is the clearest path to accomplishing the goal. Prefer clean replacement over compatibility scaffolding unless the user or project docs explicitly require coexistence.
 Do not widen a local change into a broader rewrite unless the current structure directly blocks the approved change or the user approves the expansion.