repo-harness 0.1.3 → 0.1.4

package/AGENTS.md

@@ -21,7 +21,7 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 ## Operating Rules
 
 - Sync `tasks/` whenever substantive repo changes are made.
-- Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
 - Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.

package/CLAUDE.md

@@ -21,7 +21,7 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 ## Operating Rules
 
 - Sync `tasks/` whenever substantive repo changes are made.
-- Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
 - Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
 - Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.

package/README.md

@@ -77,9 +77,9 @@ flowchart TD
 
   Approve --> Project["Project plan into execution<br/>capture-plan.sh --execute<br/>or plan-to-todo.sh --plan"]
   Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
-  Project --> Contract["Sprint contract<br/>tasks/contracts/task-slug.contract.md"]
-  Project --> ReviewFile["Review file<br/>tasks/reviews/task-slug.review.md"]
-  Project --> Notes["Task notes<br/>tasks/notes/task-slug.notes.md"]
+  Project --> Contract["Sprint contract<br/>tasks/contracts/YYYYMMDD-HHMM-task-slug.contract.md"]
+  Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
+  Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
   Contract --> WorktreePolicy{"Contract worktree required?"}
   WorktreePolicy -->|yes| Checkout["Checkout isolated worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
@@ -121,12 +121,12 @@ npx -y repo-harness init
 ```
 
 The npm package release line is `0.1.x`; generated workflow compatibility is
-tracked separately as the `5.x` model line. The `0.1.3` package publishes the
+tracked separately as the `5.x` model line. The `0.1.4` package publishes the
 renamed `repo-harness` CLI, user-level Claude/Codex hook adapter bootstrap,
-AI-native scaffold overlays, the typed prompt-guard decision engine, Waza
-runtime skill sync, `diagram-design` sync, and the release gate used by
-maintainers before npm publish. When working from a source checkout instead of
-npm, run:
+AI-native scaffold overlays, the typed prompt-guard decision engine, plan-stem
+task artifact naming, Waza runtime skill sync, `diagram-design` sync, and the
+release gate used by maintainers before npm publish. When working from a source
+checkout instead of npm, run:
 
 ```bash
 git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
@@ -250,7 +250,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.1.3`
+- npm package: `repo-harness@0.1.4`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)

package/README.zh-CN.md

@@ -69,9 +69,9 @@ flowchart TD
 
   Approve --> Project["投射到执行面<br/>capture-plan.sh --execute<br/>或 plan-to-todo.sh --plan"]
   Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
-  Project --> Contract["Sprint contract<br/>tasks/contracts/task-slug.contract.md"]
-  Project --> ReviewFile["Review file<br/>tasks/reviews/task-slug.review.md"]
-  Project --> Notes["Task notes<br/>tasks/notes/task-slug.notes.md"]
+  Project --> Contract["Sprint contract<br/>tasks/contracts/YYYYMMDD-HHMM-task-slug.contract.md"]
+  Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
+  Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
   Contract --> WorktreePolicy{"是否需要 contract worktree?"}
   WorktreePolicy -->|是| Checkout["Checkout 隔离 worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
@@ -112,10 +112,10 @@ npx -y repo-harness init
 ```
 
 npm package release line 是 `0.1.x`；生成的 workflow compatibility model line
-单独以 `5.x` 追踪。`repo-harness@0.1.3` 发布的是改名后的 CLI、Claude/Codex
+单独以 `5.x` 追踪。`repo-harness@0.1.4` 发布的是改名后的 CLI、Claude/Codex
 user-level hook adapter bootstrap、AI-native scaffold overlays、typed prompt-guard
-decision engine、Waza runtime skill sync、`diagram-design` sync，以及 maintainer
-发布 npm 前使用的 release gate。
+decision engine、plan-stem task artifact 命名、Waza runtime skill sync、
+`diagram-design` sync，以及 maintainer 发布 npm 前使用的 release gate。
 
 如果从源码 checkout 工作：
 
@@ -235,7 +235,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.1.3`
+- npm package：`repo-harness@0.1.4`
 - Generated workflow compatibility：`5.2.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)

package/assets/hooks/lib/workflow-state.sh

@@ -275,7 +275,7 @@ get_todo_source_plan() {
   awk -F': ' '/^\> \*\*Source Plan\*\*:/ {print $2; exit}' tasks/todo.md | xargs
 }
 
-derive_contract_path() {
+workflow_plan_slug_from_path() {
   local plan_file="$1"
   local base slug
 
@@ -286,7 +286,43 @@ derive_contract_path() {
     return 1
   fi
 
-  printf 'tasks/contracts/%s.contract.md' "$slug"
+  printf '%s' "$slug"
+}
+
+workflow_plan_artifact_stem_from_path() {
+  local plan_file="$1"
+  local base stem
+
+  base="$(basename "$plan_file")"
+  stem="$(printf '%s' "$base" | sed -E 's/^plan-//; s/\.md$//')"
+  if [[ "$stem" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    printf '%s' "$stem"
+    return 0
+  fi
+
+  workflow_plan_slug_from_path "$plan_file"
+}
+
+workflow_preferred_or_legacy_path() {
+  local preferred="$1"
+  local legacy="$2"
+
+  if [[ -f "$preferred" ]] || [[ ! -f "$legacy" ]]; then
+    printf '%s' "$preferred"
+  else
+    printf '%s' "$legacy"
+  fi
+}
+
+derive_contract_path() {
+  local plan_file="$1"
+  local stem slug
+
+  stem="$(workflow_plan_artifact_stem_from_path "$plan_file" || true)"
+  slug="$(workflow_plan_slug_from_path "$plan_file" || true)"
+  [[ -n "$stem" && -n "$slug" ]] || return 1
+
+  workflow_preferred_or_legacy_path "tasks/contracts/${stem}.contract.md" "tasks/contracts/${slug}.contract.md"
 }
 
 workflow_plan_slug() {
@@ -296,7 +332,7 @@ workflow_plan_slug() {
     return 1
   fi
 
-  slug="$(basename "$active_plan" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
   if [[ -n "$slug" ]]; then
     printf '%s' "$slug"
     return 0
@@ -930,7 +966,7 @@ workflow_contract_slug() {
   local active_plan slug
   active_plan="$(get_active_plan || true)"
   [[ -n "$active_plan" ]] || return 1
-  slug="$(basename "$active_plan" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
   [[ -n "$slug" ]] || return 1
   printf '%s' "$slug"
 }
@@ -945,18 +981,25 @@ workflow_active_contract() {
 }
 
 workflow_active_review() {
-  local slug
-  slug="$(workflow_contract_slug || true)"
-  [[ -n "$slug" ]] || return 1
-  printf 'tasks/reviews/%s.review.md' "$slug"
+  local active_plan stem slug reviews_dir
+  active_plan="$(get_active_plan || true)"
+  [[ -n "$active_plan" ]] || return 1
+  stem="$(workflow_plan_artifact_stem_from_path "$active_plan" || true)"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
+  [[ -n "$stem" && -n "$slug" ]] || return 1
+  reviews_dir="$(workflow_repo_relative_path "$(workflow_policy_get '.tasks.reviews_dir' 'tasks/reviews')" 'tasks/reviews' 'tasks/')"
+  workflow_preferred_or_legacy_path "${reviews_dir}/${stem}.review.md" "${reviews_dir}/${slug}.review.md"
 }
 
 workflow_active_notes() {
-  local slug notes_dir
-  slug="$(workflow_contract_slug || true)"
-  [[ -n "$slug" ]] || return 1
+  local active_plan stem slug notes_dir
+  active_plan="$(get_active_plan || true)"
+  [[ -n "$active_plan" ]] || return 1
+  stem="$(workflow_plan_artifact_stem_from_path "$active_plan" || true)"
+  slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
+  [[ -n "$stem" && -n "$slug" ]] || return 1
   notes_dir="$(workflow_repo_relative_path "$(workflow_policy_get '.tasks.notes_dir' 'tasks/notes')" 'tasks/notes' 'tasks/')"
-  printf '%s/%s.notes.md' "$notes_dir" "$slug"
+  workflow_preferred_or_legacy_path "${notes_dir}/${stem}.notes.md" "${notes_dir}/${slug}.notes.md"
 }
 
 workflow_checks_file() {

package/assets/partials/07-footer.partial.md

@@ -14,9 +14,9 @@ CLAUDE.md is a routing card. Keep context minimal and load only what the current
 |---------|----------------|
 | Deep codebase investigation | `tasks/research.md` |
 | Active implementation planning | `plans/plan-*.md` |
-| Sprint done definition | `tasks/contracts/<slug>.contract.md` |
-| Evaluator verdict | `tasks/reviews/<slug>.review.md` |
-| Implementation notes | `tasks/notes/<slug>.notes.md` |
+| Sprint done definition | `tasks/contracts/<plan-stem>.contract.md` |
+| Evaluator verdict | `tasks/reviews/<plan-stem>.review.md` |
+| Implementation notes | `tasks/notes/<plan-stem>.notes.md` |
 | Latest verification evidence | `.ai/harness/checks/latest.json` |
 | Historical implementation context | `plans/archive/` and `tasks/archive/` |
 | Agentic skill routing | `docs/reference-configs/agentic-development-flow.md` |

package/assets/partials/08-orchestration.partial.md

@@ -36,7 +36,7 @@
 - Define per-sprint contract files in `tasks/contracts/`.
 - Verify contract exit criteria before claiming completion.
 - Require Waza `/check` to produce the matching evaluator review before any done/completed response.
-- Use `scripts/verify-contract.sh --contract tasks/contracts/{slug}.contract.md --strict`.
+- Use `scripts/verify-contract.sh --contract tasks/contracts/{plan-stem}.contract.md --strict`.
 
 ### 7. Balanced Elegance
 - Redesign hacky non-trivial fixes before shipping.

package/assets/partials-agents/04-task-protocol.partial.md

@@ -29,16 +29,16 @@ RULES:
   - Keep multiple active plans in parallel worktrees when tasks diverge; fill workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, runs, scope owner, switching rule, and worktree path
   - Process annotation notes before implementing
   - Extract approved plan tasks into tasks/todo.md
-  - Define task contracts in tasks/contracts/{slug}.contract.md
-  - Fill tasks/reviews/{slug}.review.md from Waza /check after verification
-  - Record only non-obvious implementation decisions, deviations, tradeoffs, and open questions in tasks/notes/{slug}.notes.md
+  - Define task contracts in tasks/contracts/{plan-stem}.contract.md
+  - Fill tasks/reviews/{plan-stem}.review.md from Waza /check after verification
+  - Record only non-obvious implementation decisions, deviations, tradeoffs, and open questions in tasks/notes/{plan-stem}.notes.md
   - Verify contracts before claiming completion
   - Require review pass before claiming completion
   - Keep tasks/todo.md limited to deferred medium/long-term goals, with tradeoff and revisit trigger; do not duplicate plan Task Breakdown
   - Record correction-derived prevention rules in tasks/lessons.md
   - Distill repeated corrections into tasks/lessons.md instead of keeping them in tasks/todo.md
   - Capture deep findings and hidden contracts in tasks/research.md
-  - Keep sprint-level verification notes, behavior diffs, and residual risks in tasks/reviews/{slug}.review.md
+  - Keep sprint-level verification notes, behavior diffs, and residual risks in tasks/reviews/{plan-stem}.review.md
   - Do not use implementation notes as durable memory or task logs; archive them on close and promote only after evidence shows the rule should outlive the sprint
   - Promote implementation-ready follow-up work into a new plans/plan-{timestamp}-{slug}.md file; keep deferred goals in tasks/todo.md only when intentionally postponed
   - Treat `.ai/hooks/` as the shared automation entrypoint when repo scripts reference hook-backed workflow checks

package/assets/partials-agents/06-quality-safety.partial.md

@@ -5,8 +5,8 @@
 - Run impact-based checks: typecheck, tests, lint/build.
 - Run `bash scripts/check-task-workflow.sh --strict` before claiming the workflow is clean.
 - Run `bash scripts/verify-contract.sh --contract <active-plan-contract> --strict` before any done/completed response when the active plan has a contract.
-- Require the matching `tasks/reviews/<slug>.review.md` to recommend pass before claiming completion.
-- Require the matching `tasks/notes/<slug>.notes.md` to capture material implementation decisions before review.
+- Require the matching `tasks/reviews/<plan-stem>.review.md` to recommend pass before claiming completion.
+- Require the matching `tasks/notes/<plan-stem>.notes.md` to capture material implementation decisions before review.
 
 ### Safety Rules
 - Do not silently expand scope beyond approved plan.

package/assets/reference-configs/evaluator-rubric.md

@@ -9,7 +9,7 @@
 
 ## Repo Role
 
-Keep pass/fail evidence in `tasks/reviews/<slug>.review.md` and
+Keep pass/fail evidence in `tasks/reviews/<plan-stem>.review.md` and
 `.ai/harness/checks/latest.json`. Use the external rubric for detailed scoring
 dimensions and review examples.
 

package/assets/reference-configs/harness-overview.md

@@ -5,18 +5,18 @@ This repo uses a shared long-running harness. The durable workflow lives in repo
 ## Roles
 
 - **Planner** updates `docs/spec.md`, researches constraints, and writes or approves `plans/plan-*.md`.
-- **Generator** implements only against the active sprint contract and the plan's `## Task Breakdown`, leaving `tasks/todo.md` as a deferred-goal ledger, and records task-local implementation judgments in `tasks/notes/<slug>.notes.md`.
-- **Evaluator** runs Waza `/check`, then writes `tasks/reviews/<slug>.review.md` using fresh evidence from `.ai/harness/checks/latest.json` and `.ai/harness/runs/*.json`.
+- **Generator** implements only against the active sprint contract and the plan's `## Task Breakdown`, leaving `tasks/todo.md` as a deferred-goal ledger, and records task-local implementation judgments in `tasks/notes/<plan-stem>.notes.md`.
+- **Evaluator** runs Waza `/check`, then writes `tasks/reviews/<plan-stem>.review.md` using fresh evidence from `.ai/harness/checks/latest.json` and `.ai/harness/runs/*.json`.
 
 ## State Flow
 
 1. `docs/spec.md` captures stable product intent.
 2. `plans/plan-*.md` captures a concrete execution approach.
-3. `tasks/contracts/<slug>.contract.md` defines done for the active sprint.
+3. `tasks/contracts/<plan-stem>.contract.md` defines done for the active sprint.
 4. `tasks/current.md` is a tracked mainline status snapshot derived from workflow artifacts; it is not a live lock, kanban board, or implementation gate.
 5. `tasks/todo.md` is the execution projection for the active sprint.
-6. `tasks/notes/<slug>.notes.md` records design decisions, deviations, tradeoffs, open questions, and promotion candidates for this sprint only.
-7. `tasks/reviews/<slug>.review.md` records evaluator judgment.
+6. `tasks/notes/<plan-stem>.notes.md` records design decisions, deviations, tradeoffs, open questions, and promotion candidates for this sprint only.
+7. `tasks/reviews/<plan-stem>.review.md` records evaluator judgment.
 8. `.ai/harness/policy.json` is the machine-readable workflow contract.
 9. `information_lifecycle` inside `.ai/harness/policy.json` separates notes, raw evidence, reusable assets, advisory memory, and external knowledge.
 10. `agentic_development` inside `.ai/harness/policy.json` captures product, engineering, design, bug-hunt, and review routing.
@@ -41,7 +41,7 @@ This repo uses a shared long-running harness. The durable workflow lives in repo
 - Use `docs/reference-configs/agentic-development-flow.md` for skill routing and `docs/reference-configs/external-tooling.md` for install/update commands.
 - Use `docs/reference-configs/global-working-rules.md` as the user-level Claude/Codex rule template; keep repo-local workflow contracts in repo files.
 - Externalized reference docs are indexed by `.ai/harness/brain-manifest.json` and checked by `scripts/check-brain-manifest.sh`. Valuable repo docs can opt into default-brain mirroring with `sync.direction=repo-to-brain`; `post-edit-guard.sh` then calls `scripts/sync-brain-docs.sh --changed <path>` for that specific file.
-- Contract-level execution should run in an isolated `codex/<task-slug>` worktree. Merge back only after the contract is fulfilled, `tasks/reviews/<slug>.review.md` recommends pass, and the target worktree is clean.
+- Contract-level execution should run in an isolated `codex/<task-slug>` worktree. Merge back only after the contract is fulfilled, `tasks/reviews/<plan-stem>.review.md` recommends pass, and the target worktree is clean.
 
 ## Documentation Profile
 
@@ -53,7 +53,7 @@ This repo uses a shared long-running harness. The durable workflow lives in repo
 
 ## Information Lifecycle
 
-- Notes: `tasks/notes/<slug>.notes.md` is task-local and auditable. It should not be treated as durable knowledge by default.
+- Notes: `tasks/notes/<plan-stem>.notes.md` is task-local and auditable. It should not be treated as durable knowledge by default.
 - Current status: `tasks/current.md` is a tracked derived snapshot for orientation only. It must be regenerated from source artifacts and must not contain hand-written kanban/checklist state.
 - Evidence: `.ai/harness/checks/latest.json` is the current gate, while `.ai/harness/runs/*.json` keeps immutable verification snapshots for later audit.
 - Memory: `tasks/research.md`, `tasks/lessons.md`, and gbrain are advisory. Current repo state and evidence override summaries.

package/assets/reference-configs/sprint-contracts.md

@@ -28,8 +28,8 @@ Sprint contracts are the repo-local agreement between planner, generator, and ev
 ## Review Coupling
 
 - A contract is not truly done until the matching review file records a passing recommendation.
-- `tasks/reviews/<slug>.review.md` should be filled from Waza `/check` after verification and cite the contract, implementation notes, checks file, run snapshot, `## External Acceptance Advice`, and any manual observations.
-- `tasks/notes/<slug>.notes.md` captures task-local decisions and should be archived or promoted deliberately, not left as hidden long-term memory.
+- `tasks/reviews/<plan-stem>.review.md` should be filled from Waza `/check` after verification and cite the contract, implementation notes, checks file, run snapshot, `## External Acceptance Advice`, and any manual observations.
+- `tasks/notes/<plan-stem>.notes.md` captures task-local decisions and should be archived or promoted deliberately, not left as hidden long-term memory.
 
 ## Worktree Lifecycle
 

package/assets/templates/contract.template.md

@@ -5,8 +5,8 @@
 > **Owner**: {{OWNER}}
 > **Capability ID**: {{CAPABILITY_ID}}
 > **Last Updated**: {{TIMESTAMP}}
-> **Review File**: `tasks/reviews/{{TASK_SLUG}}.review.md`
-> **Notes File**: `tasks/notes/{{TASK_SLUG}}.notes.md`
+> **Review File**: `{{REVIEW_FILE}}`
+> **Notes File**: `{{NOTES_FILE}}`
 
 ## Goal
 
@@ -21,8 +21,8 @@ Describe the exact outcome this task must deliver.
 
 - Source plan: `{{PLAN_FILE}}`
 - Deferred-goal ledger: `tasks/todo.md`
-- Review file: `tasks/reviews/{{TASK_SLUG}}.review.md`
-- Notes file: `tasks/notes/{{TASK_SLUG}}.notes.md`
+- Review file: `{{REVIEW_FILE}}`
+- Notes file: `{{NOTES_FILE}}`
 - Checks file: `.ai/harness/checks/latest.json`
 - Run snapshots: `.ai/harness/runs/`
 - Scope gate: edit only paths listed under `allowed_paths`; update this contract before widening scope.
@@ -35,9 +35,9 @@ allowed_paths:
   - docs/spec.md
   - plans/
   - tasks/todo.md
-  - tasks/contracts/{{TASK_SLUG}}.contract.md
-  - tasks/reviews/{{TASK_SLUG}}.review.md
-  - tasks/notes/{{TASK_SLUG}}.notes.md
+  - {{CONTRACT_FILE}}
+  - {{REVIEW_FILE}}
+  - {{NOTES_FILE}}
   - .ai/context/capabilities.json
   - src/
   - tests/
@@ -51,7 +51,7 @@ exit_criteria:
     - docs/spec.md
   artifacts_exist:
     - .ai/harness/checks/latest.json
-    - tasks/notes/{{TASK_SLUG}}.notes.md
+    - {{NOTES_FILE}}
   tests_pass:
     - path: tests/unit/{{TASK_SLUG}}.test.ts
   commands_succeed:

package/assets/templates/helpers/archive-workflow.sh

@@ -106,6 +106,7 @@ timestamp="$(date +%Y%m%d-%H%M)"
 timestamp_human="$(date '+%Y-%m-%d %H:%M')"
 plan_base="$(basename "$plan_file")"
 slug="$(echo "$plan_base" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+artifact_stem="$(printf '%s' "$plan_base" | sed -E 's/^plan-//; s/\.md$//')"
 parent_run_id="${HOOK_RUN_ID:-${CLAUDE_RUN_ID:-${CODEX_RUN_ID:-run-${timestamp}}}}"
 todo_source_plan="$(awk -F': ' '/^\> \*\*Source Plan\*\*:/ {print $2; exit}' tasks/todo.md 2>/dev/null | xargs)"
 
@@ -135,7 +136,10 @@ if [[ -f tasks/todo.md ]] && grep -q '[^[:space:]]' tasks/todo.md; then
   } > "$archive_todo"
 fi
 
-notes_file="tasks/notes/${slug}.notes.md"
+notes_file="tasks/notes/${artifact_stem}.notes.md"
+if [[ ! -f "$notes_file" && -f "tasks/notes/${slug}.notes.md" ]]; then
+  notes_file="tasks/notes/${slug}.notes.md"
+fi
 if [[ -f "$notes_file" ]]; then
   archive_notes="$(unique_archive_path "tasks/archive/notes-${timestamp}-${slug}.md")"
   {

package/assets/templates/helpers/capture-plan.sh

@@ -180,6 +180,7 @@ while [[ -f "$plan_file" ]]; do
   plan_file="plans/plan-${timestamp}-${slug}-v${counter}.md"
   counter=$((counter + 1))
 done
+artifact_stem="$(basename "$plan_file" .md | sed -E 's/^plan-//')"
 
 tasks="$(extract_task_breakdown "$body" || true)"
 if [[ -z "$tasks" ]]; then
@@ -197,9 +198,9 @@ cat > "$plan_file" <<PLAN_EOF
 > **Source Ref**: ${source_ref:-"(none)"}
 > **Spec**: \`docs/spec.md\`
 > **Research**: See \`tasks/research.md\`
-> **Sprint Contract**: \`tasks/contracts/${slug}.contract.md\`
-> **Sprint Review**: \`tasks/reviews/${slug}.review.md\`
-> **Implementation Notes**: \`tasks/notes/${slug}.notes.md\`
+> **Sprint Contract**: \`tasks/contracts/${artifact_stem}.contract.md\`
+> **Sprint Review**: \`tasks/reviews/${artifact_stem}.review.md\`
+> **Implementation Notes**: \`tasks/notes/${artifact_stem}.notes.md\`
 
 ## Agentic Routing
 - Selected route: ${route}
@@ -214,13 +215,13 @@ cat > "$plan_file" <<PLAN_EOF
 Complete this inventory before implementation. If any line is unknown, keep the plan in Draft and fill it before projection.
 
 - Active plan: \`${plan_file}\`
-- Sprint contract: \`tasks/contracts/${slug}.contract.md\`
-- Sprint review: \`tasks/reviews/${slug}.review.md\`
-- Implementation notes: \`tasks/notes/${slug}.notes.md\`
+- Sprint contract: \`tasks/contracts/${artifact_stem}.contract.md\`
+- Sprint review: \`tasks/reviews/${artifact_stem}.review.md\`
+- Implementation notes: \`tasks/notes/${artifact_stem}.notes.md\`
 - Deferred-goal ledger: \`tasks/todo.md\`
 - Current checks: \`.ai/harness/checks/latest.json\`
 - Run snapshots: \`.ai/harness/runs/\`
-- Scope authority: \`tasks/contracts/${slug}.contract.md\` \`allowed_paths\`
+- Scope authority: \`tasks/contracts/${artifact_stem}.contract.md\` \`allowed_paths\`
 - Concurrency rule: \`.ai/harness/active-plan\` selects the active plan for this worktree when present; \`.ai/harness/active-worktree\` records the owning worktree; \`.claude/.active-plan\` is a legacy fallback during transition. If another worktree already owns active work, open or switch to the matching worktree instead of serializing unrelated plans.
 - Execution isolation: approved contract-level work projects through \`scripts/plan-to-todo.sh --plan ${plan_file}\` and may start \`scripts/contract-worktree.sh start --plan ${plan_file}\`.
 
@@ -251,11 +252,11 @@ See captured planning output.
 | Captured plan lacks enough detail | Medium | Execution may need clarification | Stop before implementation if the captured output contradicts repo rules or lacks concrete file targets |
 
 ## Task Contracts
-- Contract file: \`tasks/contracts/${slug}.contract.md\`
-- Review file: \`tasks/reviews/${slug}.review.md\`
-- Implementation notes file: \`tasks/notes/${slug}.notes.md\`
+- Contract file: \`tasks/contracts/${artifact_stem}.contract.md\`
+- Review file: \`tasks/reviews/${artifact_stem}.review.md\`
+- Implementation notes file: \`tasks/notes/${artifact_stem}.notes.md\`
 - Template: \`.claude/templates/contract.template.md\`
-- Verification command: \`bash scripts/verify-contract.sh --contract tasks/contracts/${slug}.contract.md --strict\`
+- Verification command: \`bash scripts/verify-contract.sh --contract tasks/contracts/${artifact_stem}.contract.md --strict\`
 - Active plan rule: this captured plan is written to \`.ai/harness/active-plan\`, the owning worktree is written to \`.ai/harness/active-worktree\`, and the plan is mirrored to \`.claude/.active-plan\` unless --no-active is used. Do not infer active execution from the latest non-archived plan.
 
 ## Handoff
@@ -265,9 +266,9 @@ See captured planning output.
 
 ## Evidence Contract
 
-- **State/progress path**: \`${plan_file}\` task breakdown, \`tasks/todo.md\` deferred-goal ledger, \`tasks/contracts/${slug}.contract.md\`, \`tasks/reviews/${slug}.review.md\`, and \`tasks/notes/${slug}.notes.md\`
+- **State/progress path**: \`${plan_file}\` task breakdown, \`tasks/todo.md\` deferred-goal ledger, \`tasks/contracts/${artifact_stem}.contract.md\`, \`tasks/reviews/${artifact_stem}.review.md\`, and \`tasks/notes/${artifact_stem}.notes.md\`
 - **Verification evidence**: \`.ai/harness/checks/latest.json\`, \`.ai/harness/runs/\`, and the commands named in the captured planning output
-- **Evaluator rubric**: \`tasks/reviews/${slug}.review.md\` must record a passing Waza /check style recommendation
+- **Evaluator rubric**: \`tasks/reviews/${artifact_stem}.review.md\` must record a passing Waza /check style recommendation
 - **Stop condition**: all task breakdown items are complete, sprint verification passes, and the review recommends pass
 - **Rollback surface**: before execution remove \`${plan_file}\`; after execution revert branch \`codex/${slug}\` or the generated task artifacts
 

package/assets/templates/helpers/codex-handoff-resume.sh

@@ -100,23 +100,55 @@ latest_plan() {
   find plans -maxdepth 1 -type f -name 'plan-*.md' 2>/dev/null | sort | tail -1
 }
 
+plan_slug_from_path() {
+  local plan_file="$1"
+  local base slug
+  base="$(basename "$plan_file")"
+  slug="$(printf '%s' "$base" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+  printf '%s' "$slug"
+}
+
+plan_artifact_stem_from_path() {
+  local plan_file="$1"
+  local base stem
+  base="$(basename "$plan_file")"
+  stem="$(printf '%s' "$base" | sed -E 's/^plan-//; s/\.md$//')"
+  if [[ "$stem" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    printf '%s' "$stem"
+  else
+    plan_slug_from_path "$plan_file"
+  fi
+}
+
+preferred_or_legacy_path() {
+  local preferred="$1"
+  local legacy="$2"
+  if [[ -f "$preferred" ]] || [[ ! -f "$legacy" ]]; then
+    printf '%s' "$preferred"
+  else
+    printf '%s' "$legacy"
+  fi
+}
+
 derive_contract() {
   local plan_file="$1"
-  local slug
+  local slug stem
   [[ -n "$plan_file" ]] || return 1
-  slug="$(basename "$plan_file" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
-  [[ -n "$slug" ]] || return 1
-  printf 'tasks/contracts/%s.contract.md' "$slug"
+  slug="$(plan_slug_from_path "$plan_file")"
+  stem="$(plan_artifact_stem_from_path "$plan_file")"
+  [[ -n "$slug" && -n "$stem" ]] || return 1
+  preferred_or_legacy_path "tasks/contracts/${stem}.contract.md" "tasks/contracts/${slug}.contract.md"
 }
 
 derive_notes() {
   local plan_file="$1"
-  local slug notes_dir
+  local slug stem notes_dir
   [[ -n "$plan_file" ]] || return 1
-  slug="$(basename "$plan_file" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
-  [[ -n "$slug" ]] || return 1
+  slug="$(plan_slug_from_path "$plan_file")"
+  stem="$(plan_artifact_stem_from_path "$plan_file")"
+  [[ -n "$slug" && -n "$stem" ]] || return 1
   notes_dir="$(safe_repo_file "$(policy_get '.tasks.notes_dir' 'tasks/notes')" 'tasks/notes' 'tasks/')"
-  printf '%s/%s.notes.md' "$notes_dir" "$slug"
+  preferred_or_legacy_path "${notes_dir}/${stem}.notes.md" "${notes_dir}/${slug}.notes.md"
 }
 
 latest_global_handoff() {

package/assets/templates/helpers/contract-worktree.sh

@@ -61,6 +61,18 @@ derive_slug_from_plan() {
   normalize_slug "${slug:-contract-task}"
 }
 
+derive_artifact_stem_from_plan() {
+  local plan_file="$1"
+  local plan_base stem
+  plan_base="$(basename "$plan_file")"
+  stem="$(printf '%s' "$plan_base" | sed -E 's/^plan-//; s/\.md$//')"
+  if [[ "$stem" =~ ^[0-9]{8}-[0-9]{4}-.+ ]]; then
+    printf '%s' "$stem"
+  else
+    derive_slug_from_plan "$plan_file"
+  fi
+}
+
 is_linked_worktree() {
   local git_dir
   git_dir="$(git rev-parse --git-dir 2>/dev/null || true)"
@@ -381,7 +393,7 @@ finish_worktree() {
     exit 1
   fi
 
-  local current_branch slug active_plan contract_file review_file target_worktree
+  local current_branch slug active_plan contract_file review_file target_worktree artifact_stem
   local external_status external_state external_reviewer external_source external_message
   current_branch="$(git branch --show-current)"
   [[ -n "$current_branch" ]] || { echo "contract-worktree: detached HEAD is not supported" >&2; exit 1; }
@@ -402,6 +414,18 @@ finish_worktree() {
   if [[ -z "${active_plan:-}" ]]; then
     active_plan="$(latest_plan_for_slug "$slug" || true)"
   fi
+  if [[ -n "${active_plan:-}" && -z "${contract_file:-}" ]]; then
+    artifact_stem="$(derive_artifact_stem_from_plan "$active_plan")"
+    if [[ -f "tasks/contracts/${artifact_stem}.contract.md" ]] || [[ ! -f "tasks/contracts/${slug}.contract.md" ]]; then
+      contract_file="tasks/contracts/${artifact_stem}.contract.md"
+    fi
+  fi
+  if [[ -n "${active_plan:-}" && -z "${review_file:-}" ]]; then
+    artifact_stem="${artifact_stem:-$(derive_artifact_stem_from_plan "$active_plan")}"
+    if [[ -f "tasks/reviews/${artifact_stem}.review.md" ]] || [[ ! -f "tasks/reviews/${slug}.review.md" ]]; then
+      review_file="tasks/reviews/${artifact_stem}.review.md"
+    fi
+  fi
   contract_file="${contract_file:-tasks/contracts/${slug}.contract.md}"
   review_file="${review_file:-tasks/reviews/${slug}.review.md}"