[System] Task-spec allowed_paths schema: per-task file-scope enforcement

Goal

Extend the Orchestra pre-push hook with a new Check 6 that enforces per-task file scoping based on an allowed_paths field in task spec frontmatter. Workers declare intent up front; the hook rejects commits that accidentally drift outside the declared scope.

Background

The 2026-04-11 stale-worktree clobber incident showed that workers can accidentally roll back unrelated files (api.py, etc.) via git add -A on stale worktrees. The pre-push hook (Check 5) already blocks commits that touch critical files without naming them. This task adds precise, per-task file-scope enforcement:

• Each task spec declares allowed_paths (list of glob patterns)
• Default scope derived from [Layer] prefix
• Hook reads the task's spec from the push commit itself and validates the diff

Default Scope by Layer

Layer prefix	Default allowed_paths globs
[Agora]	agora/, docs/agora/, tests/agora/**
[Exchange]	exchange/, docs/exchange/, tests/exchange/**
[Forge]	forge/, tools/, docs/forge/, tests/forge/
[Atlas]	atlas/, wiki/, docs/atlas/**
[Senate]	senate/, docs/senate/, tests/senate/**
[UI]	site/, static/, docs/ui/**
[System]	orchestra/, .claude/, docs/system/**

Tasks about core infrastructure can opt into broader scope via explicit --allowed-paths.

Spec Frontmatter Schema

---
task_id: fc395b8d-c9a7-43d5-bc3a-a9f98892f879
title: "[Atlas] ..."
allowed_paths:
  - "atlas/**"
  - "wiki/**"
  - "docs/atlas/**"
---

If allowed_paths is absent, the layer-default applies.

Acceptance Criteria

Implementation Plan

1. Spec file format

Add allowed_paths (list of glob strings) to spec frontmatter. No change to existing spec files that omit it — layer-default applies.

2. CLI changes (orchestra_cli.py)

• Add --allowed-paths flag to cmd_create(): accepts space-separated glob pattern string
• Write allowed_paths list to auto-generated spec file frontmatter
• No DB schema change needed (spec_path column already links task ↔ spec file)

3. Layer-default map

LAYER_DEFAULT_PATHS = {
    "agora":   ["agora/**", "docs/agora/**", "tests/agora/**"],
    "exchange": ["exchange/**", "docs/exchange/**", "tests/exchange/**"],
    "forge":   ["forge/**", "tools/**", "docs/forge/**", "tests/forge/**"],
    "atlas":   ["atlas/**", "wiki/**", "docs/atlas/**"],
    "senate":  ["senate/**", "docs/senate/**", "tests/senate/**"],
    "ui":      ["site/**", "static/**", "docs/ui/**"],
    "system":  ["orchestra/**", ".claude/**", "docs/system/**"],
}

If task has no [Layer] prefix and no explicit allowed_paths, allow all (*).

4. Pre-push hook Check 6

In _pre_push_hook() (hooks.py), add after Check 5:

# ── Check 6: Per-task allowed_paths enforcement ───────────────
# Extract task IDs from commit messages in the push range.
# For each task, read its spec from the push commit (git show <sha>:<spec_path>)
# and validate that all changed files match the allowed_paths globs.

Implementation steps in bash:

Loop over commits in $remote_sha..$local_sha

Extract task IDs via grep -oP '\[task:\K[^]]+'

For each task ID, find the spec file path from the commit's files (git show <sha> --name-only --diff-filter=)

Read spec content via git show <sha>:<spec_path>

Parse allowed_paths from YAML frontmatter (Python one-liner)

For each file in the commit's diff, check against globs via Python fnmatch

If any file is outside all globs → BLOCK

5. Glob matching utility

Python fnmatch is sufficient for shell integration. Example:

from fnmatch import fnmatch
def allowed(path, patterns): return any(fnmatch(path, p) for p in patterns)

6. Override

Set ORCHESTRA_SKIP_ALLOWED_PATHS=1 in environment to bypass Check 6 (same pattern as existing ORCHESTRA_SKIP_CRITICAL_CHECK).

Dependencies

• Pre-existing: orchestra_cli.py, hooks.py, spec files at docs/planning/specs/
• No new dependencies

Files to Modify

orchestra/hooks.py — add Check 6 to _pre_push_hook()

scripts/orchestra_cli.py — add --allowed-paths flag to cmd_create()

No migration needed (spec files are git-tracked, no DB schema change)

Work Log

2026-04-17 10:50 PT — Slot minimax:65 (reopen — completed)

• Confirmed Check 6 and validate_allowed_paths.py are on origin/main (main == d7754ecc0).
• Two acceptance criteria remained incomplete: unit tests + integration tests.
• Added unit tests (32 tests covering path_allowed, LAYER_DEFAULT_PATHS, extract_layer_prefix, extract_allowed_paths).
• Added integration tests (4 tests exercising full hook flow with temp git repos).
• Fixed two bugs found while writing tests:

1. extract_allowed_paths didn't strip quotes around glob patterns (e.g. "atlas/" → unquoted atlas/).
2. extract_layer_prefix regex didn't handle quoted title values (title: "[Atlas] ...").

• All 36 tests pass. Committed and pushed: 681b2ed58.
• Investigated prior orphan branch situation. The e91daa7be commit (Check 6) was never on main due to failed push. The validate_allowed_paths.py and spec file DID land on main (dbd4a8c46, c7ccb4cf1).
• Main hooks/pre-push is currently Check 5 only (model provenance) — missing Check 6.
• scripts/validate_allowed_paths.py exists on main but lacks --files argument needed by pre-push hook.
• Implemented Check 6 by updating hooks/pre-push and adding --files arg to validate script.
• Updated spec acceptance criteria to reflect completed work.

2026-04-12 — Slot minimax:61

• Read AGENTS.md, Orchestra/AGENTS.md, hooks.py, orchestra_cli.py, services.py
• Understood task scope: add allowed_paths to spec frontmatter, CLI flag, and pre-push hook Check 6
• Creating spec file at docs/planning/specs/fc395b8d_c9a_spec.md

Tasks using this spec (1)

[System] Task-spec allowed_paths schema: per-task file-scope

File: fc395b8d_c9a_spec.md

Modified: 2026-05-01 20:13

Size: 6.7 KB