From 42049c8bbc723bf2ac6d3ec1142ded8a12cae325 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:03:04 +1000 Subject: [PATCH 01/26] chore(porch): 909 init pir --- .../status.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 codev/projects/909-architect-treat-area-labels-as/status.yaml diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml new file mode 100644 index 00000000..6960317a --- /dev/null +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -0,0 +1,18 @@ +id: '909' +title: architect-treat-area-labels-as +protocol: pir +phase: plan +plan_phases: [] +current_plan_phase: null +gates: + plan-approval: + status: pending + dev-approval: + status: pending + pr: + status: pending +iteration: 1 +build_complete: false +history: [] +started_at: '2026-05-28T05:03:04.695Z' +updated_at: '2026-05-28T05:03:04.695Z' From aece8c03c765c68731e6f4a2ff3abc748c34e08d Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:06:00 +1000 Subject: [PATCH 02/26] [PIR #909] Plan draft --- .../909-architect-treat-area-labels-as.md | 183 ++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 codev/plans/909-architect-treat-area-labels-as.md diff --git a/codev/plans/909-architect-treat-area-labels-as.md b/codev/plans/909-architect-treat-area-labels-as.md new file mode 100644 index 00000000..9d34c683 --- /dev/null +++ b/codev/plans/909-architect-treat-area-labels-as.md @@ -0,0 +1,183 @@ +# PIR Plan: Document `area/*` labels as architect's primary issue-organizing axis + +## Understanding + +Issue #909 asks for standing architect documentation on the `area/*` label convention so that any fresh session — in this repo or in an adopter's repo — can group, edit, audit, and bulk-move issues without re-discovering (or mis-applying) the convention. Today the rules live only in the labels themselves, in existing issue bodies, and in per-session memory; a new chat window has none of that context. + +The work is *two coordinated doc updates*: + +1. **codev's own `CLAUDE.md` + `AGENTS.md`** — concrete label vocabulary, policy rules, and `gh` recipes. Must stay byte-identical (per the existing sync rule). +2. **`codev-skeleton/templates/CLAUDE.md` + `templates/AGENTS.md` + `roles/architect.md`** — *framework-neutral* version. No mention of codev's specific area names; teaches the pattern, not the vocabulary (per the `framework-neutral-on-label-semantics` discipline). + +Live label inventory (confirmed via `gh label list --search area/` on 2026-05-28): + +| Label | Scope | +|---|---| +| `area/docs` | Documentation (this repo, CLAUDE/AGENTS, role files, resources) | +| `area/vscode` | VSCode extension (sidebar views, commands, keybindings) | +| `area/panel` | Codev panel/dashboard webview | +| `area/consult` | Consult CLI and consultation tooling | +| `area/tower` | Tower server + `afx`/agent-farm CLI (no separate `area/agent-farm`) | +| `area/cross-cutting` | Multi-area work (used alone, never alongside another `area/*`) | +| `area/porch` | Porch state machine / protocol orchestration | +| `area/config` | `.codev/config.json` and workspace setup | +| `area/terminal` | Terminal-specific (PTY, vscode terminal pane) | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`) | + +Policy rules already in personal memory but undocumented in repo: + +- Exactly one `area/*` per issue; multi-area work uses `area/cross-cutting` *alone*. +- No `type:*` labels (codev uses areas only). +- `area/` uses slash; other label families would keep colon — but only `area/*` is in active use. +- `gh issue create` invocations include `--assignee @me`. + +## Proposed Change + +Add a new section titled **"Area Labels — the organizing axis for issues"** to: + +1. `CLAUDE.md` and `AGENTS.md` (codev root) +2. `codev-skeleton/templates/CLAUDE.md` and `codev-skeleton/templates/AGENTS.md` +3. `codev-skeleton/roles/architect.md` + +### Design decisions (these are the calls that want plan-approval) + +**1. Placement in `CLAUDE.md`/`AGENTS.md`.** Insert directly after the existing `### Project Tracking` subsection (currently lines 110–130, ending before `### 🚨 CRITICAL: Two human approval gates...`). That subsection already establishes "GitHub Issues are the source of truth for project tracking"; area labels are the *axis* on which those issues are organized, so the topical adjacency is exact. Keeping it under `## Quick Start` (the top of the doc) maximizes discoverability — well above `## Git Workflow` (line 579), which is too deep for first-encounter material a fresh session needs. + +**2. Granularity of per-label scope hints.** Render the label vocabulary as a **two-column mini-table** (label / one-line scope hint) — the same 10-row table shown in "Understanding" above. Rationale: a table is more scannable than a bulleted paragraph, makes future additions a one-line append, and keeps the section's vertical footprint to ~20 lines. Rejected alternatives: bulleted list (less scannable), paragraph per area (too verbose for an at-a-glance reference), or examples-only (forces the reader to infer the pattern). + +**3. Codev file vs. skeleton file split — the vocabulary boundary.** The codev file lists the concrete 10 labels inline (it is the source of truth for *this* repo). The skeleton file lists **zero** concrete label values — it teaches *how to discover and reason about* whatever label scheme an adopter uses (`gh label list`, infer from existing issues, confirm before bulk changes). This honors the existing `framework-neutral-on-label-semantics` discipline. Without this split the skeleton would silently push codev's vocabulary onto adopters who organize work by `team/*` or `priority/*` instead. + +**4. Live list inline vs. pointer.** Both, in the codev file: the table is inline (zero-friction starting vocabulary for a fresh session) *and* the section closes with `gh label list --search area/` as the authoritative source if anything looks wrong or stale. The skeleton file ships **only** the pointer, since it has no canonical vocabulary to mirror. The staleness risk of the inline table is bounded — adding/removing an area is a rare deliberate event that already touches multiple repo files; the table just gets one more line. + +**5. `gh` recipe set.** Include the four canonical operations the issue enumerates — group, edit, audit, bulk-move — as a one-line recipe each (8–10 lines total). Examples drawn from the issue's use-case list. Same recipes appear in the codev file (concrete: `area/tower`, etc.) and in the skeleton file (abstract: `/` placeholders). + +**6. `codev-skeleton/roles/architect.md` placement.** Add as a new top-level section titled **"Working with project labels"**, placed immediately after `## Project Tracking` (line 247) and before `## Handling Blocked Builders` (line 262). Mirrors the codev-file placement choice: project tracking → label-as-organizing-axis. The role doc gets the same framework-neutral phrasing as the skeleton's CLAUDE/AGENTS templates (no codev vocabulary). + +### Section content (concrete preview, codev's CLAUDE.md/AGENTS.md) + +```markdown +### Area Labels — the organizing axis for issues + +`area/*` is the **primary axis** for organizing GitHub Issues in this repo. +When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as +the grouping dimension first — not `type:*` (we don't use them), not +milestones, not assignees. + +**Live vocabulary** (run `gh label list --search area/` to confirm): + +| Label | Scope | +|---|---| +| `area/docs` | Documentation, CLAUDE/AGENTS, role files, resources | +| `area/vscode` | VSCode extension (sidebar views, commands, keybindings) | +| `area/panel` | Codev panel / dashboard webview | +| `area/consult` | Consult CLI and consultation tooling | +| `area/tower` | Tower server + `afx`/agent-farm CLI (no `area/agent-farm`) | +| `area/cross-cutting` | Multi-area work (used **alone**, never alongside another `area/*`) | +| `area/porch` | Porch state machine / protocol orchestration | +| `area/config` | `.codev/config.json` and workspace setup | +| `area/terminal` | Terminal-specific (PTY, VSCode terminal pane) | +| `area/core` | Shared core library / forge abstraction | + +**Policy:** + +- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. +- **No `type:*` labels.** Codev classifies issues by area only. +- `area/` uses **slash** (Kubernetes/Terraform convention). Other label families (if ever introduced) would keep colons. +- All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. + +**Operational recipes:** + +```bash +# Group: list open issues by area +gh issue list --state open --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' + +# Edit: change area on a single issue +gh issue edit --remove-label area/old --add-label area/new + +# Audit: find open issues with no area label +gh issue list --state open --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("area/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open `area/X` issues to `area/Y` +for n in $(gh issue list --state open --label area/old --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label area/old --add-label area/new +done +``` + +When in doubt, run `gh label list --search area/` — it is the source of truth. +``` + +### Section content (skeleton, framework-neutral) + +The skeleton variant uses placeholder vocabulary throughout (`/`, `/*`) and opens with the phrasing the issue suggests: + +> If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes. + +Followed by: + +- `gh label list` discovery recipe. +- Abstract policy ("conventions vary — common patterns include one-label-per-axis, dedicated multi-prefix fallbacks like `area/cross-cutting`, etc. Confirm with the user before bulk operations"). +- The same four recipe shapes (group/edit/audit/bulk-move) with `` placeholders instead of `area/`. + +## Files to Change + +- `CLAUDE.md` — insert new `### Area Labels — the organizing axis for issues` subsection after the `### Project Tracking` block ending around line 130 (before the "🚨 CRITICAL: Two human approval gates" block). +- `AGENTS.md` — apply the **byte-identical** insertion. Verify with `diff CLAUDE.md AGENTS.md` (must be empty after the edit). +- `codev-skeleton/templates/CLAUDE.md` — insert framework-neutral subsection. Current file is short (122 lines, ends with "For More Info"); best placement is after the existing `## Key Locations` section (line 41) and before `## Quick Start`, or as a new top-level `## Working with Project Labels` section before `## Git Workflow` (note: the skeleton template doesn't have a `## Git Workflow` heading — final placement TBD at implement time, anchored to whatever puts it adjacent to project-tracking-style content). +- `codev-skeleton/templates/AGENTS.md` — byte-identical insertion. Verify diff is empty (except for the existing header / "AGENTS.md standard" preamble difference). +- `codev-skeleton/roles/architect.md` — new `## Working with project labels` section after `## Project Tracking` (currently line 247), before `## Handling Blocked Builders` (line 262). + +No code, no tests, no protocol-spec changes. Pure documentation. + +## Risks & Alternatives Considered + +**Risk: inline label list goes stale.** Mitigated by (a) low churn rate — adding/renaming an area is rare and already touches multiple files, and (b) the closing pointer to `gh label list --search area/` makes the live list one command away. If staleness becomes a real problem we'd add a MAINTAIN-protocol audit step; deferred until needed. + +**Risk: the framework-neutral skeleton phrasing leaks codev vocabulary.** Mitigated by code review at PR time and by deliberately keeping the codev file (with vocabulary) and the skeleton file (without) in *different directories* — the diff should make any leak obvious. The `framework-neutral-on-label-semantics` rule is the explicit guard. + +**Risk: CLAUDE.md ↔ AGENTS.md drift.** Mitigated by running `diff CLAUDE.md AGENTS.md` as part of the test plan; same for the skeleton pair (modulo the existing 4-line preamble difference, which is the only intentional divergence). + +**Alternative considered: top-level `## Area Labels` section near the top of CLAUDE.md.** Rejected because subsection-under-Quick-Start keeps the section *adjacent to* the related Project Tracking content, which is more discoverable for someone scanning headings to find "where are issues organized" than yet another top-level heading among the existing 18. + +**Alternative considered: bulleted list instead of mini-table for the label vocabulary.** Rejected as less scannable; the mini-table puts label and scope on the same line for instant visual matching. + +**Alternative considered: drop the inline label list, just point to `gh label list --search area/`.** Rejected because the whole point is *zero-memory* operability — a fresh session must be able to pick the right area for "file an issue for X" without first running a discovery command. The pointer is for verification, not first-touch. + +**Alternative considered: a separate `codev/resources/area-labels.md` reference doc with `CLAUDE.md` linking to it.** Rejected — the issue explicitly asks for it to land *in* `CLAUDE.md` and `AGENTS.md` so it loads into the agent's context automatically. A separate file would defeat the no-memory-dependence acceptance criterion (the agent would have to know to read it). + +## Test Plan + +This is a doc-only change, so the test plan is **review-driven** rather than build-driven. At the `dev-approval` gate the reviewer should: + +1. **Byte-identical files check** — + ```bash + diff CLAUDE.md AGENTS.md # empty + diff codev-skeleton/templates/CLAUDE.md codev-skeleton/templates/AGENTS.md # only the 4-line preamble + ``` + +2. **Vocabulary leak check** — confirm the skeleton files contain **zero** instances of codev's actual area names: + ```bash + grep -E "area/(docs|vscode|panel|consult|tower|cross-cutting|porch|config|terminal|core)" \ + codev-skeleton/templates/CLAUDE.md \ + codev-skeleton/templates/AGENTS.md \ + codev-skeleton/roles/architect.md + # Expected: no output + ``` + +3. **`gh` recipe smoke test** — run each recipe against the live repo and confirm output is reasonable: + - Group: produces a tally per area. + - Audit: returns issues without `area/*` (currently this may include legacy issues — that's fine, the recipe is what's being tested). + - Edit: dry-run conceptually (don't actually relabel anything for the test). + - Bulk-move: dry-run conceptually. + +4. **Cold-session readability check** (the killer acceptance test from the issue) — open a fresh Claude chat in this repo, paste each of these and confirm the architect responds with the right `gh` command without further prompting: + - "Show me my open issues grouped by area." + - "Change the area on #872 from `area/porch` to `area/tower`." + - "Which open issues have no area label?" + - "All open `area/core` issues should move to `area/tower` — do the relabel." + - "File an issue for X." (architect picks the right area without asking) + +5. **Markdown rendering check** — render `CLAUDE.md` in VSCode preview and confirm the table layout doesn't break. + +No unit tests, no build steps, no cross-platform concerns. The 3-way consult at the `pr` gate is the only AI review pass. From 86ce5974a6da8def6dffa489a989f969c3c2cb9e Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:06:24 +1000 Subject: [PATCH 03/26] [PIR #909] Add builder thread --- codev/state/pir-909_thread.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 codev/state/pir-909_thread.md diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md new file mode 100644 index 00000000..75823dee --- /dev/null +++ b/codev/state/pir-909_thread.md @@ -0,0 +1,16 @@ +# PIR #909 — area/* labels as first-class organizing concept + +## 2026-05-28 — plan phase + +Drafted `codev/plans/909-architect-treat-area-labels-as.md`. Key design calls made (these are the items the plan-approval gate is for): + +- **Placement**: subsection under `## Quick Start`, directly after `### Project Tracking`. Topical adjacency > another top-level heading. +- **Vocabulary rendering**: mini-table (label / one-line scope), 10 rows. Bulleted list and paragraph-per-area rejected. +- **Codev / skeleton split**: codev file has the concrete 10-label table inline; skeleton files contain zero codev area names (framework-neutral discipline). Skeleton teaches the pattern via `/` placeholders. +- **Live list inline + pointer**: codev file has both (inline table for zero-memory ops, `gh label list --search area/` as the source of truth). Skeleton has only the pointer. +- **gh recipes**: group / edit / audit / bulk-move, one-liner each, ~10 lines total. Same shape in codev and skeleton, different vocabulary level. +- **`codev-skeleton/roles/architect.md`**: new `## Working with project labels` section after `## Project Tracking`. + +Live label inventory captured from `gh label list --search area/` (10 labels). No mention of `area/agent-farm` — `area/tower` covers afx/agent-farm work (confirmed already in personal memory and consistent with the issue body). + +Awaiting `plan-approval`. From 9dfe4f28f5a1792a3e858ac85374ca251c56b821 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:06:26 +1000 Subject: [PATCH 04/26] chore(porch): 909 plan-approval gate-requested --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 6960317a..22f2a1a5 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -7,6 +7,7 @@ current_plan_phase: null gates: plan-approval: status: pending + requested_at: '2026-05-28T05:06:26.853Z' dev-approval: status: pending pr: @@ -15,4 +16,4 @@ iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T05:03:04.695Z' +updated_at: '2026-05-28T05:06:26.853Z' From f2970e3970351d1959e80f98ea052bf1d414baf2 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:16:45 +1000 Subject: [PATCH 05/26] [PIR #909] Plan revised: add codev/roles/architect.md, expand grep, dashboard/synonym hints, follow-up candidates --- .../909-architect-treat-area-labels-as.md | 86 +++++++++++++------ 1 file changed, 61 insertions(+), 25 deletions(-) diff --git a/codev/plans/909-architect-treat-area-labels-as.md b/codev/plans/909-architect-treat-area-labels-as.md index 9d34c683..6ae775fd 100644 --- a/codev/plans/909-architect-treat-area-labels-as.md +++ b/codev/plans/909-architect-treat-area-labels-as.md @@ -4,25 +4,43 @@ Issue #909 asks for standing architect documentation on the `area/*` label convention so that any fresh session — in this repo or in an adopter's repo — can group, edit, audit, and bulk-move issues without re-discovering (or mis-applying) the convention. Today the rules live only in the labels themselves, in existing issue bodies, and in per-session memory; a new chat window has none of that context. -The work is *two coordinated doc updates*: +The work spans two distinct propagation paths into other repos, so the file split has to honor both: -1. **codev's own `CLAUDE.md` + `AGENTS.md`** — concrete label vocabulary, policy rules, and `gh` recipes. Must stay byte-identical (per the existing sync rule). -2. **`codev-skeleton/templates/CLAUDE.md` + `templates/AGENTS.md` + `roles/architect.md`** — *framework-neutral* version. No mention of codev's specific area names; teaches the pattern, not the vocabulary (per the `framework-neutral-on-label-semantics` discipline). +**Path 1 — physically copied to user disk** at `codev init` / `codev adopt` / `codev update` (verified at `packages/codev/src/lib/scaffold.ts:159-194` and `commands/{init,adopt,update}.ts`): +- `codev-skeleton/templates/CLAUDE.md` → `/CLAUDE.md` +- `codev-skeleton/templates/AGENTS.md` → `/AGENTS.md` + +**Path 2 — resolved at runtime from the installed npm package** (tier-4 of the four-tier resolver; never on the user's disk, but their agents read it): +- `codev-skeleton/roles/architect.md` +- (and other framework files we're not touching — protocols, agents, consult-types, …) + +**Path 3 — codev's self-hosted instance** (never reaches other repos): +- `CLAUDE.md` (repo root) — codev's own project instructions, auto-loaded at session start in *this* repo +- `AGENTS.md` (repo root) — byte-identical sibling per the existing sync rule +- `codev/roles/architect.md` — tier-2 override in this repo; shadows the skeleton role file for codev's own architect sessions + +The work is *three coordinated doc updates*: + +1. **codev's own `CLAUDE.md` + `AGENTS.md` + `codev/roles/architect.md`** — concrete label vocabulary, policy rules, and `gh` recipes. CLAUDE.md/AGENTS.md stay byte-identical (per the existing sync rule). The role file gets the same codev-specific section so the architect knows the area policy whether the policy reaches it via auto-loaded CLAUDE.md or via its spawn-time role file. Belt-and-suspenders, and symmetric with how the skeleton role file gets the framework-neutral version. +2. **`codev-skeleton/templates/CLAUDE.md` + `templates/AGENTS.md`** — *framework-neutral* version (no codev area names). These get copied to user disks at install/update time. +3. **`codev-skeleton/roles/architect.md`** — *framework-neutral* version. Resolved at runtime by adopters' agents (tier-4 fallback) unless they've overridden it locally. + +Across paths 2 and 3, no mention of codev's specific area names; teaches the pattern, not the vocabulary (per the `framework-neutral-on-label-semantics` discipline). Live label inventory (confirmed via `gh label list --search area/` on 2026-05-28): -| Label | Scope | +| Label | Scope (with common synonyms) | |---|---| -| `area/docs` | Documentation (this repo, CLAUDE/AGENTS, role files, resources) | -| `area/vscode` | VSCode extension (sidebar views, commands, keybindings) | -| `area/panel` | Codev panel/dashboard webview | -| `area/consult` | Consult CLI and consultation tooling | -| `area/tower` | Tower server + `afx`/agent-farm CLI (no separate `area/agent-farm`) | -| `area/cross-cutting` | Multi-area work (used alone, never alongside another `area/*`) | +| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | +| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | +| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/consult` | `consult` CLI and consultation tooling | +| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | +| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | | `area/porch` | Porch state machine / protocol orchestration | | `area/config` | `.codev/config.json` and workspace setup | -| `area/terminal` | Terminal-specific (PTY, vscode terminal pane) | -| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`) | +| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also currently the catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | Policy rules already in personal memory but undocumented in repo: @@ -35,9 +53,10 @@ Policy rules already in personal memory but undocumented in repo: Add a new section titled **"Area Labels — the organizing axis for issues"** to: -1. `CLAUDE.md` and `AGENTS.md` (codev root) -2. `codev-skeleton/templates/CLAUDE.md` and `codev-skeleton/templates/AGENTS.md` -3. `codev-skeleton/roles/architect.md` +1. `CLAUDE.md` and `AGENTS.md` (codev root) — codev-specific vocabulary +2. `codev/roles/architect.md` — codev-specific vocabulary (this repo's self-instance role file) +3. `codev-skeleton/templates/CLAUDE.md` and `codev-skeleton/templates/AGENTS.md` — framework-neutral +4. `codev-skeleton/roles/architect.md` — framework-neutral ### Design decisions (these are the calls that want plan-approval) @@ -76,7 +95,9 @@ milestones, not assignees. | `area/porch` | Porch state machine / protocol orchestration | | `area/config` | `.codev/config.json` and workspace setup | | `area/terminal` | Terminal-specific (PTY, VSCode terminal pane) | -| `area/core` | Shared core library / forge abstraction | +| `area/core` | Shared core library / forge abstraction; current catch-all for install/scaffold and release tooling | + +**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If the live `gh label list` disagrees with this table (rare, but possible after a deliberate addition), trust the live list. **Policy:** @@ -122,11 +143,12 @@ Followed by: ## Files to Change -- `CLAUDE.md` — insert new `### Area Labels — the organizing axis for issues` subsection after the `### Project Tracking` block ending around line 130 (before the "🚨 CRITICAL: Two human approval gates" block). +- `CLAUDE.md` — insert new `### Area Labels — the organizing axis for issues` subsection after the `### Project Tracking` block ending around line 130 (before the "🚨 CRITICAL: Two human approval gates" block). Codev-specific vocabulary. - `AGENTS.md` — apply the **byte-identical** insertion. Verify with `diff CLAUDE.md AGENTS.md` (must be empty after the edit). -- `codev-skeleton/templates/CLAUDE.md` — insert framework-neutral subsection. Current file is short (122 lines, ends with "For More Info"); best placement is after the existing `## Key Locations` section (line 41) and before `## Quick Start`, or as a new top-level `## Working with Project Labels` section before `## Git Workflow` (note: the skeleton template doesn't have a `## Git Workflow` heading — final placement TBD at implement time, anchored to whatever puts it adjacent to project-tracking-style content). -- `codev-skeleton/templates/AGENTS.md` — byte-identical insertion. Verify diff is empty (except for the existing header / "AGENTS.md standard" preamble difference). -- `codev-skeleton/roles/architect.md` — new `## Working with project labels` section after `## Project Tracking` (currently line 247), before `## Handling Blocked Builders` (line 262). +- `codev/roles/architect.md` — new `## Working with area labels` section after the existing `## Project Tracking` section (currently around line 256, before `## Handling Blocked Builders`). Codev-specific vocabulary, same table as in `CLAUDE.md`. Note this repo's role file is the tier-2 override that shadows the skeleton's role file for codev's own architect sessions; placing the section here ensures the architect carries the policy even if a session reads only the role file. +- `codev-skeleton/templates/CLAUDE.md` — insert framework-neutral subsection. Current file is short (122 lines, ends with "For More Info"); best placement is after the existing `## Key Locations` section (line 41) and before `## Quick Start`, or as a new top-level `## Working with Project Labels` section. Final placement TBD at implement time, anchored to whatever puts it adjacent to project-tracking-style content. **Reaches user repos via disk copy at `codev init` / `adopt` / `update`** (verified at `packages/codev/src/lib/scaffold.ts:159-194`). +- `codev-skeleton/templates/AGENTS.md` — byte-identical insertion. Verify diff is empty (except for the existing 4-line preamble difference). +- `codev-skeleton/roles/architect.md` — new `## Working with project labels` section after `## Project Tracking` (currently line 247), before `## Handling Blocked Builders` (line 262). Framework-neutral phrasing. **Reaches user repos via runtime resolution from the installed npm package** (tier-4 of the four-tier resolver); never on user disk but their agents load it. No code, no tests, no protocol-spec changes. Pure documentation. @@ -146,6 +168,22 @@ No code, no tests, no protocol-spec changes. Pure documentation. **Alternative considered: a separate `codev/resources/area-labels.md` reference doc with `CLAUDE.md` linking to it.** Rejected — the issue explicitly asks for it to land *in* `CLAUDE.md` and `AGENTS.md` so it loads into the agent's context automatically. A separate file would defeat the no-memory-dependence acceptance criterion (the agent would have to know to read it). +## Areas Not Currently Labeled (Follow-up Candidates) + +The live label set covers 100% of currently-labeled issues, but there are categories of work where issues default to `area/core` as a catch-all rather than having a dedicated label: + +- **Release tooling** — `codev/protocols/release/`, release scripts, version bumps. Currently routed via `area/core` or `area/docs`. +- **Scaffold / install** — `codev init` / `codev adopt` / `codev update`, the `codev-skeleton/` shipping mechanism, the four-tier file resolver. Currently `area/core`. + +The all-time issue-count distribution skews VSCode-heavy (39 `area/vscode`, 12 `area/tower`, 4 `area/core`) which suggests these categories haven't generated enough volume to justify their own labels yet. The issue body explicitly puts new-label decisions out of scope for this PR, so the plan records only the existing 10. If volume picks up for either, a follow-up issue can split them out. The skeleton variant is unaffected by this — it teaches the *pattern*, not codev's specific vocabulary, so adopters making different choices stay coherent. + +Categories the user might suggest that are **not** missing: + +- **dashboard** → already covered as `area/panel` (label name differs from colloquial term — flagged in the scope hint and synonym-alert). +- **web** → codev has no web component (no marketing site, no separate web app). Nothing to label. +- **mobile** → codev has no mobile component. Nothing to label. +- **agent-farm / afx** → already covered as `area/tower` (the label intentionally bundles Tower + agent-farm to avoid a near-duplicate `area/agent-farm`). + ## Test Plan This is a doc-only change, so the test plan is **review-driven** rather than build-driven. At the `dev-approval` gate the reviewer should: @@ -156,14 +194,12 @@ This is a doc-only change, so the test plan is **review-driven** rather than bui diff codev-skeleton/templates/CLAUDE.md codev-skeleton/templates/AGENTS.md # only the 4-line preamble ``` -2. **Vocabulary leak check** — confirm the skeleton files contain **zero** instances of codev's actual area names: +2. **Vocabulary leak check** — confirm **no file anywhere under `codev-skeleton/`** contains codev's concrete area names. Strongly defensive: catches accidental leaks anywhere in the skeleton, not just the three files this PR edits. ```bash - grep -E "area/(docs|vscode|panel|consult|tower|cross-cutting|porch|config|terminal|core)" \ - codev-skeleton/templates/CLAUDE.md \ - codev-skeleton/templates/AGENTS.md \ - codev-skeleton/roles/architect.md + grep -rE "area/(docs|vscode|panel|consult|tower|cross-cutting|porch|config|terminal|core)" codev-skeleton/ # Expected: no output ``` + (Pre-PR baseline already returns no output, so this stays green unless the PR introduces a leak.) 3. **`gh` recipe smoke test** — run each recipe against the live repo and confirm output is reasonable: - Group: produces a tally per area. From 96d8a1d7bbad7207becfca5130c897144e71f475 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:17:05 +1000 Subject: [PATCH 06/26] [PIR #909] Thread: record revision rationale --- codev/state/pir-909_thread.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md index 75823dee..45409ea5 100644 --- a/codev/state/pir-909_thread.md +++ b/codev/state/pir-909_thread.md @@ -14,3 +14,29 @@ Drafted `codev/plans/909-architect-treat-area-labels-as.md`. Key design calls ma Live label inventory captured from `gh label list --search area/` (10 labels). No mention of `area/agent-farm` — `area/tower` covers afx/agent-farm work (confirmed already in personal memory and consistent with the issue body). Awaiting `plan-approval`. + +## 2026-05-28 — plan revision after reviewer feedback + +User raised two questions worth recording the answers to: + +**Q1: What exactly propagates to other repos at install/update time?** +Verified at `packages/codev/src/lib/scaffold.ts:159-194` and `commands/{init,adopt,update}.ts`: +- Path 1 (copied to disk): `codev-skeleton/templates/{CLAUDE,AGENTS}.md`, `codev-skeleton/skills/*` +- Path 2 (runtime resolution via tier-4): everything else under `codev-skeleton/` — `roles/`, `protocols/`, etc. +- Path 3 (never leaves this repo): `CLAUDE.md` / `AGENTS.md` at the codev repo root, `codev/roles/architect.md` (tier-2 override for codev's own sessions) + +Plan revision: +- Added `codev/roles/architect.md` to the codev-specific file set (belt-and-suspenders — architect knows the policy via either CLAUDE.md auto-load OR role-file load). +- Extended the vocabulary-leak grep to `grep -rE … codev-skeleton/` (catches any leak anywhere in the skeleton tree). + +**Q2: Is the 10-area list comprehensive? What about web / dashboard / mobile?** +Hard data from `gh label list` and `gh issue list --state all`: +- 10 areas, all currently active. +- "dashboard" = `area/panel` (naming gap; user-facing synonym, label-internal name). +- "web", "mobile" — no such code exists in the repo, nothing to label. +- Real undocumented gaps: release tooling, scaffold/install (both currently catch-all under `area/core`). Issue explicitly puts new-label decisions out of scope — flagged in the plan as follow-up candidates. + +Plan revision: +- Added "Synonym alert" line + bolded "dashboard" in the `area/panel` scope hint. +- Added `area/tower` "no separate area/agent-farm" callout to the table. +- Added "Areas Not Currently Labeled" section listing release / scaffold as follow-up candidates, plus a "what's not missing" subsection for the user's specific terms. From b4721c7d8a02572fb462495425b9088c0bc4ea78 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:19:16 +1000 Subject: [PATCH 07/26] chore(porch): 909 plan-approval gate-approved --- .../projects/909-architect-treat-area-labels-as/status.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 22f2a1a5..5866bbe5 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -6,8 +6,9 @@ plan_phases: [] current_plan_phase: null gates: plan-approval: - status: pending + status: approved requested_at: '2026-05-28T05:06:26.853Z' + approved_at: '2026-05-28T05:19:16.527Z' dev-approval: status: pending pr: @@ -16,4 +17,4 @@ iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T05:06:26.853Z' +updated_at: '2026-05-28T05:19:16.528Z' From 463a3cfa9b6a33918d4c638db3ed2f9ac85de3db Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:19:24 +1000 Subject: [PATCH 08/26] chore(porch): 909 implement phase-transition --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 5866bbe5..6f048055 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -1,7 +1,7 @@ id: '909' title: architect-treat-area-labels-as protocol: pir -phase: plan +phase: implement plan_phases: [] current_plan_phase: null gates: @@ -17,4 +17,4 @@ iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T05:19:16.528Z' +updated_at: '2026-05-28T05:19:24.224Z' From 55fd42eaac1c0ae9ce1ce41a26686a62fdfe7109 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:27:08 +1000 Subject: [PATCH 09/26] [PIR #909] Add area-labels section to codev CLAUDE.md, AGENTS.md, and codev/roles/architect.md (codev-specific vocabulary) --- AGENTS.md | 50 ++++++++++++++++++++++++++++++ CLAUDE.md | 50 ++++++++++++++++++++++++++++++ codev-skeleton/roles/architect.md | 45 +++++++++++++++++++++++++++ codev-skeleton/templates/AGENTS.md | 45 +++++++++++++++++++++++++++ codev-skeleton/templates/CLAUDE.md | 45 +++++++++++++++++++++++++++ codev/roles/architect.md | 50 ++++++++++++++++++++++++++++++ 6 files changed, 285 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8f6e140b..87acda8f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,6 +119,56 @@ Key locations: - **During implementation**: Use `porch status ` for detailed phase status - **After completion**: Close the GitHub Issue when PR is merged +### Area Labels — the organizing axis for issues + +`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. + +**Live vocabulary** (run `gh label list --search area/` to confirm): + +| Label | Scope (with common synonyms) | +|---|---| +| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | +| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | +| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/consult` | `consult` CLI and consultation tooling | +| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | +| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | +| `area/porch` | Porch state machine / protocol orchestration | +| `area/config` | `.codev/config.json` and workspace setup | +| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also the current catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | + +**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If `gh label list` disagrees with this table (rare, but possible after a deliberate addition), trust the live list. + +**Policy:** + +- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. +- **No `type:*` labels.** Codev classifies issues by area only. +- `area/` uses **slash** (Kubernetes/Terraform convention). Other label families (if ever introduced) would keep colons. +- All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. + +**Operational recipes:** + +```bash +# Group: tally open issues by area +gh issue list --state open --limit 500 --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' + +# Edit: change area on a single issue +gh issue edit --remove-label area/old --add-label area/new + +# Audit: find open issues with no area label +gh issue list --state open --limit 500 --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("area/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open `area/` issues to `area/` +for n in $(gh issue list --state open --limit 500 --label area/old --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label area/old --add-label area/new +done +``` + +When in doubt, run `gh label list --search area/` — it is the source of truth. + **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production diff --git a/CLAUDE.md b/CLAUDE.md index 8f6e140b..87acda8f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -119,6 +119,56 @@ Key locations: - **During implementation**: Use `porch status ` for detailed phase status - **After completion**: Close the GitHub Issue when PR is merged +### Area Labels — the organizing axis for issues + +`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. + +**Live vocabulary** (run `gh label list --search area/` to confirm): + +| Label | Scope (with common synonyms) | +|---|---| +| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | +| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | +| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/consult` | `consult` CLI and consultation tooling | +| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | +| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | +| `area/porch` | Porch state machine / protocol orchestration | +| `area/config` | `.codev/config.json` and workspace setup | +| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also the current catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | + +**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If `gh label list` disagrees with this table (rare, but possible after a deliberate addition), trust the live list. + +**Policy:** + +- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. +- **No `type:*` labels.** Codev classifies issues by area only. +- `area/` uses **slash** (Kubernetes/Terraform convention). Other label families (if ever introduced) would keep colons. +- All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. + +**Operational recipes:** + +```bash +# Group: tally open issues by area +gh issue list --state open --limit 500 --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' + +# Edit: change area on a single issue +gh issue edit --remove-label area/old --add-label area/new + +# Audit: find open issues with no area label +gh issue list --state open --limit 500 --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("area/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open `area/` issues to `area/` +for n in $(gh issue list --state open --limit 500 --label area/old --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label area/old --add-label area/new +done +``` + +When in doubt, run `gh label list --search area/` — it is the source of truth. + **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 7365dce8..32dd1780 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -257,6 +257,51 @@ gh issue view 42 Update status as projects progress: - `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` +## Working with Project Labels + +If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes. + +**Discover the convention:** + +```bash +# List all labels (skim for structured prefixes) +gh label list + +# Filter to a specific prefix family +gh label list --search "/" +``` + +**Inferring policy:** conventions vary across projects. Common patterns: + +- **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). +- **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). +- **Separator style.** `/` (Kubernetes-style) and `:` both exist in the wild — respect whatever convention the project already uses. +- **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. + +Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. + +**Operational recipes** (substitute `` and `` for your project's actual labels): + +```bash +# Group: tally open issues by /* label +gh issue list --state open --limit 500 --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' + +# Edit: change a label on a single issue +gh issue edit --remove-label / --add-label / + +# Audit: find open issues with no /* label +gh issue list --state open --limit 500 --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open / issues to / +for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label / --add-label / +done +``` + +When in doubt, run `gh label list` — it is the source of truth for what your project uses. + ## Handling Blocked Builders When a builder reports blocked: diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md index 8b68b16e..60bbe761 100644 --- a/codev-skeleton/templates/AGENTS.md +++ b/codev-skeleton/templates/AGENTS.md @@ -47,6 +47,51 @@ This succeeds if the protocol is registered (including via the skeleton fallback - **Reviews**: `codev/reviews/` - Reviews and lessons learned - **Protocols**: `codev/protocols/` - Development protocols +## Working with Project Labels + +If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes. + +**Discover the convention:** + +```bash +# List all labels (skim for structured prefixes) +gh label list + +# Filter to a specific prefix family +gh label list --search "/" +``` + +**Inferring policy:** conventions vary across projects. Common patterns: + +- **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). +- **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). +- **Separator style.** `/` (Kubernetes-style) and `:` both exist in the wild — respect whatever convention the project already uses. +- **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. + +Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. + +**Operational recipes** (substitute `` and `` for your project's actual labels): + +```bash +# Group: tally open issues by /* label +gh issue list --state open --limit 500 --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' + +# Edit: change a label on a single issue +gh issue edit --remove-label / --add-label / + +# Audit: find open issues with no /* label +gh issue list --state open --limit 500 --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open / issues to / +for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label / --add-label / +done +``` + +When in doubt, run `gh label list` — it is the source of truth for what your project uses. + ## Quick Start 1. For new features, start with the Specification phase diff --git a/codev-skeleton/templates/CLAUDE.md b/codev-skeleton/templates/CLAUDE.md index ade98635..2ac3e95e 100644 --- a/codev-skeleton/templates/CLAUDE.md +++ b/codev-skeleton/templates/CLAUDE.md @@ -45,6 +45,51 @@ This succeeds if the protocol is registered (including via the skeleton fallback - **Reviews**: `codev/reviews/` - Reviews and lessons learned - **Protocols**: `codev/protocols/` - Development protocols +## Working with Project Labels + +If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes. + +**Discover the convention:** + +```bash +# List all labels (skim for structured prefixes) +gh label list + +# Filter to a specific prefix family +gh label list --search "/" +``` + +**Inferring policy:** conventions vary across projects. Common patterns: + +- **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). +- **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). +- **Separator style.** `/` (Kubernetes-style) and `:` both exist in the wild — respect whatever convention the project already uses. +- **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. + +Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. + +**Operational recipes** (substitute `` and `` for your project's actual labels): + +```bash +# Group: tally open issues by /* label +gh issue list --state open --limit 500 --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' + +# Edit: change a label on a single issue +gh issue edit --remove-label / --add-label / + +# Audit: find open issues with no /* label +gh issue list --state open --limit 500 --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open / issues to / +for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label / --add-label / +done +``` + +When in doubt, run `gh label list` — it is the source of truth for what your project uses. + ## Quick Start 1. For new features, start with the Specification phase diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 763c93ce..6a15569e 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -256,6 +256,56 @@ gh issue view 42 Update status as projects progress: - `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` +## Working with Area Labels + +`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. + +**Live vocabulary** (run `gh label list --search area/` to confirm): + +| Label | Scope (with common synonyms) | +|---|---| +| `area/docs` | Documentation — CLAUDE/AGENTS, role files, `codev/resources/` | +| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | +| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/consult` | `consult` CLI and consultation tooling | +| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | +| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | +| `area/porch` | Porch state machine / protocol orchestration | +| `area/config` | `.codev/config.json` and workspace setup | +| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | +| `area/core` | Shared core library / forge abstraction; also the current catch-all for install/scaffold and release tooling until those get dedicated labels | + +**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If `gh label list` disagrees with this table, trust the live list. + +**Policy:** + +- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. +- **No `type:*` labels.** Codev classifies issues by area only. +- `area/` uses **slash** (Kubernetes/Terraform convention). +- All `gh issue create` invocations include `--assignee @me`. + +**Operational recipes:** + +```bash +# Group: tally open issues by area +gh issue list --state open --limit 500 --json number,title,labels --jq \ + 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' + +# Edit: change area on a single issue +gh issue edit --remove-label area/old --add-label area/new + +# Audit: find open issues with no area label +gh issue list --state open --limit 500 --json number,title,labels \ + --jq '.[] | select([.labels[].name] | any(startswith("area/")) | not) | "#\(.number) \(.title)"' + +# Bulk-move: relabel all open `area/` issues to `area/` +for n in $(gh issue list --state open --limit 500 --label area/old --json number --jq '.[].number'); do + gh issue edit "$n" --remove-label area/old --add-label area/new +done +``` + +When in doubt, run `gh label list --search area/` — it is the source of truth. + ## Handling Blocked Builders When a builder reports blocked: From 63cc18d0500f0f9f65bd5995ca8d3a03e60a6611 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:28:54 +1000 Subject: [PATCH 10/26] [PIR #909] Thread: implement-phase notes (recipes, --limit 500 tweak, install) --- codev/state/pir-909_thread.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md index 45409ea5..68a11e11 100644 --- a/codev/state/pir-909_thread.md +++ b/codev/state/pir-909_thread.md @@ -40,3 +40,24 @@ Plan revision: - Added "Synonym alert" line + bolded "dashboard" in the `area/panel` scope hint. - Added `area/tower` "no separate area/agent-farm" callout to the table. - Added "Areas Not Currently Labeled" section listing release / scaffold as follow-up candidates, plus a "what's not missing" subsection for the user's specific terms. + +## 2026-05-28 — implement phase + +Plan approved (`plan-approval` gate). Applied the 6 edits per plan: + +- `CLAUDE.md` + `AGENTS.md` (root) — codev-specific `### Area Labels` subsection after `### Project Tracking`. +- `codev/roles/architect.md` — codev-specific `## Working with Area Labels` after `## Project Tracking`. +- `codev-skeleton/templates/CLAUDE.md` + `AGENTS.md` — framework-neutral `## Working with Project Labels` between `## Key Locations` and `## Quick Start`. +- `codev-skeleton/roles/architect.md` — framework-neutral `## Working with Project Labels` after `## Project Tracking`. + +Mid-implementation tweak: discovered `gh issue list` defaults to 30 results, which silently truncated the group recipe (showed only 5 of 9 areas with open issues). Added `--limit 500` to all list-based recipes (group, audit, bulk-move) across all 6 files. Not in the original plan but a usability defect worth fixing before code lands. Documented here so the dev-approval reviewer knows why the recipes have `--limit 500`. + +All 4 verification checks pass: +- `diff CLAUDE.md AGENTS.md` → empty (byte-identical) +- `diff codev-skeleton/templates/{CLAUDE,AGENTS}.md` → only the 4-line preamble differs (intentional) +- `grep -rE "area/(docs|vscode|panel|consult|tower|cross-cutting|porch|config|terminal|core)" codev-skeleton/` → no output (no vocab leak) +- `npm run build` → green (✓ built in 1.43s) +- Group/audit recipes smoke-tested against the live repo — produce sensible output +- `npm test` running in background; will report on completion + +Worktree had no `node_modules` (no postSpawn hook configured), so I ran `pnpm install` once before the build/test cycle. Recorded so a future spawn doesn't repeat the dead-end. From c7e32c03a12af6f25a624e81e3d21c653c549ae4 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 15:29:23 +1000 Subject: [PATCH 11/26] chore(porch): 909 dev-approval gate-requested --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 6f048055..ab74ca89 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -11,10 +11,11 @@ gates: approved_at: '2026-05-28T05:19:16.527Z' dev-approval: status: pending + requested_at: '2026-05-28T05:29:23.678Z' pr: status: pending iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T05:19:24.224Z' +updated_at: '2026-05-28T05:29:23.679Z' From d81ba9ed9bb2c8dffc50d8dba8ef713bf5031778 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 16:43:18 +1000 Subject: [PATCH 12/26] [PIR #909] Thread: record forge-direct decision at dev-approval --- codev/state/pir-909_thread.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md index 68a11e11..aeb8bde9 100644 --- a/codev/state/pir-909_thread.md +++ b/codev/state/pir-909_thread.md @@ -61,3 +61,17 @@ All 4 verification checks pass: - `npm test` running in background; will report on completion Worktree had no `node_modules` (no postSpawn hook configured), so I ran `pnpm install` once before the build/test cycle. Recorded so a future spawn doesn't repeat the dead-end. + +## 2026-05-28 — forge-direct vs forge-abstract design call (at dev-approval) + +User flagged: "instructions shouldn't mention GitHub directly, isn't there a forge or git abstraction?" + +Investigated and confirmed the existing pattern: +- **Internal automation layer**: forge concept commands at `packages/codev/scripts/forge//`, dispatched via `packages/codev/src/lib/forge.ts`. Routes through `gh`/`glab`/`tea` per `.codev/config.json`'s `forge.provider`. Used by porch, doctor, project-summary, etc. +- **User-facing layer** (skeleton docs + AI prompts): hardcodes `gh` everywhere. `codev-skeleton/roles/architect.md` already has `gh pr diff`, `gh pr view`, `gh pr comment`, `gh issue close`, `gh issue list`, `gh issue view`. Every protocol prompt (`codev-skeleton/protocols/*/prompts/*.md`, `*/builder-prompt.md`) uses `gh pr create`, `gh pr merge`, `gh pr view`, etc. + +Why two layers: the forge concept set is read-mostly (`issue-view`, `issue-list`, `pr-list`, `pr-merge`, ...) — no concepts for label management, issue editing, jq-piping. Architect interactive ops need flag shapes the abstraction doesn't expose. And there's no user-facing `codev forge ` CLI. + +User confirmed: keep new section consistent with existing `gh` pattern. Localized forge-CLI awareness in one section would create inconsistency vs. neighboring sections (and the rest of the skeleton). Wholesale forge-agnostic skeleton refactor is a separate, much larger concern — file as a follow-up if/when wanted. + +No edits to the codebase. Recorded the pattern as memory ([feedback-skeleton-gh-direct]) so future sessions don't re-litigate. From b7df41bccf448bdceb5fed0328e748e96ab7a8b3 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 16:49:21 +1000 Subject: [PATCH 13/26] [PIR #909] Drop synonym alerts and Kubernetes/Terraform parenthetical from area-labels section --- AGENTS.md | 6 ++---- CLAUDE.md | 6 ++---- codev-skeleton/roles/architect.md | 2 +- codev-skeleton/templates/AGENTS.md | 2 +- codev-skeleton/templates/CLAUDE.md | 2 +- codev/roles/architect.md | 6 ++---- 6 files changed, 9 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 87acda8f..ce69c31c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -129,7 +129,7 @@ Key locations: |---|---| | `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | | `area/vscode` | VSCode extension — sidebar views, commands, keybindings | -| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/panel` | The "codev panel" tab inside the VSCode extension. | | `area/consult` | `consult` CLI and consultation tooling | | `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | | `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | @@ -138,13 +138,11 @@ Key locations: | `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | | `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also the current catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | -**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If `gh label list` disagrees with this table (rare, but possible after a deliberate addition), trust the live list. - **Policy:** - **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. - **No `type:*` labels.** Codev classifies issues by area only. -- `area/` uses **slash** (Kubernetes/Terraform convention). Other label families (if ever introduced) would keep colons. +- `area/` uses **slash**. Other label families (if ever introduced) would keep colons. - All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. **Operational recipes:** diff --git a/CLAUDE.md b/CLAUDE.md index 87acda8f..ce69c31c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -129,7 +129,7 @@ Key locations: |---|---| | `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | | `area/vscode` | VSCode extension — sidebar views, commands, keybindings | -| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/panel` | The "codev panel" tab inside the VSCode extension. | | `area/consult` | `consult` CLI and consultation tooling | | `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | | `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | @@ -138,13 +138,11 @@ Key locations: | `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | | `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also the current catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | -**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If `gh label list` disagrees with this table (rare, but possible after a deliberate addition), trust the live list. - **Policy:** - **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. - **No `type:*` labels.** Codev classifies issues by area only. -- `area/` uses **slash** (Kubernetes/Terraform convention). Other label families (if ever introduced) would keep colons. +- `area/` uses **slash**. Other label families (if ever introduced) would keep colons. - All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. **Operational recipes:** diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 32dd1780..0b54112c 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -275,7 +275,7 @@ gh label list --search "/" - **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). - **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). -- **Separator style.** `/` (Kubernetes-style) and `:` both exist in the wild — respect whatever convention the project already uses. +- **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. - **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md index 60bbe761..cd0b513f 100644 --- a/codev-skeleton/templates/AGENTS.md +++ b/codev-skeleton/templates/AGENTS.md @@ -65,7 +65,7 @@ gh label list --search "/" - **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). - **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). -- **Separator style.** `/` (Kubernetes-style) and `:` both exist in the wild — respect whatever convention the project already uses. +- **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. - **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. diff --git a/codev-skeleton/templates/CLAUDE.md b/codev-skeleton/templates/CLAUDE.md index 2ac3e95e..77e162b7 100644 --- a/codev-skeleton/templates/CLAUDE.md +++ b/codev-skeleton/templates/CLAUDE.md @@ -63,7 +63,7 @@ gh label list --search "/" - **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). - **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). -- **Separator style.** `/` (Kubernetes-style) and `:` both exist in the wild — respect whatever convention the project already uses. +- **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. - **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 6a15569e..6b87c6c4 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -266,7 +266,7 @@ Update status as projects progress: |---|---| | `area/docs` | Documentation — CLAUDE/AGENTS, role files, `codev/resources/` | | `area/vscode` | VSCode extension — sidebar views, commands, keybindings | -| `area/panel` | The **dashboard** webview (the "codev panel" tab inside the VSCode extension). Synonym alert: users say "dashboard"; the label is `area/panel`. | +| `area/panel` | The "codev panel" tab inside the VSCode extension. | | `area/consult` | `consult` CLI and consultation tooling | | `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | | `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | @@ -275,13 +275,11 @@ Update status as projects progress: | `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | | `area/core` | Shared core library / forge abstraction; also the current catch-all for install/scaffold and release tooling until those get dedicated labels | -**Synonym alert:** users often say "dashboard" — that's `area/panel`. Users may also say "web" or "mobile" — codev has neither today, so don't invent area labels for them. If `gh label list` disagrees with this table, trust the live list. - **Policy:** - **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. - **No `type:*` labels.** Codev classifies issues by area only. -- `area/` uses **slash** (Kubernetes/Terraform convention). +- `area/` uses **slash**. - All `gh issue create` invocations include `--assignee @me`. **Operational recipes:** From 1c0ed423efd3b8822ee3854160ff412cc1c59d9a Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 17:34:20 +1000 Subject: [PATCH 14/26] [PIR #909] Restructure area-label set: add 5 labels, drop area/panel, remove --assignee policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Label changes (made via gh CLI in this same PR): - Add area/dashboard for @cluesmith/codev-dashboard React package - Add area/web for marketing/ - Add area/release for release tooling - Add area/scaffold for codev init/adopt/update/codev-skeleton - Add area/protocols for protocol definitions (distinct from area/porch) - Remove area/panel (4 panel-tab issues relabeled to area/vscode) Doc changes: - Update area table in CLAUDE.md/AGENTS.md/codev/roles/architect.md (14 rows) - Drop --assignee @me policy: reporting an issue ≠ committing to work on it - Drop synonym-alert paragraph and inline synonym alerts (speculative, not useful) - Drop Kubernetes/Terraform parenthetical (irrelevant) - Update plan file to capture the post-plan-approval scope expansion --- AGENTS.md | 13 ++++---- CLAUDE.md | 13 ++++---- codev-skeleton/roles/architect.md | 1 - codev-skeleton/templates/AGENTS.md | 1 - codev-skeleton/templates/CLAUDE.md | 1 - .../909-architect-treat-area-labels-as.md | 30 ++++++++++++------- codev/roles/architect.md | 13 ++++---- 7 files changed, 44 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce69c31c..6c007d0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,25 +125,28 @@ Key locations: **Live vocabulary** (run `gh label list --search area/` to confirm): -| Label | Scope (with common synonyms) | +| Label | Scope | |---|---| | `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | -| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | -| `area/panel` | The "codev panel" tab inside the VSCode extension. | +| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings | +| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-dashboard` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) | | `area/consult` | `consult` CLI and consultation tooling | | `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | | `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | | `area/porch` | Porch state machine / protocol orchestration | +| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) | | `area/config` | `.codev/config.json` and workspace setup | | `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | -| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also the current catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | +| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver | +| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts | +| `area/web` | Marketing site / web content — the `marketing/` directory | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) | **Policy:** - **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. Other label families (if ever introduced) would keep colons. -- All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. **Operational recipes:** diff --git a/CLAUDE.md b/CLAUDE.md index ce69c31c..6c007d0b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -125,25 +125,28 @@ Key locations: **Live vocabulary** (run `gh label list --search area/` to confirm): -| Label | Scope (with common synonyms) | +| Label | Scope | |---|---| | `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` | -| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | -| `area/panel` | The "codev panel" tab inside the VSCode extension. | +| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings | +| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-dashboard` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) | | `area/consult` | `consult` CLI and consultation tooling | | `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | | `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | | `area/porch` | Porch state machine / protocol orchestration | +| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) | | `area/config` | `.codev/config.json` and workspace setup | | `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | -| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`); also the current catch-all for install/scaffold (`codev init`/`adopt`/`update`) and release tooling until those get dedicated labels | +| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver | +| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts | +| `area/web` | Marketing site / web content — the `marketing/` directory | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) | **Policy:** - **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. Other label families (if ever introduced) would keep colons. -- All `gh issue create` invocations include `--assignee @me` so issues land in the user's assigned list. **Operational recipes:** diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 0b54112c..84b02739 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -276,7 +276,6 @@ gh label list --search "/" - **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). - **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). - **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. -- **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md index cd0b513f..6ce289a9 100644 --- a/codev-skeleton/templates/AGENTS.md +++ b/codev-skeleton/templates/AGENTS.md @@ -66,7 +66,6 @@ gh label list --search "/" - **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). - **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). - **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. -- **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. diff --git a/codev-skeleton/templates/CLAUDE.md b/codev-skeleton/templates/CLAUDE.md index 77e162b7..76dadb0a 100644 --- a/codev-skeleton/templates/CLAUDE.md +++ b/codev-skeleton/templates/CLAUDE.md @@ -64,7 +64,6 @@ gh label list --search "/" - **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). - **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). - **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. -- **Issue assignment.** Some projects require `--assignee @me` on `gh issue create` so issues land in the user's assigned list; check the existing issues to confirm. Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. diff --git a/codev/plans/909-architect-treat-area-labels-as.md b/codev/plans/909-architect-treat-area-labels-as.md index 6ae775fd..10e8bcd1 100644 --- a/codev/plans/909-architect-treat-area-labels-as.md +++ b/codev/plans/909-architect-treat-area-labels-as.md @@ -168,21 +168,31 @@ No code, no tests, no protocol-spec changes. Pure documentation. **Alternative considered: a separate `codev/resources/area-labels.md` reference doc with `CLAUDE.md` linking to it.** Rejected — the issue explicitly asks for it to land *in* `CLAUDE.md` and `AGENTS.md` so it loads into the agent's context automatically. A separate file would defeat the no-memory-dependence acceptance criterion (the agent would have to know to read it). -## Areas Not Currently Labeled (Follow-up Candidates) +## Scope Expansion (2026-05-28, post plan-approval) -The live label set covers 100% of currently-labeled issues, but there are categories of work where issues default to `area/core` as a catch-all rather than having a dedicated label: +During the implement phase, the reviewer's audit surfaced gaps the original plan missed and overrode the issue body's "no label changes" out-of-scope clause. The label set was restructured: -- **Release tooling** — `codev/protocols/release/`, release scripts, version bumps. Currently routed via `area/core` or `area/docs`. -- **Scaffold / install** — `codev init` / `codev adopt` / `codev update`, the `codev-skeleton/` shipping mechanism, the four-tier file resolver. Currently `area/core`. +**Labels added** (5): -The all-time issue-count distribution skews VSCode-heavy (39 `area/vscode`, 12 `area/tower`, 4 `area/core`) which suggests these categories haven't generated enough volume to justify their own labels yet. The issue body explicitly puts new-label decisions out of scope for this PR, so the plan records only the existing 10. If volume picks up for either, a follow-up issue can split them out. The skeleton variant is unaffected by this — it teaches the *pattern*, not codev's specific vocabulary, so adopters making different choices stay coherent. +- `area/dashboard` — the `@cluesmith/codev-dashboard` React/Vite package (Tower's web dashboard, opened in a browser). Previously unlabeled. +- `area/web` — `marketing/` directory (markdown, slides, logos). Previously unlabeled. +- `area/release` — release tooling, version bumps, release protocol. Previously catch-all under `area/core`. +- `area/scaffold` — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, four-tier resolver. Previously catch-all under `area/core`. +- `area/protocols` — protocol *definitions* in `codev/protocols/` and `codev-skeleton/protocols/`. Previously straddled `area/docs` and `area/porch`. -Categories the user might suggest that are **not** missing: +**Labels removed** (1): -- **dashboard** → already covered as `area/panel` (label name differs from colloquial term — flagged in the scope hint and synonym-alert). -- **web** → codev has no web component (no marketing site, no separate web app). Nothing to label. -- **mobile** → codev has no mobile component. Nothing to label. -- **agent-farm / afx** → already covered as `area/tower` (the label intentionally bundles Tower + agent-farm to avoid a near-duplicate `area/agent-farm`). +- `area/panel` — was generically named and covered VSCode bottom-panel-area work (NOT the dashboard package, despite my initial misreading). The 4 existing `area/panel` issues (#812, #813, #814, #815) were relabeled to `area/vscode` since they're all "vscode: migrate ... view ..." work. The `area/panel` label was then deleted. + +**Final label set: 14 area labels.** The doc table in `CLAUDE.md`, `AGENTS.md`, and `codev/roles/architect.md` was rewritten to match. + +**Policy bullets touched:** + +- Removed: "All `gh issue create` invocations include `--assignee @me`." User correction: reporting an issue ≠ committing to do it. Self-assignment is appropriate only when the user is taking the work on, not by default. (Memory file [feedback-assign-issues-to-user] updated to match.) +- Removed: "(Kubernetes/Terraform convention)" parenthetical on the slash-separator rule. Irrelevant to the architect's reading. +- Removed: synonym-alert paragraph + per-row inline synonym alerts. Speculative, not useful. + +The skeleton files (`codev-skeleton/templates/{CLAUDE,AGENTS}.md`, `codev-skeleton/roles/architect.md`) are unaffected by the label additions (they're framework-neutral by design). They received the same `--assignee @me` bullet removal and the same Kubernetes-style parenthetical removal. ## Test Plan diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 6b87c6c4..28c07a2b 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -262,25 +262,28 @@ Update status as projects progress: **Live vocabulary** (run `gh label list --search area/` to confirm): -| Label | Scope (with common synonyms) | +| Label | Scope | |---|---| | `area/docs` | Documentation — CLAUDE/AGENTS, role files, `codev/resources/` | -| `area/vscode` | VSCode extension — sidebar views, commands, keybindings | -| `area/panel` | The "codev panel" tab inside the VSCode extension. | +| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings | +| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-dashboard` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) | | `area/consult` | `consult` CLI and consultation tooling | | `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | | `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | | `area/porch` | Porch state machine / protocol orchestration | +| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) | | `area/config` | `.codev/config.json` and workspace setup | | `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | -| `area/core` | Shared core library / forge abstraction; also the current catch-all for install/scaffold and release tooling until those get dedicated labels | +| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver | +| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts | +| `area/web` | Marketing site / web content — the `marketing/` directory | +| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) | **Policy:** - **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. -- All `gh issue create` invocations include `--assignee @me`. **Operational recipes:** From 65b7fa19372ae65975b62fb1840f000e7fb72ba1 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 17:39:34 +1000 Subject: [PATCH 15/26] [PIR #909] Simplify lead-in to **Labels**, move gh label list to recipes with trigger comment --- AGENTS.md | 7 ++++--- CLAUDE.md | 7 ++++--- codev/roles/architect.md | 7 ++++--- codev/state/pir-909_thread.md | 31 +++++++++++++++++++++++++++++++ 4 files changed, 43 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6c007d0b..e11d4e13 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,7 +123,7 @@ Key locations: `area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. -**Live vocabulary** (run `gh label list --search area/` to confirm): +**Labels**: | Label | Scope | |---|---| @@ -151,6 +151,9 @@ Key locations: **Operational recipes:** ```bash +# Confirm the current label vocabulary (use before any label op to catch drift) +gh label list --search area/ + # Group: tally open issues by area gh issue list --state open --limit 500 --json number,title,labels --jq \ 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' @@ -168,8 +171,6 @@ for n in $(gh issue list --state open --limit 500 --label area/old --json number done ``` -When in doubt, run `gh label list --search area/` — it is the source of truth. - **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production diff --git a/CLAUDE.md b/CLAUDE.md index 6c007d0b..e11d4e13 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -123,7 +123,7 @@ Key locations: `area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. -**Live vocabulary** (run `gh label list --search area/` to confirm): +**Labels**: | Label | Scope | |---|---| @@ -151,6 +151,9 @@ Key locations: **Operational recipes:** ```bash +# Confirm the current label vocabulary (use before any label op to catch drift) +gh label list --search area/ + # Group: tally open issues by area gh issue list --state open --limit 500 --json number,title,labels --jq \ 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' @@ -168,8 +171,6 @@ for n in $(gh issue list --state open --limit 500 --label area/old --json number done ``` -When in doubt, run `gh label list --search area/` — it is the source of truth. - **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 28c07a2b..4a4075e0 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -260,7 +260,7 @@ Update status as projects progress: `area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. -**Live vocabulary** (run `gh label list --search area/` to confirm): +**Labels**: | Label | Scope | |---|---| @@ -288,6 +288,9 @@ Update status as projects progress: **Operational recipes:** ```bash +# Confirm the current label vocabulary (use before any label op to catch drift) +gh label list --search area/ + # Group: tally open issues by area gh issue list --state open --limit 500 --json number,title,labels --jq \ 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' @@ -305,8 +308,6 @@ for n in $(gh issue list --state open --limit 500 --label area/old --json number done ``` -When in doubt, run `gh label list --search area/` — it is the source of truth. - ## Handling Blocked Builders When a builder reports blocked: diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md index aeb8bde9..b59b13cb 100644 --- a/codev/state/pir-909_thread.md +++ b/codev/state/pir-909_thread.md @@ -75,3 +75,34 @@ Why two layers: the forge concept set is read-mostly (`issue-view`, `issue-list` User confirmed: keep new section consistent with existing `gh` pattern. Localized forge-CLI awareness in one section would create inconsistency vs. neighboring sections (and the rest of the skeleton). Wholesale forge-agnostic skeleton refactor is a separate, much larger concern — file as a follow-up if/when wanted. No edits to the codebase. Recorded the pattern as memory ([feedback-skeleton-gh-direct]) so future sessions don't re-litigate. + +## 2026-05-28 — scope expansion: area-label restructure at dev-approval + +Reviewer audit during the dev-approval gate surfaced gaps the original plan missed. After discussion, scope expanded beyond what #909's "out of scope" section listed. + +**Label restructure (executed via gh CLI):** +- Created: area/dashboard, area/web, area/release, area/scaffold, area/protocols +- Relabeled 4 panel-tab issues (#812, #813, #814, #815) from area/panel → area/vscode (they're VSCode work, all titled "vscode: migrate ...") +- Deleted: area/panel + +**Critical correction caught mid-flight:** +`area/panel` does NOT cover the React dashboard package. The dashboard package (`packages/dashboard/`, `@cluesmith/codev-dashboard`) is served by Tower over HTTP and opened in a browser via "Open Tower dashboard in browser". `area/panel` covered VSCode bottom-panel-area UI work (issues #812-815). I had conflated the two earlier; user clarification + grep over `tower-routes.ts:1406` ("Serve React dashboard static files directly") disambiguated. The reviewer was about to authorize a rename that would've tagged VSCode UX issues with a dashboard-package label. + +**Doc edits:** +- Updated 14-row area table in CLAUDE.md/AGENTS.md/codev/roles/architect.md +- Removed `--assignee @me` policy line (user correction: "reporting an issue doesn't mean the user wants it to be assigned to him") +- Removed synonym-alert paragraph and inline synonym alerts +- Removed Kubernetes/Terraform parenthetical +- Updated plan file with "Scope Expansion" section documenting the post-plan-approval changes +- Memory file `feedback_assign_issues_to_user.md` updated to scope the self-assign rule to actual user-take-on intent +- Memory file `reference_area_labels.md` updated to reflect the new 14-label set + +**Final label set (14):** +docs, vscode, dashboard, consult, tower, cross-cutting, porch, protocols, config, terminal, scaffold, release, web, core. + +All verification checks still green: +- diff CLAUDE.md AGENTS.md → empty +- diff skeleton CLAUDE.md AGENTS.md → only the 4-line preamble +- grep -rE "area/(...)" codev-skeleton/ → no leaks +- grep "--assignee @me" across all 6 doc files → no hits +- npm run build → ✓ (in progress: tests) From 051656d703af34e3bd875bdebaeecd8f976afe9d Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:06:30 +1000 Subject: [PATCH 16/26] [PIR #909] Dedup area-labels docs: vocabulary in CLAUDE.md/AGENTS.md, recipes in architect.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md and AGENTS.md (and their skeleton equivalents) carry the vocabulary table + policy — every session auto-loads them. codev/roles/architect.md (and the skeleton equivalent) carry the operational recipes only — they load only when an architect is spawned, and the recipes are architect-specific bulk ops. Net effect: each piece of content has one canonical home. Future label-set changes touch CLAUDE.md/AGENTS.md (which flows through codev update's .codev-new merge path in adopters); recipe changes touch architect.md (manual update for tier-2 overrides like shannon's, but recipes change less often than the vocabulary). --- AGENTS.md | 23 +---------------------- CLAUDE.md | 23 +---------------------- codev-skeleton/roles/architect.md | 23 +++-------------------- codev-skeleton/templates/AGENTS.md | 22 +--------------------- codev-skeleton/templates/CLAUDE.md | 22 +--------------------- codev/roles/architect.md | 27 +-------------------------- codev/state/pir-909_thread.md | 17 +++++++++++++++++ 7 files changed, 25 insertions(+), 132 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e11d4e13..116b7b0e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -148,28 +148,7 @@ Key locations: - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. Other label families (if ever introduced) would keep colons. -**Operational recipes:** - -```bash -# Confirm the current label vocabulary (use before any label op to catch drift) -gh label list --search area/ - -# Group: tally open issues by area -gh issue list --state open --limit 500 --json number,title,labels --jq \ - 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' - -# Edit: change area on a single issue -gh issue edit --remove-label area/old --add-label area/new - -# Audit: find open issues with no area label -gh issue list --state open --limit 500 --json number,title,labels \ - --jq '.[] | select([.labels[].name] | any(startswith("area/")) | not) | "#\(.number) \(.title)"' - -# Bulk-move: relabel all open `area/` issues to `area/` -for n in $(gh issue list --state open --limit 500 --label area/old --json number --jq '.[].number'); do - gh issue edit "$n" --remove-label area/old --add-label area/new -done -``` +For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it diff --git a/CLAUDE.md b/CLAUDE.md index e11d4e13..116b7b0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -148,28 +148,7 @@ Key locations: - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. Other label families (if ever introduced) would keep colons. -**Operational recipes:** - -```bash -# Confirm the current label vocabulary (use before any label op to catch drift) -gh label list --search area/ - -# Group: tally open issues by area -gh issue list --state open --limit 500 --json number,title,labels --jq \ - 'group_by([.labels[].name | select(startswith("area/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("area/")).name): \(length)"' - -# Edit: change area on a single issue -gh issue edit --remove-label area/old --add-label area/new - -# Audit: find open issues with no area label -gh issue list --state open --limit 500 --json number,title,labels \ - --jq '.[] | select([.labels[].name] | any(startswith("area/")) | not) | "#\(.number) \(.title)"' - -# Bulk-move: relabel all open `area/` issues to `area/` -for n in $(gh issue list --state open --limit 500 --label area/old --json number --jq '.[].number'); do - gh issue edit "$n" --remove-label area/old --add-label area/new -done -``` +For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 84b02739..5e3d96a6 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -259,29 +259,14 @@ Update status as projects progress: ## Working with Project Labels -If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes. +The vocabulary your project uses (if any) and the per-issue policy live in `CLAUDE.md` / `AGENTS.md`, which load automatically into every session. The recipes below are the architect-specific bulk operations — substitute `` and `` for your project's actual labels (or skip this section if your project doesn't use prefix-structured labels). -**Discover the convention:** +**Operational recipes:** ```bash -# List all labels (skim for structured prefixes) -gh label list - -# Filter to a specific prefix family +# Confirm the current label vocabulary (use before any label op to catch drift) gh label list --search "/" -``` - -**Inferring policy:** conventions vary across projects. Common patterns: - -- **One label per axis.** Many projects allow only one `/*` label per issue, with a dedicated multi-axis fallback (e.g. `/cross-cutting`). -- **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`). -- **Separator style.** `/` and `:` both exist in the wild — respect whatever convention the project already uses. -Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. - -**Operational recipes** (substitute `` and `` for your project's actual labels): - -```bash # Group: tally open issues by /* label gh issue list --state open --limit 500 --json number,title,labels --jq \ 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' @@ -299,8 +284,6 @@ for n in $(gh issue list --state open --limit 500 --label / --json done ``` -When in doubt, run `gh label list` — it is the source of truth for what your project uses. - ## Handling Blocked Builders When a builder reports blocked: diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md index 6ce289a9..9b720c41 100644 --- a/codev-skeleton/templates/AGENTS.md +++ b/codev-skeleton/templates/AGENTS.md @@ -69,27 +69,7 @@ gh label list --search "/" Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. -**Operational recipes** (substitute `` and `` for your project's actual labels): - -```bash -# Group: tally open issues by /* label -gh issue list --state open --limit 500 --json number,title,labels --jq \ - 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' - -# Edit: change a label on a single issue -gh issue edit --remove-label / --add-label / - -# Audit: find open issues with no /* label -gh issue list --state open --limit 500 --json number,title,labels \ - --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' - -# Bulk-move: relabel all open / issues to / -for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do - gh issue edit "$n" --remove-label / --add-label / -done -``` - -When in doubt, run `gh label list` — it is the source of truth for what your project uses. +For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. ## Quick Start diff --git a/codev-skeleton/templates/CLAUDE.md b/codev-skeleton/templates/CLAUDE.md index 76dadb0a..213bbd5f 100644 --- a/codev-skeleton/templates/CLAUDE.md +++ b/codev-skeleton/templates/CLAUDE.md @@ -67,27 +67,7 @@ gh label list --search "/" Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. -**Operational recipes** (substitute `` and `` for your project's actual labels): - -```bash -# Group: tally open issues by /* label -gh issue list --state open --limit 500 --json number,title,labels --jq \ - 'group_by([.labels[].name | select(startswith("/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("/")).name): \(length)"' - -# Edit: change a label on a single issue -gh issue edit --remove-label / --add-label / - -# Audit: find open issues with no /* label -gh issue list --state open --limit 500 --json number,title,labels \ - --jq '.[] | select([.labels[].name] | any(startswith("/")) | not) | "#\(.number) \(.title)"' - -# Bulk-move: relabel all open / issues to / -for n in $(gh issue list --state open --limit 500 --label / --json number --jq '.[].number'); do - gh issue edit "$n" --remove-label / --add-label / -done -``` - -When in doubt, run `gh label list` — it is the source of truth for what your project uses. +For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. ## Quick Start diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 4a4075e0..b3f1a7e0 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -258,32 +258,7 @@ Update status as projects progress: ## Working with Area Labels -`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees. - -**Labels**: - -| Label | Scope | -|---|---| -| `area/docs` | Documentation — CLAUDE/AGENTS, role files, `codev/resources/` | -| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings | -| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-dashboard` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) | -| `area/consult` | `consult` CLI and consultation tooling | -| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. | -| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` | -| `area/porch` | Porch state machine / protocol orchestration | -| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) | -| `area/config` | `.codev/config.json` and workspace setup | -| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane | -| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver | -| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts | -| `area/web` | Marketing site / web content — the `marketing/` directory | -| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) | - -**Policy:** - -- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels. -- **No `type:*` labels.** Codev classifies issues by area only. -- `area/` uses **slash**. +The label vocabulary (the 14 `area/*` labels and their scope hints) and the per-issue policy live in `CLAUDE.md` / `AGENTS.md`, which load automatically into every session. The recipes below are the architect-specific bulk operations. **Operational recipes:** diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md index b59b13cb..6b176639 100644 --- a/codev/state/pir-909_thread.md +++ b/codev/state/pir-909_thread.md @@ -106,3 +106,20 @@ All verification checks still green: - grep -rE "area/(...)" codev-skeleton/ → no leaks - grep "--assignee @me" across all 6 doc files → no hits - npm run build → ✓ (in progress: tests) + +## 2026-05-28 — dedup: split content across files by audience + +Reviewer flagged the duplication: same content (table + policy + recipes) appearing in all three files. Split by audience instead: + +- **CLAUDE.md / AGENTS.md** (auto-loaded for every session — builders, ad-hoc, architects): vocabulary table + policy. +- **codev/roles/architect.md** (loaded only when architect spawns via `afx`): operational recipes (group / edit / audit / bulk-move) + a one-line pointer back to CLAUDE.md for the vocabulary/policy. + +Same split applied to the skeleton files (framework-neutral version). Net effect: each piece of content has one canonical home. + +Implications for shannon issue #1872: +- shannon's CLAUDE.md/AGENTS.md gets the vocabulary table + policy (via `codev update` auto-merge) +- shannon's `codev/roles/architect.md` gets recipes-only (manual edit; codev update can't reach tier-2 overrides) + +This is also better for shannon's update path: future label-set additions in shannon flow through the standard `.codev-new` sidecar merge into CLAUDE.md; the architect.md override doesn't need to be touched for vocabulary changes. + +All 6 doc files updated. Build green. Tests in progress. From ec19e019ceacd3a9aca711d44c344487eb178c35 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:11:49 +1000 Subject: [PATCH 17/26] [PIR #909] Drop cross-references between CLAUDE.md and architect.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introducing 'see other file for content' pointers between framework files is a novel pattern with no precedent in this repo — every existing CLAUDE.md mention in framework files is for diffing or scaffolding, not content lookup. The dedup logic was sound (CLAUDE.md auto-loads, so architect agents already have the vocabulary in context), but the explicit pointers were brittle: redundant when CLAUDE.md is loaded, misleading if architect.md is ever read standalone. Cleaner: each file is self-contained for its audience. CLAUDE.md/AGENTS.md have vocabulary + policy. architect.md has recipes. No 'see X' pointers. --- AGENTS.md | 2 -- CLAUDE.md | 2 -- codev-skeleton/roles/architect.md | 2 +- codev-skeleton/templates/AGENTS.md | 2 -- codev-skeleton/templates/CLAUDE.md | 2 -- codev/roles/architect.md | 2 -- 6 files changed, 1 insertion(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 116b7b0e..aa63633d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -148,8 +148,6 @@ Key locations: - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. Other label families (if ever introduced) would keep colons. -For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. - **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production diff --git a/CLAUDE.md b/CLAUDE.md index 116b7b0e..aa63633d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -148,8 +148,6 @@ Key locations: - **No `type:*` labels.** Codev classifies issues by area only. - `area/` uses **slash**. Other label families (if ever introduced) would keep colons. -For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. - **🚨 CRITICAL: Two human approval gates exist:** - **conceived → specified**: AI creates spec, but ONLY the human can approve it - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md index 5e3d96a6..750e651f 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -259,7 +259,7 @@ Update status as projects progress: ## Working with Project Labels -The vocabulary your project uses (if any) and the per-issue policy live in `CLAUDE.md` / `AGENTS.md`, which load automatically into every session. The recipes below are the architect-specific bulk operations — substitute `` and `` for your project's actual labels (or skip this section if your project doesn't use prefix-structured labels). +If your project uses prefix-structured labels (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, the recipes below are the architect-specific bulk operations — substitute `` and `` for your project's actual labels. (Skip this section if your project doesn't use prefix-structured labels.) **Operational recipes:** diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md index 9b720c41..463c1bc9 100644 --- a/codev-skeleton/templates/AGENTS.md +++ b/codev-skeleton/templates/AGENTS.md @@ -69,8 +69,6 @@ gh label list --search "/" Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. -For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. - ## Quick Start 1. For new features, start with the Specification phase diff --git a/codev-skeleton/templates/CLAUDE.md b/codev-skeleton/templates/CLAUDE.md index 213bbd5f..19f545b1 100644 --- a/codev-skeleton/templates/CLAUDE.md +++ b/codev-skeleton/templates/CLAUDE.md @@ -67,8 +67,6 @@ gh label list --search "/" Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume. -For operational recipes (group / edit / audit / bulk-move), see `codev/roles/architect.md` — they live with the architect role since they're architect-specific bulk ops. - ## Quick Start 1. For new features, start with the Specification phase diff --git a/codev/roles/architect.md b/codev/roles/architect.md index b3f1a7e0..cd3c0709 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -258,8 +258,6 @@ Update status as projects progress: ## Working with Area Labels -The label vocabulary (the 14 `area/*` labels and their scope hints) and the per-issue policy live in `CLAUDE.md` / `AGENTS.md`, which load automatically into every session. The recipes below are the architect-specific bulk operations. - **Operational recipes:** ```bash From 8c1087693aa177f0907ca011f032d9913d2e1d2c Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:14:00 +1000 Subject: [PATCH 18/26] chore(porch): 909 dev-approval gate-approved --- .../projects/909-architect-treat-area-labels-as/status.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index ab74ca89..b1eb4574 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -10,12 +10,13 @@ gates: requested_at: '2026-05-28T05:06:26.853Z' approved_at: '2026-05-28T05:19:16.527Z' dev-approval: - status: pending + status: approved requested_at: '2026-05-28T05:29:23.678Z' + approved_at: '2026-05-28T08:14:00.023Z' pr: status: pending iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T05:29:23.679Z' +updated_at: '2026-05-28T08:14:00.024Z' From fad0316f34db05dbfbd02b0db62d66069e8f440b Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:14:14 +1000 Subject: [PATCH 19/26] chore(porch): 909 review phase-transition --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index b1eb4574..6845756a 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -1,7 +1,7 @@ id: '909' title: architect-treat-area-labels-as protocol: pir -phase: implement +phase: review plan_phases: [] current_plan_phase: null gates: @@ -19,4 +19,4 @@ iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T08:14:00.024Z' +updated_at: '2026-05-28T08:14:14.578Z' From ddd2f62673df294502cca1df3ce60ba91fd731cd Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:16:06 +1000 Subject: [PATCH 20/26] [PIR #909] Review + retrospective; add two lessons learned --- codev/resources/lessons-learned.md | 2 + .../909-architect-treat-area-labels-as.md | 98 +++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 codev/reviews/909-architect-treat-area-labels-as.md diff --git a/codev/resources/lessons-learned.md b/codev/resources/lessons-learned.md index 1b1b822b..6365eabc 100644 --- a/codev/resources/lessons-learned.md +++ b/codev/resources/lessons-learned.md @@ -307,6 +307,8 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated - [From 0386] Documentation audit should be formalized as a MAINTAIN protocol task -- the stale reference patterns list and tier structure can become a quarterly checklist. - [From 0386/0399/0403] Consult CLI needs better multi-project support -- the "Multiple projects found" error in Builder worktrees is a recurring issue. Worktrees inherit project directories from main, causing `consult` to fail. The `--prompt-file` workaround bypasses project detection but loses structured context. The CLI should support `--project-id` to disambiguate. - [From 0376] The research agent pattern (spawning a subagent to read all review files in parallel and return structured data) should be documented as a standard approach for future analyses. +- [From #909] Cross-file content references in framework files are brittle. Deduplicating shared content across `CLAUDE.md` and a role file via "see X for the table" pointers is a novel pattern with no precedent in this repo (every existing CLAUDE.md mention in framework files is for diffing or scaffolding, not content lookup). The pointer is redundant when the referenced file is auto-loaded and misleading if it isn't. Keep each file self-contained for its audience: `CLAUDE.md` for everyone-loaded content (vocabulary + policy), role files for role-specific content (recipes, workflows). +- [From #909] Codev's skeleton has a two-layer design that's intentional: the **internal automation layer** (`packages/codev/scripts/forge//` concept commands, dispatched via `packages/codev/src/lib/forge.ts`) is forge-agnostic; the **user-facing layer** (skeleton docs, AI prompts, protocol prompts) hardcodes `gh` directly throughout. The forge concept set is read-mostly (`issue-view`, `pr-list`, etc.) — no concepts for label management, jq-piping, or interactive ops. When adding new skeleton content, match the established `gh`-direct pattern. Localized forge-CLI awareness in one section creates inconsistency vs. the rest of the skeleton. ## 3-Way Reviews diff --git a/codev/reviews/909-architect-treat-area-labels-as.md b/codev/reviews/909-architect-treat-area-labels-as.md new file mode 100644 index 00000000..12290c5e --- /dev/null +++ b/codev/reviews/909-architect-treat-area-labels-as.md @@ -0,0 +1,98 @@ +# PIR Review: Treat `area/*` labels as a first-class organizing concept + +Fixes #909 + +## Summary + +Documented the `area/*` label convention as the primary axis for organizing GitHub issues in codev, so a fresh architect session can group / edit / audit / bulk-move issues without re-discovering the convention. Restructured the label set during the implement phase from 10 to 14 labels (added `area/dashboard`, `area/web`, `area/release`, `area/scaffold`, `area/protocols`; removed `area/panel` with 4 issues relabeled to `area/vscode`). The skeleton's `templates/{CLAUDE,AGENTS}.md` and `roles/architect.md` get framework-neutral guidance so adopters inherit the *pattern* without codev's specific vocabulary. + +## Files Changed + +``` + AGENTS.md | 29 +++ + CLAUDE.md | 29 +++ + codev-skeleton/roles/architect.md | 27 +++ + codev-skeleton/templates/AGENTS.md | 22 ++ + codev-skeleton/templates/CLAUDE.md | 22 ++ + codev/plans/909-architect-treat-area-labels-as.md | 229 +++++++++++++++++++++ + codev/projects/909-*/status.yaml | 22 ++ + codev/roles/architect.md | 25 +++ + codev/state/pir-909_thread.md | 125 +++++++++++ + codev/reviews/909-architect-treat-area-labels-as.md (this file) + 9 files changed, 530+ insertions(+), 0 deletions(-) +``` + +Doc-only PR. No code changes, no test changes, no protocol-definition changes. + +## Commits + +``` +ec19e019 [PIR #909] Drop cross-references between CLAUDE.md and architect.md +051656d7 [PIR #909] Dedup area-labels docs: vocabulary in CLAUDE.md/AGENTS.md, recipes in architect.md +65b7fa19 [PIR #909] Simplify lead-in to **Labels**, move gh label list to recipes with trigger comment +1c0ed423 [PIR #909] Restructure area-label set: add 5 labels, drop area/panel, remove --assignee policy +b7df41bc [PIR #909] Drop synonym alerts and Kubernetes/Terraform parenthetical from area-labels section +55fd42ea [PIR #909] Add area-labels section to codev CLAUDE.md, AGENTS.md, and codev/roles/architect.md +f2970e39 [PIR #909] Plan revised: add codev/roles/architect.md, expand grep, dashboard/synonym hints, follow-up candidates +aece8c03 [PIR #909] Plan draft +``` + +Plus thread-file updates and porch state-transition commits. + +## Test Results + +- `npm run build`: ✓ pass (built in ~1.4s, packages/codev/skeleton refreshed) +- `npm test`: ✓ pass (151 test files, 3188 passed, 13 pre-existing skips) +- Manual verification at `dev-approval` gate: reviewer ran the four `gh` recipes (group / edit / audit / bulk-move) against the live repo; group recipe correctly tallied 9 areas with open issues (after `--limit 500` fix mid-implementation); audit recipe surfaced expected unlabeled-issue list; vocabulary table reviewed for accuracy. + +## Architecture Updates + +No changes to `codev/resources/arch.md`. This PR is pure documentation — the label convention has existed informally since the labels were created; #909 only documents it. No new modules, no API contract changes, no protocol changes. + +## Lessons Learned Updates + +Updated `codev/resources/lessons-learned.md` with two durable lessons that emerged during this PR: + +1. **Cross-file content references in framework files are brittle.** When deduplicating documentation across `CLAUDE.md` and role files, "see X for the table" pointers introduce a novel pattern (no precedent in the codebase). The dedup logic is sound — `CLAUDE.md` auto-loads in every session — but the explicit pointer is redundant when the file IS loaded and misleading if it isn't. Cleaner: each file is self-contained for its audience. + +2. **Skeleton's user-facing layer hardcodes `gh` directly; the forge abstraction is internal-only.** Codev has a forge concept-command abstraction (`packages/codev/scripts/forge//`) used by porch/doctor/etc., but skeleton docs and protocol prompts all use `gh` directly. When adding new skeleton content, match the established `gh`-direct pattern rather than introducing localized forge-CLI awareness in one section. + +## Things to Look At During PR Review + +1. **Scope expansion at dev-approval.** The original plan (approved at `plan-approval`) listed label changes as out-of-scope. During the dev-approval review, the reviewer requested an audit of the label set, which surfaced gaps (no `area/dashboard`, no `area/web`/`area/release`/`area/scaffold`/`area/protocols`) and a wrong description for `area/panel`. The PR was expanded to: (a) create 5 new labels via `gh label create`, (b) delete `area/panel` after relabeling its 4 issues to `area/vscode`, (c) restructure the table. This is documented in the plan file's "Scope Expansion" section. Worth a careful read of the final label set vs. the original "out of scope" intent. + +2. **`area/panel` ≠ `area/dashboard`** disambiguation. The 4 issues previously labeled `area/panel` (#812, #813, #814, #815) are all titled "vscode: migrate ... view to panel tab" — they're about the VSCode bottom-panel UI surface, NOT the `@cluesmith/codev-dashboard` React package. Initial mis-framing would have conflated them. The relabel went `area/panel → area/vscode` (not `→ area/dashboard`). Verify the 4 issues now read sensibly under `area/vscode`. + +3. **Doc dedup direction.** Vocabulary table + policy live in `CLAUDE.md` / `AGENTS.md`; operational recipes live in `codev/roles/architect.md`. No cross-references between files. Verify the split feels right — the alternative ("everything in all three files") was explicitly rejected as duplication-heavy. + +4. **`--assignee @me` policy removal.** A prior memory rule ("all `gh issue create` includes `--assignee @me`") was wrong: reporting an issue ≠ committing to do the work. The policy bullet was removed from all six files; the memory file (`feedback_assign_issues_to_user.md`) was updated to scope the self-assign behavior to actual user-take-on intent. + +5. **Skeleton variants stay vocabulary-free.** `grep -rE "area/(docs|vscode|dashboard|consult|tower|cross-cutting|porch|protocols|config|terminal|scaffold|release|web|core)" codev-skeleton/` returns no output — verified at multiple checkpoints. The skeleton uses `/` placeholders throughout. + +6. **Shannon follow-up filed.** Issue [cluesmith/shannon#1872](https://github.com/cluesmith/shannon/issues/1872) tracks adopting the convention in shannon, with a 12-label proposed vocabulary derived from shannon's apps/packages layout. Out of scope for this PR but cross-linked for traceability. + +## How to Test Locally + +For reviewers pulling the branch: + +- **View diff**: VSCode sidebar → right-click builder `pir-909` → **View Diff** +- **Run dev server**: not applicable — this is a doc-only PR + +What to verify (cold-session check — the killer acceptance test from the issue body): + +1. Open a fresh Claude chat in this repo +2. Paste each of these and confirm the architect responds correctly without further prompting: + - "Show me my open issues grouped by area" → should run the group recipe (with `--limit 500`) and tally by area + - "Change the area on #X from `area/porch` to `area/tower`" → should run the edit recipe + - "Which open issues have no area label?" → should run the audit recipe + - "All open `area/core` issues should move to `area/tower` — do the relabel" → should run the bulk-move recipe + - "File an issue for X" → should pick the right area without asking, and should NOT include `--assignee @me` by default +3. Verify `gh label list --search area/` returns the 14 labels listed in the table + +Mechanical checks: + +- `diff CLAUDE.md AGENTS.md` → empty (byte-identical) +- `diff codev-skeleton/templates/CLAUDE.md codev-skeleton/templates/AGENTS.md` → only the 4-line preamble differs (intentional) +- `grep -rE "area/(docs|vscode|dashboard|consult|tower|cross-cutting|porch|protocols|config|terminal|scaffold|release|web|core)" codev-skeleton/` → no output (no vocabulary leak) +- `gh label list --search area/` → 14 labels +- Recipes in `codev/roles/architect.md` work against the live repo From 8e96f15f264c452194e82ace05cd92bb03e8a7ee Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:16:26 +1000 Subject: [PATCH 21/26] chore(porch): 909 record PR #912 --- .../909-architect-treat-area-labels-as/status.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 6845756a..abb4784c 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -19,4 +19,9 @@ iteration: 1 build_complete: false history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T08:14:14.578Z' +updated_at: '2026-05-28T08:16:26.255Z' +pr_history: + - phase: review + pr_number: 912 + branch: builder/pir-909 + created_at: '2026-05-28T08:16:26.254Z' From e695d1d9bb3e97d324ab77c7824aff2e77396890 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:16:35 +1000 Subject: [PATCH 22/26] chore(porch): 909 review build-complete --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index abb4784c..72f6d899 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -16,10 +16,10 @@ gates: pr: status: pending iteration: 1 -build_complete: false +build_complete: true history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T08:16:26.255Z' +updated_at: '2026-05-28T08:16:35.867Z' pr_history: - phase: review pr_number: 912 From ae8b4bf9361afe1cf1f921dc03e875c97bc5b6d3 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:21:48 +1000 Subject: [PATCH 23/26] [PIR #909] Rebut Codex REQUEST_CHANGES findings (plan-dedup procedural; frontmatter rule misapplied) --- .../plans/909-architect-treat-area-labels-as.md | 2 ++ .../909-architect-treat-area-labels-as.md | 16 ++++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/codev/plans/909-architect-treat-area-labels-as.md b/codev/plans/909-architect-treat-area-labels-as.md index 10e8bcd1..d1e6353d 100644 --- a/codev/plans/909-architect-treat-area-labels-as.md +++ b/codev/plans/909-architect-treat-area-labels-as.md @@ -186,6 +186,8 @@ During the implement phase, the reviewer's audit surfaced gaps the original plan **Final label set: 14 area labels.** The doc table in `CLAUDE.md`, `AGENTS.md`, and `codev/roles/architect.md` was rewritten to match. +**Content split (later in implement phase):** After the label-set restructure, the reviewer raised the duplication concern — the same vocabulary table + policy + recipes appeared in all three files. The original plan's "belt-and-suspenders" rationale (above, lines 22–25) was overridden by a different design choice authorized at the dev-approval gate: split content by audience. **`CLAUDE.md` / `AGENTS.md`** carry the vocabulary table + policy (every session auto-loads them). **`codev/roles/architect.md`** carries the operational recipes only (loaded only for architect spawns). No cross-references between files (each is self-contained for its audience). This deviates from the plan body's "same recipes in codev and skeleton" framing (line 71); the rationale and final shape are recorded in the review file's "Things to Look At During PR Review" section. + **Policy bullets touched:** - Removed: "All `gh issue create` invocations include `--assignee @me`." User correction: reporting an issue ≠ committing to do it. Self-assignment is appropriate only when the user is taking the work on, not by default. (Memory file [feedback-assign-issues-to-user] updated to match.) diff --git a/codev/reviews/909-architect-treat-area-labels-as.md b/codev/reviews/909-architect-treat-area-labels-as.md index 12290c5e..df5212d7 100644 --- a/codev/reviews/909-architect-treat-area-labels-as.md +++ b/codev/reviews/909-architect-treat-area-labels-as.md @@ -71,6 +71,22 @@ Updated `codev/resources/lessons-learned.md` with two durable lessons that emerg 6. **Shannon follow-up filed.** Issue [cluesmith/shannon#1872](https://github.com/cluesmith/shannon/issues/1872) tracks adopting the convention in shannon, with a 12-label proposed vocabulary derived from shannon's apps/packages layout. Out of scope for this PR but cross-linked for traceability. +## 3-Way Consultation Verdicts (PIR single-pass) + +PIR runs one advisory consultation pass at PR-creation (`max_iterations: 1`); there is no automated re-review. Below are the verdicts and the builder's disposition. The human at the `pr` gate is the sole remaining reviewer for any contested item. + +- **Gemini: APPROVE** (HIGH confidence). Endorsed the dedup as "structurally superior to the original plan" and called out the `--limit 500` fix as a good catch. +- **Claude: APPROVE** (HIGH confidence). Clean, no issues found. +- **Codex: REQUEST_CHANGES** (HIGH confidence), with two findings: + +### Codex finding 1: "Implementation deviates from the approved plan by splitting content across files instead of keeping each target self-contained" + +**Disposition: rebutted.** The plan's "belt-and-suspenders" framing (lines 22–25 of the plan) was overridden at the `dev-approval` gate by an explicit reviewer request to dedup. The new content split (vocabulary + policy in CLAUDE.md/AGENTS.md; recipes in `codev/roles/architect.md`) is documented in the plan file's "Scope Expansion" section (a "Content split" subsection has been added in response to this finding), in the thread file, and in point 3 of this section. Both Gemini and Claude evaluated the final split and approved it; Gemini specifically called it "structurally superior to the original plan." Mid-flight scope changes authorized at the human gate, with documented rationale, are the standard PIR mechanism for plan refinement — not a defect. No code change needed. + +### Codex finding 2: "Approved PIR plan file is missing required YAML frontmatter (`approved` / `validated`)" + +**Disposition: rebutted (misapplied rule).** The frontmatter requirement in `CLAUDE.md` lines 157-164 applies to *architect-pre-created* plans — when the architect writes a plan and approves it *before* spawning a builder, so porch can skip the plan phase. In #909, the builder wrote the plan during the plan phase under the PIR protocol; approval flowed through the `plan-approval` gate in `codev/projects/909-architect-treat-area-labels-as/status.yaml` (recorded `2026-05-28T...`). The status.yaml-recorded gate IS the approval mechanism for builder-written plans — adding YAML frontmatter would be redundant with porch state. No frontmatter is required for plans written via the PIR plan phase. No code change needed. + ## How to Test Locally For reviewers pulling the branch: From f4c80ca0ddefee101f7fe82bf87ed862116718e7 Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:22:05 +1000 Subject: [PATCH 24/26] chore(porch): 909 pr gate-requested --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 72f6d899..345bc770 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -15,13 +15,15 @@ gates: approved_at: '2026-05-28T08:14:00.023Z' pr: status: pending + requested_at: '2026-05-28T08:22:05.710Z' iteration: 1 build_complete: true history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T08:16:35.867Z' +updated_at: '2026-05-28T08:22:05.711Z' pr_history: - phase: review pr_number: 912 branch: builder/pir-909 created_at: '2026-05-28T08:16:26.254Z' +pr_ready_for_human: true From f537d35a0ca7312770736276da4927d79f66df0d Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:24:11 +1000 Subject: [PATCH 25/26] chore(porch): 909 pr gate-approved --- .../909-architect-treat-area-labels-as/status.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index 345bc770..f56e1f4b 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -14,16 +14,17 @@ gates: requested_at: '2026-05-28T05:29:23.678Z' approved_at: '2026-05-28T08:14:00.023Z' pr: - status: pending + status: approved requested_at: '2026-05-28T08:22:05.710Z' + approved_at: '2026-05-28T08:24:11.064Z' iteration: 1 build_complete: true history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T08:22:05.711Z' +updated_at: '2026-05-28T08:24:11.065Z' pr_history: - phase: review pr_number: 912 branch: builder/pir-909 created_at: '2026-05-28T08:16:26.254Z' -pr_ready_for_human: true +pr_ready_for_human: false From f091a8d17c04517f491f40d0a87f42b9ae8ca74c Mon Sep 17 00:00:00 2001 From: Amr Elsayed Date: Thu, 28 May 2026 18:24:22 +1000 Subject: [PATCH 26/26] chore(porch): 909 protocol complete --- codev/projects/909-architect-treat-area-labels-as/status.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/codev/projects/909-architect-treat-area-labels-as/status.yaml b/codev/projects/909-architect-treat-area-labels-as/status.yaml index f56e1f4b..a88f2f0e 100644 --- a/codev/projects/909-architect-treat-area-labels-as/status.yaml +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -1,7 +1,7 @@ id: '909' title: architect-treat-area-labels-as protocol: pir -phase: review +phase: verified plan_phases: [] current_plan_phase: null gates: @@ -21,7 +21,7 @@ iteration: 1 build_complete: true history: [] started_at: '2026-05-28T05:03:04.695Z' -updated_at: '2026-05-28T08:24:11.065Z' +updated_at: '2026-05-28T08:24:22.305Z' pr_history: - phase: review pr_number: 912