diff --git a/AGENTS.md b/AGENTS.md index 8f6e140b..aa63633d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,6 +119,35 @@ 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. + +**Labels**: + +| Label | Scope | +|---|---| +| `area/docs` | Documentation — this repo, 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**. Other label families (if ever introduced) would keep colons. + **🚨 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..aa63633d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -119,6 +119,35 @@ 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. + +**Labels**: + +| Label | Scope | +|---|---| +| `area/docs` | Documentation — this repo, 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**. Other label families (if ever introduced) would keep colons. + **🚨 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..750e651f 100644 --- a/codev-skeleton/roles/architect.md +++ b/codev-skeleton/roles/architect.md @@ -257,6 +257,33 @@ gh issue view 42 Update status as projects progress: - `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` +## Working with Project 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:** + +```bash +# Confirm the current label vocabulary (use before any label op to catch drift) +gh label list --search "/" + +# 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 +``` + ## Handling Blocked Builders When a builder reports blocked: diff --git a/codev-skeleton/templates/AGENTS.md b/codev-skeleton/templates/AGENTS.md index 8b68b16e..463c1bc9 100644 --- a/codev-skeleton/templates/AGENTS.md +++ b/codev-skeleton/templates/AGENTS.md @@ -47,6 +47,28 @@ 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.** `/` 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. + ## 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..19f545b1 100644 --- a/codev-skeleton/templates/CLAUDE.md +++ b/codev-skeleton/templates/CLAUDE.md @@ -45,6 +45,28 @@ 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.** `/` 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. + ## Quick Start 1. For new features, start with the Specification phase 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..d1e6353d --- /dev/null +++ b/codev/plans/909-architect-treat-area-labels-as.md @@ -0,0 +1,231 @@ +# 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 spans two distinct propagation paths into other repos, so the file split has to honor both: + +**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 (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 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: + +- 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) — 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) + +**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; 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:** + +- **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). Codev-specific vocabulary. +- `AGENTS.md` — apply the **byte-identical** insertion. Verify with `diff CLAUDE.md AGENTS.md` (must be empty after the edit). +- `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. + +## 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). + +## Scope Expansion (2026-05-28, post plan-approval) + +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: + +**Labels added** (5): + +- `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`. + +**Labels removed** (1): + +- `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. + +**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.) +- 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 + +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 **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 -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. + - 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. 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..a88f2f0e --- /dev/null +++ b/codev/projects/909-architect-treat-area-labels-as/status.yaml @@ -0,0 +1,30 @@ +id: '909' +title: architect-treat-area-labels-as +protocol: pir +phase: verified +plan_phases: [] +current_plan_phase: null +gates: + plan-approval: + status: approved + requested_at: '2026-05-28T05:06:26.853Z' + approved_at: '2026-05-28T05:19:16.527Z' + dev-approval: + status: approved + requested_at: '2026-05-28T05:29:23.678Z' + approved_at: '2026-05-28T08:14:00.023Z' + pr: + 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:24:22.305Z' +pr_history: + - phase: review + pr_number: 912 + branch: builder/pir-909 + created_at: '2026-05-28T08:16:26.254Z' +pr_ready_for_human: false 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..df5212d7 --- /dev/null +++ b/codev/reviews/909-architect-treat-area-labels-as.md @@ -0,0 +1,114 @@ +# 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. + +## 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: + +- **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 diff --git a/codev/roles/architect.md b/codev/roles/architect.md index 763c93ce..cd3c0709 100644 --- a/codev/roles/architect.md +++ b/codev/roles/architect.md @@ -256,6 +256,31 @@ gh issue view 42 Update status as projects progress: - `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` +## Working with Area Labels + +**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 +``` + ## Handling Blocked Builders When a builder reports blocked: diff --git a/codev/state/pir-909_thread.md b/codev/state/pir-909_thread.md new file mode 100644 index 00000000..6b176639 --- /dev/null +++ b/codev/state/pir-909_thread.md @@ -0,0 +1,125 @@ +# 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`. + +## 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. + +## 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. + +## 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. + +## 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) + +## 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.