Add wrong-location guardrails: PreToolUse hook + artifact validator

[KjellKod]

Summary

Ship two additive guardrails that ride out through the installer to every Quest user, targeting the top friction class in the eval data (wrong-branch / wrong-directory / wrong nested .quest/ edits — 55 "wrong approach" events across recent sessions).

• A PreToolUse Edit|Write hook that prints branch + working directory before every edit.
• A post-invocation artifact-path validator wired into workflow.md's Handoff File Polling pattern.

Important

Existing Quest installs with a customized .claude/settings.json will receive a .quest_updated sidecar on the next installer run and must merge the new PreToolUse Edit|Write block manually. The installer's merge-carefully mode is checksum-compare, not JSON-aware merge. The caveat is documented in AGENTS.md; the manifest contract test asserts the caveat string stays present.

Changes

• Hook:
  • .claude/hooks/branch-dir-context.sh — prints [quest-context] branch=<name|no-git> dir=<path>; exits 0 in git, non-git, and detached-HEAD contexts; never blocks the wrapped tool call.
  • .claude/settings.json — additive PreToolUse Edit|Write entry; existing SessionStart and PostToolUse Write|Edit hooks preserved verbatim.
• Validator:
  • scripts/quest_artifact_postflight.py — filesystem-only check against expected_artifacts_for_role(...). Five mismatch reasons (missing, outside_boundary, noncanonical_filename, nested_quest_path, path_traversal) plus defensive unsupported_role_or_phase. Non-zero exit on mismatch; appends one JSON line per mismatch to .quest/<id>/logs/path_compliance.log. Orchestrator policy is accepted_with_warnings (non-halting per kill criterion). Latency target <50 ms, regression cap <200 ms.
• Workflow wire-in:
  • .skills/quest/delegation/workflow.md — new postflight step appended at the end of the Handoff File Polling pattern. Items 1–6 keep their numbers so the 10 hard-coded Handoff File Polling §5/§6 cross-references elsewhere in the doc don't drift.
• Manifest:
  • .quest-manifest — both new files added under [copy-as-is] so downstream installs receive them.
• Documentation:
  • AGENTS.md — "Wrong-location guardrails" section naming both guardrails, the disable mechanism, and the installer caveat.
  • ideas/README.md — Done Index row added; three active rows removed.
  • docs/quest-journal/wrong-location-guardrails_2026-05-18.md — quest journal with celebration data.
• Archival:
  • ideas/2026-05-17-wrong-location-guardrails.md, ideas/2026-04-15-pretooluse-branch-dir-verification-hook.md, ideas/2026-04-15-subagent-path-constraints-hardening.md moved to ideas/archive/ via git mv.
• Tests:
  • tests/unit/test_branch_dir_context_hook.sh — hook contexts (git, non-git, detached-HEAD), stdout format, exit-0 guarantee.
  • tests/unit/test_quest_artifact_postflight.py — 12 cases including latency target and regression cap behind pytest.mark.perf.
  • tests/unit/test_workflow_postflight_wireup.py — placement (end-of-section) + cross-reference count assertions (§5 × 6, §6 × 4).
  • tests/unit/test_manifest_guardrails_entries.py — [copy-as-is] entries + AGENTS.md literals + merge-carefully posture for settings.json.
  • tests/unit/test_ideas_archive_guardrails_housekeeping.py — archive paths exist + Done Index row points at the journal.
• Config:
  • pyproject.toml — registers perf marker so non-perf runs filter cleanly.
  • .ai/allowlist.json — every role pinned to claude for this quest (committed earlier in the branch).

Validation

• Run the unit suite. Prerequisites: repo root with pyproject.toml. Action: python3 -m pytest tests/unit/ -q -m "not perf". Expected: 584 tests pass, 0 failures. Then python3 -m pytest tests/unit/test_quest_artifact_postflight.py -q -m perf for the two latency tests (<50 ms typical and <200 ms stress).
• Run the hook shell tests. Action: bash tests/unit/test_branch_dir_context_hook.sh. Expected: 5 cases pass — git repo with a named branch, non-git directory, detached-HEAD, stdout format check, exit-0 guarantee.
• Exercise the hook live. Prerequisites: this branch checked out. Action: trigger any Edit or Write tool call (or run bash .claude/hooks/branch-dir-context.sh directly). Expected: one line [quest-context] branch=claude/review-intelligence-roadmap-i0my2 dir=/home/user/quest (or equivalent) printed to stdout. The wrapped tool call is unaffected.
• Exercise the validator. Prerequisites: the working tree. Action: python3 scripts/quest_artifact_postflight.py --quest-dir .quest/wrong-location-guardrails_2026-05-18__0003 --role planner --phase plan (substitute any role/phase). Expected: exit 0 (no mismatches against expected_artifacts_for_role). Then run with a fake declared artifact pointing outside .quest/: expected non-zero exit and a JSON record appended to .quest/wrong-location-guardrails_2026-05-18__0003/logs/path_compliance.log with reason: "outside_boundary".
• Verify workflow placement and cross-reference counts. Action: grep -n "quest_artifact_postflight" .skills/quest/delegation/workflow.md (expect the line to be after the "Three-tier fallback ladder" header at ~line 143) and grep -c "Handoff File Polling §5" .skills/quest/delegation/workflow.md (expect 6) and grep -c "Handoff File Polling\*\* §6" .skills/quest/delegation/workflow.md (expect 4).

Watch for: a customized .claude/settings.json in your install — the installer will not automatically merge the new PreToolUse Edit|Write entry into it. Pick up the new block from the .quest_updated sidecar by hand.

Notes

• Plan history: 3 plan iterations, 0 fix iterations. Reviewer B caught two real defects during planning — (1) the installer merge-carefully gap that would have shipped the hook to no one with a customized settings.json, and (2) the 10-cross-reference rot that mid-list step insertion would have caused in workflow.md. Both were verified empirically (line numbers, grep counts) before the arbiter ruled. Final iteration approved with 0 findings from both code reviewers.
• Validator wire-in is doc-only. No new Python module auto-invokes run(...). Orchestrators read the workflow doc and call the CLI. Auto-invocation is logged as a follow-up backlog item.
• Failure policy is accepted_with_warnings (non-halting). CLI exits non-zero, structured log persists, orchestrator surfaces a warning. Tighten to halting only once false-positive rate is empirically zero in the field.
• 3 deferred findings were appended to .quest/backlog/deferred_findings.jsonl for the next quest touching the postflight validator (docstring drift, fragile test heuristic, --quest-mode help-text polish).

     ▐▛███▜▌
    ▝▜█████▛▘
      ▘▘ ▝▝
Quest/Co-Authored by
Co-Authored-By: Claude Opus 4.7 
in collaboration with the repository author

---

Generated by Claude Code

[cubic-dev-ai]

6 issues found across 18 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".skills/quest/delegation/workflow.md">

<violation number="1" location=".skills/quest/delegation/workflow.md:184">
P2: The postflight example uses a generic `handoff.json` path that is incorrect for several role-specific handoff filenames.</violation>
</file>

<file name=".claude/hooks/branch-dir-context.sh">

<violation number="1" location=".claude/hooks/branch-dir-context.sh:20">
P2: Escape newlines in the working directory before printing; otherwise a valid path containing `\n`/`\r` breaks the hook's single-line stdout contract.</violation>
</file>

<file name="tests/unit/test_branch_dir_context_hook.sh">

<violation number="1" location="tests/unit/test_branch_dir_context_hook.sh:1">
P2: This test file is not wired into the repo’s test runner, so CI will never execute it. Add a shell-test step or convert it to a pytest module so the new coverage actually runs.</violation>
</file>

<file name="tests/unit/test_workflow_postflight_wireup.py">

<violation number="1" location="tests/unit/test_workflow_postflight_wireup.py:70">
P2: Scope this check to the actual postflight step, not any filename mention in the file.</violation>

<violation number="2" location="tests/unit/test_workflow_postflight_wireup.py:135">
P2: Don't end the scan on the first bold subheading; it truncates the artifact-preparation block early.</violation>
</file>

<file name="scripts/quest_artifact_postflight.py">

<violation number="1" location="scripts/quest_artifact_postflight.py:136">
P2: Catch `OSError`, `UnicodeDecodeError`, and `json.JSONDecodeError` when reading the handoff file, and ensure `data` is a dictionary before calling `.get()`. This avoids unhandled exceptions (e.g., `FileNotFoundError` or `AttributeError`) that could crash the postflight validator if the orchestrator text-fallback didn't write a valid JSON file.

(Based on your team's feedback about catching OSError and UnicodeDecodeError when reading UTF-8 files to avoid crashing quest completion.) [FEEDBACK_USED]</violation>
</file>

_{Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.
Re-trigger cubic}

[cubic-dev-ai]

2 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".ai/allowlist.json">

<violation number="1">
P2: This change introduces inconsistent model routing by switching several roles from `claude` to `gpt-5.5`, which conflicts with the stated allowlist pinning and can cause non-deterministic behavior across quest phases.</violation>
</file>

<file name="scripts/quest_artifact_postflight.py">

<violation number="1" location="scripts/quest_artifact_postflight.py:228">
P2: Comparing coverage with `Path.resolve()` lets a symlinked artifact satisfy multiple expected outputs, so an omitted canonical file can still pass validation.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic}

[cubic-dev-ai]

0 issues found across 5 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.
Re-trigger cubic}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: This PR adds two new guardrails (a PreToolUse hook and a post-invocation artifact validator) that run on every Edit/Write tool call and every sub-agent handoff, which touches critical runtime paths; the 2688-line change includes new scripts, workflow logic, and configuration that require human...
Re-trigger cubic}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/quest_artifact_postflight.py">

<violation number="1" location="scripts/quest_artifact_postflight.py:373">
P1: This early return skips validation for every non-current-quest path, so missing workspace files and sibling `.quest/` artifacts are silently accepted.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic}

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/quest_artifact_postflight.py">

<violation number="1" location="scripts/quest_artifact_postflight.py:384">
P2: Check for sibling-quest paths before the existence test so wrong-location writes are not downgraded to `missing`.</violation>

<violation number="2" location="scripts/quest_artifact_postflight.py:393">
P2: This `.quest` check is too broad: it will reject shared paths like `.quest/cache/...`, not just sibling quest directories.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: This PR modifies core orchestration workflow, hook configuration, and adds a new artifact validation script, all of which are high-impact changes that require human review to ensure correctness and avoid unintended side effects.
Re-trigger cubic}

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/quest_artifact_postflight.py">

<violation number="1" location="scripts/quest_artifact_postflight.py:416">
P1: In worktree mode, shared `.quest` paths (like `cache/` or `backlog/`) and sibling quest artifacts will incorrectly trigger a `traversal_outside_repo` mismatch because they are validated against `workspace_root` instead of `repo_root`.

(Based on your team's feedback about Non-current-quest path validation with shared .quest allowlist.) [FEEDBACK_USED]</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Auto-approved: These changes add two additive, non-halting guardrails—an observational pre-edit hook and an advisory artifact-path validator—backed by comprehensive tests, with no modifications to critical infrastructure, authentication, or core business logic, and the orchestrator treats any validator failure as
Re-trigger cubic}