waypoint-codex 0.1.11 → 0.3.0

package/README.md

@@ -5,10 +5,10 @@ Waypoint is a docs-first repository operating system for Codex.
 It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:
 
 - `AGENTS.md` for startup instructions
-- `.waypoint/WORKSPACE.md` for live state
-- `.waypoint/docs/` for durable project memory
+- `.waypoint/WORKSPACE.md` for live state, with timestamped multi-topic entries
+- `.waypoint/docs/` for durable project memory, with `summary`, `last_updated`, and `read_when` frontmatter on routable docs
 - `.waypoint/DOCS_INDEX.md` for docs routing
-- repo-local skills for planning and audits
+- repo-local skills for planning, audits, verification, workspace compression, and review closure
 
 ## Install
 
@@ -59,6 +59,10 @@ repo/
 - `error-audit`
 - `observability-audit`
 - `ux-states-audit`
+- `workspace-compress`
+- `pre-pr-hygiene`
+- `pr-review`
+- `e2e-verify`
 
 ## Optional reviewer roles
 
@@ -69,6 +73,8 @@ If you initialize with `--with-roles`, Waypoint scaffolds:
 - `docs-researcher`
 - `plan-reviewer`
 
+The intended workflow is post-commit: after your own commit lands, run `code-reviewer` and `code-health-reviewer` in parallel in the background, then fix real findings before you call the work finished.
+
 ## Update
 
 ```bash

package/dist/src/core.js

@@ -11,6 +11,14 @@ const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
 const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
 const STATE_DIR = ".waypoint/state";
 const SYNC_RECORDS_FILE = ".waypoint/state/sync-records.json";
+const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
+    "## Current State",
+    "## In Progress",
+    "## Next",
+    "## Parked",
+    "## Done Recently",
+]);
+const TIMESTAMPED_ENTRY_PATTERN = /^(?:[-*]|\d+\.)\s+\[\d{4}-\d{2}-\d{2} \d{2}:\d{2} [A-Z]{2,5}\]/;
 function ensureDir(dirPath) {
     mkdirSync(dirPath, { recursive: true });
 }
@@ -183,6 +191,27 @@ function hashFile(filePath) {
 function codexHome() {
     return process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
 }
+function findWorkspaceTimestampViolations(workspaceText) {
+    let currentSection = "";
+    const violations = new Set();
+    for (const rawLine of workspaceText.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("## ")) {
+            currentSection = line;
+            continue;
+        }
+        if (!TIMESTAMPED_WORKSPACE_SECTIONS.has(currentSection) || line.length === 0) {
+            continue;
+        }
+        if (!/^(?:[-*]|\d+\.)\s+/.test(line)) {
+            continue;
+        }
+        if (!TIMESTAMPED_ENTRY_PATTERN.test(line)) {
+            violations.add(currentSection);
+        }
+    }
+    return [...violations];
+}
 function renderCodexAutomation(spec, cwd) {
     const now = Date.now();
     const rrule = spec.rrule?.startsWith("RRULE:") ? spec.rrule : `RRULE:${spec.rrule}`;
@@ -353,6 +382,16 @@ export function doctorRepository(projectRoot) {
                 });
             }
         }
+        const timestampViolations = findWorkspaceTimestampViolations(workspaceText);
+        if (timestampViolations.length > 0) {
+            findings.push({
+                severity: "warn",
+                category: "workspace",
+                message: `Workspace has untimestamped entries in ${timestampViolations.join(", ")}.`,
+                remediation: "Prefix new or materially revised workspace bullets with `[YYYY-MM-DD HH:MM TZ]`.",
+                paths: [workspacePath],
+            });
+        }
     }
     for (const requiredFile of [
         path.join(projectRoot, ".waypoint", "SOUL.md"),
@@ -387,7 +426,7 @@ export function doctorRepository(projectRoot) {
             severity: "warn",
             category: "docs",
             message: `Doc is missing valid frontmatter: ${relPath}`,
-            remediation: "Add `summary` and `read_when` frontmatter.",
+            remediation: "Add `summary`, `last_updated`, and `read_when` frontmatter.",
             paths: [path.join(projectRoot, relPath)],
         });
     }
@@ -414,6 +453,10 @@ export function doctorRepository(projectRoot) {
         "error-audit",
         "observability-audit",
         "ux-states-audit",
+        "workspace-compress",
+        "pre-pr-hygiene",
+        "pr-review",
+        "e2e-verify",
     ]) {
         const skillPath = path.join(projectRoot, ".agents/skills", skillName, "SKILL.md");
         if (!existsSync(skillPath)) {

package/dist/src/docs-index.js

@@ -13,14 +13,15 @@ const SKIP_NAMES = new Set(["README.md", "CHANGELOG.md", "LICENSE.md"]);
 function parseFrontmatter(filePath) {
     const text = readFileSync(filePath, "utf8");
     if (!text.startsWith("---\n")) {
-        return { summary: "", readWhen: [] };
+        return { summary: "", lastUpdated: "", readWhen: [] };
     }
     const endIndex = text.indexOf("\n---\n", 4);
     if (endIndex === -1) {
-        return { summary: "", readWhen: [] };
+        return { summary: "", lastUpdated: "", readWhen: [] };
     }
     const frontmatter = text.slice(4, endIndex);
     let summary = "";
+    let lastUpdated = "";
     const readWhen = [];
     let collectingReadWhen = false;
     for (const rawLine of frontmatter.split("\n")) {
@@ -30,6 +31,11 @@ function parseFrontmatter(filePath) {
             collectingReadWhen = false;
             continue;
         }
+        if (line.startsWith("last_updated:")) {
+            lastUpdated = line.slice("last_updated:".length).trim().replace(/^['"]|['"]$/g, "");
+            collectingReadWhen = false;
+            continue;
+        }
         if (line.startsWith("read_when:")) {
             collectingReadWhen = true;
             continue;
@@ -42,7 +48,7 @@ function parseFrontmatter(filePath) {
             collectingReadWhen = false;
         }
     }
-    return { summary, readWhen };
+    return { summary, lastUpdated, readWhen };
 }
 function walkDocs(projectRoot, currentDir, output, invalid) {
     for (const entry of readdirSync(currentDir)) {
@@ -58,9 +64,9 @@ function walkDocs(projectRoot, currentDir, output, invalid) {
         if (!entry.endsWith(".md") || SKIP_NAMES.has(entry)) {
             continue;
         }
-        const { summary, readWhen } = parseFrontmatter(fullPath);
+        const { summary, lastUpdated, readWhen } = parseFrontmatter(fullPath);
         const relPath = path.relative(projectRoot, fullPath);
-        if (!summary || readWhen.length === 0) {
+        if (!summary || !lastUpdated || readWhen.length === 0) {
             invalid.push(relPath);
             continue;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.1.11",
+  "version": "0.3.0",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

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

@@ -0,0 +1,63 @@
+---
+name: e2e-verify
+description: Perform manual end-to-end verification for a shipped feature or major change. Use when frontend and backend behavior must be verified together, when a feature needs a realistic walkthrough, or when the agent should manually exercise the flow, inspect logs and persisted state, document issues, fix them, and repeat until no meaningful end-to-end issues remain.
+---
+
+# E2E Verify
+
+Use this skill when "it should work" is not enough and the flow needs to be proven end to end.
+
+## Read First
+
+Before verification:
+
+1. Read `.waypoint/SOUL.md`
+2. Read `.waypoint/agent-operating-manual.md`
+3. Read `.waypoint/WORKSPACE.md`
+4. Read `.waypoint/context/MANIFEST.md`
+5. Read every file listed in that manifest
+6. Read the routed docs that define the feature, flow, or contract being verified
+
+## Step 1: Exercise The Real Flow
+
+- For browser-facing paths, manually exercise the feature through the real UI.
+- For backend-only or service flows, drive the real API or runtime path directly.
+- Follow the feature from entry point to persistence to user-visible outcome.
+
+## Step 2: Inspect End-To-End State
+
+Check the surfaces that prove the system actually behaved correctly:
+
+- UI state
+- server responses
+- logs
+- background-job state if relevant
+- database or persisted records when relevant
+
+Do not stop at "the page looked okay."
+
+## Step 3: Record And Fix Issues
+
+- Document each meaningful issue you find.
+- Fix the issue when the remediation is clear.
+- Update docs or contracts if verification exposes stale assumptions.
+
+## Step 4: Repeat Until Clean
+
+Re-run the end-to-end flow after fixes.
+
+The skill is complete only when:
+
+- the intended flow works
+- the persisted state is correct
+- the logs tell a truthful story
+- no meaningful issues remain
+
+## Step 5: Report Verification Truthfully
+
+Summarize:
+
+- the flows exercised
+- the state surfaces inspected
+- the issues found and fixed
+- any residual risks or unverified edges

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "E2E Verify"
+  short_description: "Manually verify a feature end to end"
+  default_prompt: "Use this skill for manual end-to-end verification of a feature or major change. Exercise the real flow, inspect UI plus logs and persisted state, document issues, fix them, and repeat until no meaningful end-to-end issues remain."

package/templates/.agents/skills/pr-review/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pr-review
+description: Triage and close the review loop on an open PR after automated or human review has started. Use when a PR has review comments pending, when automated reviewers are still running, or when you need to wait for review completion, answer every inline comment, fix meaningful issues, push follow-up commits, and keep repeating until no new meaningful review findings remain.
+---
+
+# PR Review
+
+Use this skill to drive the PR through review instead of treating review as a one-shot comment sweep.
+
+## Step 1: Wait For Review To Settle
+
+- Check the PR's current review and CI status.
+- If automated review is still running, wait for it to finish instead of racing it.
+- If comments are still arriving, do not prematurely declare the loop complete.
+
+## Step 2: Read Every Review Comment
+
+- Read all open review comments, especially inline comments.
+- Group duplicates, but do not ignore any comment.
+- Distinguish between meaningful issues, optional suggestions, and comments that should be explicitly declined.
+
+## Step 3: Triage And Respond Inline
+
+For every comment:
+
+- fix it if it is correct and in scope
+- explain clearly if you are declining it
+- reply inline where the comment lives instead of posting a disconnected summary comment
+
+Do not leave comments unanswered.
+
+## Step 4: Push The Next Round
+
+- Make the needed fixes.
+- rerun the relevant verification
+- push follow-up commit(s)
+- return to the PR and continue the loop
+
+Stay in the loop until no new meaningful issues remain.
+
+## Step 5: Close With A Crisp State Summary
+
+Summarize:
+
+- what was fixed
+- what was intentionally declined
+- what verification ran
+- whether the PR is clear or still waiting on reviewer response

package/templates/.agents/skills/pr-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PR Review"
+  short_description: "Close the review loop on an active PR"
+  default_prompt: "Use this skill when a PR has active review comments or automated review in progress. Wait for review to settle, triage every comment, reply inline, fix meaningful issues, push follow-up commits, and repeat until no new meaningful findings remain."

package/templates/.agents/skills/pre-pr-hygiene/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pre-pr-hygiene
+description: Run a broad final hygiene pass before pushing, before opening or updating a PR, or after a large implementation chunk when the diff is substantial and needs a deeper audit than per-commit review. Verify code-guide compliance, docs-to-behavior alignment, shared contract/schema drift, typing gaps, optimistic UI rollback or invalidation strategy, persistence correctness risks, and any other cross-cutting quality issues that would make the next review painful.
+---
+
+# Pre-PR Hygiene
+
+Use this skill for the larger final audit before code leaves the machine.
+
+## Read First
+
+Before the hygiene pass:
+
+1. Read `.waypoint/SOUL.md`
+2. Read `.waypoint/agent-operating-manual.md`
+3. Read `.waypoint/WORKSPACE.md`
+4. Read `.waypoint/context/MANIFEST.md`
+5. Read every file listed in that manifest
+6. Read `.waypoint/docs/code-guide.md` and the routed docs relevant to the area being shipped
+
+## Step 1: Audit The Whole Change Surface
+
+Inspect the code and docs that are about to ship.
+
+Look for:
+
+- code-guide violations such as silent fallbacks, swallowed errors, weak boundary validation, unsafe typing, or stale compatibility layers
+- stale docs, stale routes, or workspace notes that no longer match real behavior
+- shared schema, fixture, or API-contract drift
+- typing gaps such as avoidable `any`, weak narrowing, or unnecessary casts
+- optimistic UI without rollback or invalidation
+- persistence risks such as missing provenance, missing idempotency protection, weak uniqueness, or missing foreign-key style invariants
+
+Skip checks that truly do not apply, but say that you skipped them.
+
+## Step 2: Fix Or Stage Findings
+
+- Fix meaningful issues directly when the right remediation is clear.
+- Update `.waypoint/docs/` when shipped behavior or routes changed.
+- If the live handoff has become bloated or stale, use `workspace-compress`.
+
+Do not stop at reporting obvious fixable issues.
+
+## Step 3: Verify Before Ship
+
+Run the most relevant verification for the area:
+
+- tests
+- typecheck
+- lint
+- build
+- targeted manual QA
+
+## Step 4: Report The Gate Result
+
+Summarize:
+
+- what you checked
+- what you fixed
+- what verification ran
+- what residual risks remain, if any

package/templates/.agents/skills/pre-pr-hygiene/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pre-PR Hygiene"
+  short_description: "Run the final cross-cutting ship audit"
+  default_prompt: "Use this skill before pushing or opening/updating a PR for substantial work to do a broader hygiene pass across code, docs, contracts, typing, UI rollback, persistence correctness, and code-guide compliance."

package/templates/.agents/skills/workspace-compress/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: workspace-compress
+description: Compress and refresh the repository's live workspace handoff so `WORKSPACE.md` stays short, current, and useful to the next agent. Use after finishing a meaningful chunk of work, before stopping for the session, before asking for review, before opening or updating a PR, or whenever the workspace has started accumulating stale history, repeated status logs, or resolved context that should no longer stay in the live handoff. Keep the minimum current operational state, collapse old resolved entries, and move durable detail into existing routed docs instead of duplicating it in the workspace.
+---
+
+# Workspace Compress
+
+Keep `WORKSPACE.md` as a live handoff, not a project diary.
+
+This skill is for compression, not for erasing context. Preserve what the next agent needs in the first few minutes of a resume, and push durable detail into the docs layer that already exists in the repo.
+
+## Read First
+
+Before compressing:
+
+1. Read `.waypoint/SOUL.md`
+2. Read `.waypoint/agent-operating-manual.md`
+3. Read `.waypoint/WORKSPACE.md`
+4. Read `.waypoint/context/MANIFEST.md`
+5. Read every file listed in that manifest
+6. Read the routed docs relevant to the active workspace sections
+
+## Step 1: Build Context From Routing, Not From Git Diff
+
+This skill must work even in a dirty tree or an arbitrary session state.
+
+- Read the workspace file in full.
+- Read `.waypoint/DOCS_INDEX.md` and the workspace's obvious routing pointers.
+- Read the project or domain docs directly linked from the active sections you may compress.
+- If the workspace references a progress, status, architecture, or release doc, treat that as the durable home for details before removing anything from the live handoff.
+
+Do not rely on `git diff` as the primary signal for what matters.
+
+## Step 2: Apply The Handoff Test
+
+Ask one question:
+
+**What does the next agent need in the first 10 minutes to resume effectively?**
+
+Keep only the answer to that question in the workspace. Usually that means:
+
+- current focus
+- latest verified state
+- open blockers or risks
+- immediate next steps
+- only the last few meaningful timestamped updates
+
+Usually remove or collapse:
+
+- resolved implementation logs
+- repeated status updates that say the same thing
+- validation transcripts
+- old milestone history
+- duplicated durable documentation
+
+Compression is documentation quality, not data loss.
+
+## Step 3: Compress Safely
+
+When editing the workspace:
+
+1. Preserve the active operational truth.
+2. Collapse stale resolved bullets into one short summary when history still matters.
+3. Remove entries that are already preserved elsewhere and no longer affect immediate execution.
+4. Keep timestamp discipline for new or materially revised bullets.
+5. Do not turn the workspace into an archive, changelog, or debug notebook.
+
+If durable context is missing from `.waypoint/docs/`, add or refresh the smallest coherent routed doc before removing it from the workspace.
+
+## Step 4: Protect User-Owned State
+
+- Never overwrite or revert unrelated user changes.
+- If a workspace or doc already has in-flight edits you did not make, read carefully and work around them.
+- Prefer surgical edits over broad rewrites.
+- Do not delete project memory just because live state is being compressed.
+
+## Step 5: Refresh Routing
+
+After changing routed docs or the workspace:
+
+- Run `node .waypoint/scripts/prepare-context.mjs` so the docs index and generated context match the edited sources.
+
+## Step 6: Report The Result
+
+Summarize:
+
+- what stayed in the live handoff
+- what was collapsed or removed
+- which durable docs now hold the preserved detail
+- any remaining risk that still belongs in the workspace

package/templates/.agents/skills/workspace-compress/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Workspace Compress"
+  short_description: "Compress the live workspace handoff"
+  default_prompt: "Use this skill after a meaningful chunk of work, before stopping, before review, or before opening or updating a PR to keep WORKSPACE.md short, current, and useful to the next agent."

package/templates/.codex/agents/code-health-reviewer.toml

@@ -4,11 +4,10 @@ developer_instructions = """
 Read these files in order before doing anything else:
 1. .waypoint/SOUL.md
 2. .waypoint/agent-operating-manual.md
-3. WORKSPACE.md
+3. .waypoint/WORKSPACE.md
 4. .waypoint/context/MANIFEST.md
 5. every file listed in that manifest
 6. .waypoint/agents/code-health-reviewer.md
 
 After reading them, follow .waypoint/agents/code-health-reviewer.md as your operating instructions.
 """
-

package/templates/.codex/agents/code-reviewer.toml

@@ -4,11 +4,10 @@ developer_instructions = """
 Read these files in order before doing anything else:
 1. .waypoint/SOUL.md
 2. .waypoint/agent-operating-manual.md
-3. WORKSPACE.md
+3. .waypoint/WORKSPACE.md
 4. .waypoint/context/MANIFEST.md
 5. every file listed in that manifest
 6. .waypoint/agents/code-reviewer.md
 
 After reading them, follow .waypoint/agents/code-reviewer.md as your operating instructions.
 """
-

package/templates/.codex/config.toml

@@ -1,13 +1,16 @@
+[features]
+multi_agent = true
+
 [agents]
 max_depth = 1
-max_threads = 4
+max_threads = 24
 
 [agents."code-health-reviewer"]
-description = "Read-only reviewer focused on maintainability drift, dead code, duplication, and refactoring opportunities worth fixing."
+description = "Read-only background reviewer for post-commit maintainability drift, dead code, duplication, and refactoring opportunities worth fixing."
 config_file = "agents/code-health-reviewer.toml"
 
 [agents."code-reviewer"]
-description = "Read-only deep code reviewer focused on real bugs, regressions, and integration mistakes."
+description = "Read-only background reviewer for post-commit bugs, regressions, and integration mistakes."
 config_file = "agents/code-reviewer.toml"
 
 [agents."docs-researcher"]

package/templates/.waypoint/README.md

@@ -3,11 +3,11 @@
 Repo-local Waypoint configuration and optional integration sources.
 
 - `config.toml` — Waypoint feature toggles and file locations
-- `WORKSPACE.md` — live operational state
+- `WORKSPACE.md` — live operational state; new or materially revised entries in multi-topic sections are timestamped
 - `DOCS_INDEX.md` — generated docs routing map
 - `SOUL.md` — agent identity and working values
 - `agent-operating-manual.md` — required session workflow
-- `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans)
+- `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans); routable docs use `summary`, `last_updated`, and `read_when` frontmatter
 - `agents/` — agent prompt files that optional Codex roles can read and follow
 - `automations/` — optional automation source specs
 - `context/` — generated session context bundle

package/templates/.waypoint/SOUL.md

@@ -30,6 +30,8 @@ You're direct, opinionated, and evidence-driven. You read before you write. You
 
 **Update the durable record.** When behavior changes, update docs. When state changes, update `WORKSPACE.md`. When a better pattern emerges, encode it in the repo contract instead of rediscovering it later.
 
+**Close the loop after commits.** If Waypoint's reviewer roles are available, launch `code-reviewer` and `code-health-reviewer` after your own commits and address the real findings before you call the work finished.
+
 **Prefer small, reviewable changes.** Keep work scoped and comprehensible.
 
 ## What Matters Most

package/templates/.waypoint/agent-operating-manual.md

@@ -42,10 +42,11 @@ If something important lives only in your head or in the chat transcript, the re
 
 - Read code before editing it.
 - Follow the repo's documented patterns when they are healthy.
-- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes.
-- Update `.waypoint/docs/` when durable knowledge changes.
+- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes. In multi-topic sections, prefix new or materially revised bullets with a local timestamp like `[2026-03-06 20:10 PST]`.
+- Update `.waypoint/docs/` when durable knowledge changes, and refresh each changed routable doc's `last_updated` field.
 - Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
 - Use the repo-local skills and optional reviewer agents instead of improvising from scratch.
+- Do not kill long-running subagents or reviewer agents just because they are slow. Wait unless they are clearly stuck, failed, or the user redirects the work.
 
 ## Documentation expectations
 
@@ -66,6 +67,10 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 - `error-audit` when failures are being swallowed or degraded invisibly
 - `observability-audit` when production debugging signals look weak
 - `ux-states-audit` when async/data-driven UI likely lacks loading, empty, or error states
+- `workspace-compress` after meaningful chunks, before stopping, and before review when the live handoff needs compression
+- `pre-pr-hygiene` before pushing or opening/updating a PR for substantial work
+- `pr-review` once a PR has active review comments or automated review in progress
+- `e2e-verify` for major user-facing or cross-system changes that need manual end-to-end verification
 
 ## When to use the optional reviewer agents
 
@@ -76,6 +81,15 @@ If the repo was initialized with Waypoint roles enabled, use them as focused sec
 - `docs-researcher` for external dependency research
 - `plan-reviewer` to challenge weak implementation plans before execution
 
+## Post-Commit Review Loop
+
+If Waypoint's optional roles are enabled and you authored a commit, immediately after that commit:
+
+1. Launch `code-reviewer` and `code-health-reviewer` in parallel as background, read-only reviewers.
+2. Scope them to the commit you just made, then widen only when surrounding files are needed to validate a finding.
+3. Do not call the work finished before you read both reviewer results.
+4. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
+
 ## Quality bar
 
 - No silent assumptions

package/templates/.waypoint/agents/code-health-reviewer.md

@@ -9,7 +9,7 @@ You are a Code Health specialist. You find maintainability issues and technical
 
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
-3. Read `WORKSPACE.md`
+3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 5. Read every file listed in the manifest
 6. Read the docs relevant to the area under review
@@ -59,7 +59,7 @@ Do not create findings for:
 
 ## Scope
 
-Check recent commits and changes to determine scope. Focus on:
+In Waypoint's default post-commit review loop, start with the latest self-authored commit, then widen only when related files are needed to validate a maintainability issue. Focus on:
 
 - recently changed files
 - their importers
@@ -84,4 +84,3 @@ Each finding needs:
 ## Return
 
 Files analyzed, findings, brief overall assessment.
-

package/templates/.waypoint/agents/code-reviewer.md

@@ -9,7 +9,7 @@ You are a code reviewer. Find bugs that matter — logic errors, data flow issue
 
 1. Read `.waypoint/SOUL.md`
 2. Read `.waypoint/agent-operating-manual.md`
-3. Read `WORKSPACE.md`
+3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 5. Read every file listed in the manifest
 6. Read the docs relevant to the changed area
@@ -41,7 +41,7 @@ Not:
 
 ### 1. Get the Changes
 
-Review the actual diff or recent changed files first.
+In Waypoint's default post-commit review loop, start with the latest self-authored commit. Review the actual diff or recent changed files first, then widen only as needed.
 
 ### 2. Deep Research
 
@@ -99,4 +99,3 @@ Do not report:
 - theoretical problems you can't demonstrate
 - style preferences
 - vague "could be cleaner" commentary without concrete benefit
-

package/templates/.waypoint/docs/README.md

@@ -18,10 +18,10 @@ Every routable doc needs YAML frontmatter:
 ```yaml
 ---
 summary: One-line description
+last_updated: "2026-03-06 20:10 PST"
 read_when:
   - task cue
 ---
 ```
 
-`DOCS_INDEX.md` is generated from the docs here.
-
+Refresh `last_updated` whenever you materially change a doc. `DOCS_INDEX.md` is generated from the docs here.

package/templates/.waypoint/docs/code-guide.md

@@ -1,95 +1,113 @@
 ---
-summary: Opinionated rules for writing and changing Waypoint code so behavior stays explicit, strict, observable, and easy to evolve.
+summary: Universal coding conventions — explicit behavior, type safety, frontend consistency, reliability, and behavior-focused verification
+last_updated: "2026-03-10 10:05 PDT"
 read_when:
-  - writing new code
-  - changing existing behavior
-  - introducing or removing configuration
-  - handling external input or external systems
-  - adding tests, logging, or state transitions
+  - writing code
+  - coding standards
+  - code conventions
+  - TypeScript
+  - frontend
+  - backend
+  - error handling patterns
+  - testing
 ---
 
 # Code Guide
 
-Waypoint favors explicitness over convenience, correctness over compatibility theater, and deletion over accumulation. Code should make the system easier to reason about after the change, not merely pass today.
+Write code that keeps behavior explicit, failure visible, and the next change easier than the last one.
 
 ## 1. Compatibility is opt-in, not ambient
 
 Do not preserve old behavior unless a user-facing requirement explicitly asks for it.
 
-When replacing a path, remove the old one instead of leaving a shim, alias, translation layer, or silent compatibility branch. If compatibility must be preserved, document the exact contract being preserved and the planned removal condition.
+- Remove replaced paths instead of leaving shims, aliases, or silent compatibility branches.
+- Do not keep dead fields, dual formats, or migration-only logic "just in case."
+- If compatibility must stay, document the exact contract being preserved and the removal condition.
 
-Do not keep dead fields, dead parameters, dual formats, or migration-only logic "just in case". Every compatibility layer becomes part of the design whether intended or not.
+## 2. Type safety is non-negotiable
 
-## 2. Fail clearly, never quietly
+The compiler is part of the design, not an afterthought.
 
-Errors are part of the contract. Surface them early and with enough context to diagnose the cause.
+- Write as if strict mode is enabled. Type errors are build blockers.
+- Never use `any` when `unknown`, narrowing, generics, or better shared types can express the real contract.
+- Reuse exported library or app types instead of recreating them locally.
+- Be explicit at boundaries: function params, returns, public interfaces, API payloads, DB rows, and shared contracts.
+- Validate external data at boundaries with schema validation and convert it into trusted internal shapes once.
+- Avoid cross-package type casts unless there is no better contract available; fix the shared types instead when practical.
 
-Do not swallow errors, downgrade them to logs, or return partial success unless partial success is the explicit API. If an operation can fail in distinct ways, preserve those distinctions. Do not replace a specific failure with a generic one that destroys meaning.
+## 3. Fail clearly, never quietly
 
-Error messages should identify what failed, at which boundary, and why the system refused to proceed. They should not force readers to infer missing state from generic text.
+Errors are part of the contract.
 
-## 3. No silent fallback paths
+- Fail explicitly. No silent fallbacks, empty catches, or degraded behavior that pretends everything is fine.
+- Every caught exception must propagate, crash, or be surfaced truthfully to the user or operator.
+- Do not silently switch to worse models, stale cache, inferred defaults, empty values, or best-effort modes unless that degradation is an intentional product behavior.
+- Required configuration has no silent defaults. Missing required config is a startup or boundary failure.
+- Error messages should identify what failed, where, and why.
 
-Fallbacks are allowed only when they are deliberate product behavior, not a coding reflex.
+## 4. Validate at boundaries
 
-Do not silently retry with weaker behavior, alternate providers, cached data, inferred defaults, empty values, or best-effort modes unless the user asked for degraded operation and the degraded result remains truthful.
+Anything crossing a boundary is untrusted until proven otherwise.
 
-If degradation exists, it must be explicit in code, testable, and observable. Hidden fallback logic makes the system look healthy while it is already off-contract.
+- Validate user input, config, files, HTTP responses, generated content, database reads, queue payloads, and external API data at the boundary.
+- Reject invalid data instead of "normalizing" it into something ambiguous.
+- Keep validation near the boundary instead of scattering half-validation deep inside the system.
 
-## 4. Validate at boundaries, not deep inside
+## 5. Prefer direct code over speculative abstraction
 
-Anything that crosses a boundary must be treated as untrusted: user input, config, environment, files, network responses, database reads, queue payloads, generated content, and data from other modules.
+Do not invent complexity for hypothetical future needs.
 
-Validate structure, required fields, allowed values, and invariants at the boundary. Convert external data into a trusted internal shape once. Do not pass loosely-typed or half-validated data deeper into the system and hope downstream code copes.
+- Add abstractions only when multiple concrete cases already demand the same shape.
+- Prefer straightforward code and small duplication over the wrong generic layer.
+- If a helper hides critical validation, state changes, or failure modes, it is probably hurting clarity.
 
-Boundary validation should reject invalid data, not "normalize" it into something ambiguous.
+## 6. Make state, contracts, and provenance explicit
 
-## 5. Configuration must be strict
+Readers should be able to tell what states exist, what transitions are legal, and what data can be trusted.
 
-Missing or invalid configuration should stop the system at startup or at the feature boundary where it becomes required.
+- Use explicit state representations and enforce invariants at the boundary of the operation.
+- Multi-step writes must have clear transaction boundaries.
+- Retryable operations must be idempotent or guarded against duplicate effects.
+- New schema and persistence work should make provenance obvious and protect against duplication with the right uniqueness constraints, foreign keys, or equivalent invariants.
+- Shared schemas, fixtures, and contract types must match the real API and stored data shape.
 
-Do not hide absent configuration behind guessed defaults, environment-dependent behavior, or implicit no-op modes. Defaults are acceptable only when they are safe, intentional, and documented as part of the product contract.
+## 7. Frontend must reuse and fit the existing system
 
-Configuration should be centralized enough to audit. A reader should be able to tell which settings matter, what values are valid, and what happens when they are wrong.
+Frontend changes should extend the app, not fork its design language.
 
-## 6. Prefer direct code over speculative abstraction
+- Before creating a new component, check whether the app already has a component or pattern that should be reused.
+- Reuse existing components when they satisfy the need, even if minor adaptation is required.
+- When a new component is necessary, make it match the design language, interaction model, spacing, states, and compositional patterns of the rest of the app.
+- Handle all states for async and data-driven UI: loading, success, empty, error.
+- Optimistic UI must have an explicit rollback or invalidation strategy. Never leave optimistic state hanging without a recovery path.
 
-Do not introduce abstractions for imagined future use. Add them only when multiple concrete cases already demand the same shape.
+## 8. Observability is part of correctness
 
-A small amount of duplication is cheaper than the wrong abstraction. Prefer code that exposes the current domain plainly over generic layers, plugin systems, factories, wrappers, or strategy trees created before the need is real.
+If you cannot see the failure path, you have not finished the work.
 
-Abstractions must remove real complexity, not relocate it. If a helper hides critical behavior, state changes, validation, or failure modes, it is making the system harder to read.
+- Emit structured logs, metrics, or events at important boundaries and state transitions.
+- Include enough context to reproduce issues without logging secrets or sensitive data.
+- Failed async work, retries, degraded paths, and rejected inputs must leave a useful trace.
+- Do not use noisy logging to compensate for unclear control flow.
 
-## 7. Make state and invariants explicit
+## 9. Test behavior, not implementation
 
-State transitions should be visible in code. Readers should be able to answer: what states exist, what moves the system between them, and what must always be true.
+Tests should protect the contract users depend on.
 
-Do not encode important transitions as scattered flag mutations, ordering assumptions, optional fields, or side effects hidden in utility calls. Avoid representations where invalid states are easy to create and hard to detect.
-
-When a function changes state, make the transition obvious. When a module depends on an invariant, assert it at the boundary of the operation instead of relying on folklore.
-
-## 8. Tests define behavior changes, not just regressions
-
-Any behavior change must update tests to describe the new contract. If the old behavior mattered, remove or rewrite the old tests instead of making them weaker.
-
-Test observable behavior and boundary cases, not implementation trivia. Cover failure modes, validation rules, configuration strictness, and any intentional degradation path. If a bug fix closes a previously possible bad state, add a test that proves the bad state is now rejected.
-
-Do not merge code whose behavior changed without leaving behind executable evidence of the new rules.
-
-## 9. Observability is part of correctness
-
-Code is not complete if production failures cannot be understood from its signals.
-
-Emit structured logs, metrics, or events at important boundaries and state transitions, especially around input rejection, external calls, retries, and degraded modes. Observability should explain which path executed and why.
-
-Do not log noise to compensate for poor design. Prefer a small number of high-value signals tied to decisions, failures, and contract edges.
+- Test observable behavior and boundary cases, not implementation trivia.
+- Never write brittle regression tests that assert exact class strings, styling internals, private helper calls, incidental DOM structure, internal schema representations, or other implementation-detail artifacts.
+- Regression tests must focus on the behavior that was broken and the behavior that is now guaranteed.
+- For backend bugs, prefer behavior-focused regression tests by default.
+- For frontend bugs, prefer manual QA by default; add automated regression coverage only when there is a stable user-visible behavior worth protecting.
+- Do not merge behavior changes without leaving behind executable or clearly documented evidence of the new contract.
 
 ## 10. Optimize for future legibility
 
-Write code for the next person who must change it under pressure.
-
-Keep modules narrow in responsibility. Keep data flow obvious. Keep control flow boring. Prefer designs where the main path is easy to follow and unusual behavior is explicitly named.
+Write code for the next engineer or agent who has to change it under pressure.
 
-When changing code, improve the shape around the change if needed. Do not leave behind half-migrated designs, obsolete branches, commented-out code, or placeholders for imagined follow-ups.
+- Keep modules narrow in responsibility and data flow obvious.
+- Remove stale branches, half-migrations, dead code, and obsolete docs around the change.
+- Keep docs and shipped behavior aligned.
+- Before pushing or opening a PR, do a hygiene pass for stale docs, drifting contracts, typing gaps, missing rollback strategies, and new persistence correctness risks.
 
-The best code is not code that can handle every possible future. It is code whose current truth is obvious, whose failures are visible, and whose wrong parts can be deleted without fear.
+The best code is not the most flexible code. It is the code whose current truth is obvious, whose failures are visible, and whose wrong parts can be deleted without fear.

package/templates/WORKSPACE.md

@@ -1,5 +1,7 @@
 # Workspace
 
+Timestamp discipline: Prefix new or materially revised bullets in `Current State`, `In Progress`, `Next`, `Parked`, and `Done Recently` with `[YYYY-MM-DD HH:MM TZ]`.
+
 ## Active Goal
 
 Describe the main thing currently being built or changed.
@@ -23,4 +25,3 @@ What is intentionally deferred?
 ## Done Recently
 
 What meaningful progress just landed?
-

package/templates/managed-agents-block.md

@@ -31,8 +31,12 @@ This is mandatory, not optional.
 - Do not skip the context refresh or skip files in the manifest.
 
 Working rules:
-- Keep `.waypoint/WORKSPACE.md` current as the live execution state
-- Update `.waypoint/docs/` when behavior or durable project knowledge changes
+- Keep `.waypoint/WORKSPACE.md` current as the live execution state, with timestamped new or materially revised entries in multi-topic sections
+- Update `.waypoint/docs/` when behavior or durable project knowledge changes, and refresh `last_updated` on touched routable docs
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
+- If optional reviewer roles are present and you make a commit, run `code-reviewer` and `code-health-reviewer` in parallel before calling the work done
+- Before pushing or opening/updating a PR for substantial work, use `pre-pr-hygiene`
+- Use `pr-review` once a PR has active review comments or automated review in progress
+- Use `e2e-verify` for major user-facing or cross-system changes that need manual end-to-end verification
 - Treat the generated context bundle as required session bootstrap, not optional reference material
 <!-- waypoint:end -->