Auto-finish: agent/claude/remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27 (#583)

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

.agents

@@ -59,10 +59,6 @@ logs/*
 .dev-ports.json
 apps/logs/*.log
 
-.agents/hooks/state/
-.agents/.personality_migration
-.agents/version.json
-.agents/log/
 .venv
 
 .omx/

.gitignore

@@ -14,7 +14,3 @@
 	path = examples/skills_for_claude
 	url = https://github.com/NagyVikt/skills_for_claude.git
 	branch = main
-[submodule "vscode-material-icon-theme"]
-	path = vscode-material-icon-theme
-	url = https://github.com/NagyVikt/vscode-material-icon-theme.git
-	branch = main

.gitmodules

@@ -85,7 +85,7 @@ The `/project-conventions` skill is auto-activated on code edits (PreToolUse gua
 | Convention              | Location                              | When                         |
 | ----------------------- | ------------------------------------- | ---------------------------- |
 | Code Conventions (Full) | `/project-conventions` skill          | On code edit (auto-enforced) |
-| Git Workflow            | `.agents/conventions/git-workflow.md` | Commit / PR                  |
+| Git Workflow            | `.codex/conventions/git-workflow.md` | Commit / PR                  |
 
 ## UI/UX Skill Default (UI Pro Max)
 
@@ -99,7 +99,8 @@ The `/project-conventions` skill is auto-activated on code edits (PreToolUse gua
 - Do not commit ephemeral local runtime artifacts (for example `.dev-ports.json` and `apps/logs/*.log`).
 - Treat local OMX/Codex session state files as agent-ignored (as if they were in `.gitignore`) even when they appear in working tree status.
 - Never stage or commit:
-  - `.agents/settings.local.json`
+  - `.codex/settings.local.json`
+  - `.claude/settings.local.json`
   - `.omc/project-memory.json`
   - `.omc/state/**`
   - `.omx/state/**`

AGENTS.md

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-15

openspec/changes/agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27/.openspec.yaml

@@ -0,0 +1,22 @@
+## Why
+
+- The `vscode-material-icon-theme` submodule was added three weeks ago but is not used by anything in the repo — it pulls in unrelated upstream history and clutters the root listing.
+- The `.agents` symlink at the repo root is a dead backward-compat bridge: it points at `.codex` and exists only so legacy paths like `.agents/hooks/skill_guard.py` keep resolving. No live tooling, hook config, or settings file references those paths anymore (the `repo hook settings reference real local hook directories` test already enforces that `.agents/hooks/...` cannot appear in any settings command).
+- Carrying both surfaces costs visible structural noise at the repo root, drags four stale `.gitignore` entries for paths that no longer exist (`.agents/hooks/state/`, `.agents/.personality_migration`, `.agents/version.json`, `.agents/log/`), and forces multi-agent state-file globs in three scripts plus the agent contract to list `.agents/settings.local.json` alongside the real `.codex` / `.claude` paths.
+
+## What Changes
+
+- Remove the `vscode-material-icon-theme` submodule (gitlink + `.gitmodules` stanza).
+- Delete the `.agents` symlink. All resolved content stays in place under `.codex` (and the per-agent variant under `.claude`).
+- Drop the `.agents/hooks/skill_guard.py` entry from the skill-guard regression test — the remaining `.codex` and `.claude` copies already prove identical behavior.
+- Replace `.agents/conventions/git-workflow.md` with `.codex/conventions/git-workflow.md` in the agent contract's Code Conventions table.
+- Replace the single `.agents/settings.local.json` line in the Git Hygiene "Never stage or commit" list with the two real per-agent paths (`.codex/settings.local.json`, `.claude/settings.local.json`).
+- Update the auto-transfer / auto-resolve / worktree-prune exclude globs in `templates/scripts/agent-branch-start.sh`, `templates/scripts/agent-branch-finish.sh`, and `templates/scripts/agent-worktree-prune.sh` the same way.
+- Drop the four stale `.agents/...` entries from `.gitignore`.
+- Keep the negative assertion in `test/setup.test.js` that no settings command references `/.agents/hooks/` — it is now a regression guard against re-introducing the bridge.
+
+## Impact
+
+- Affected surfaces: repo root layout, `.gitmodules`, `.gitignore`, `AGENTS.md` / `CLAUDE.md` (symlinked), `test/setup.test.js`, three `templates/scripts/*.sh`.
+- Risk: external user-level Codex configs that hardcode `.agents/hooks/skill_guard.py` would lose the bridge. The repo's own settings files (`.codex/settings.json`, `.claude/settings.json`) already point at `.codex/hooks/...` and `.claude/hooks/...` directly, so in-repo behavior is unaffected. Any user with an older host config can simply point it at the per-agent hook path.
+- No published version bump (no behavior surface for downstream `gx` consumers changes — the template glob defaults expand cleanly with the two replacement entries).

openspec/changes/agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27/proposal.md

@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Repo root SHALL NOT carry the `vscode-material-icon-theme` submodule
+
+The system SHALL keep the repo root free of the `vscode-material-icon-theme` submodule and its `.gitmodules` registration.
+
+#### Scenario: `.gitmodules` no longer registers `vscode-material-icon-theme`
+- **WHEN** a contributor inspects `.gitmodules` at `HEAD`
+- **THEN** no stanza named `[submodule "vscode-material-icon-theme"]` is present
+- **AND** `git submodule status` does not list a `vscode-material-icon-theme` entry.
+
+#### Scenario: `vscode-material-icon-theme` path is gone from the working tree
+- **WHEN** a contributor runs `ls vscode-material-icon-theme` at the repo root
+- **THEN** the path does not exist
+- **AND** `git ls-tree HEAD vscode-material-icon-theme` returns no entry.
+
+### Requirement: Repo root SHALL NOT carry the legacy `.agents` bridge symlink
+
+The system SHALL remove the `.agents` symlink at the repo root and rely on the per-agent `.codex/` and `.claude/` surfaces directly.
+
+#### Scenario: `.agents` is absent from `HEAD`
+- **WHEN** a contributor runs `git ls-tree HEAD .agents`
+- **THEN** the command returns no entry
+- **AND** no `.agents` path exists in the working tree.
+
+#### Scenario: Internal references migrate off `.agents`
+- **WHEN** a contributor greps the repo (excluding `openspec/changes/archive/` and any historical `agent-codex-*` change folders) for `\.agents/`
+- **THEN** the only match is the negative regex guard in `test/setup.test.js` that asserts settings commands MUST NOT reference `/.agents/hooks/`.
+
+#### Scenario: Stale ignore patterns are dropped
+- **WHEN** a contributor inspects `.gitignore`
+- **THEN** none of `.agents/hooks/state/`, `.agents/.personality_migration`, `.agents/version.json`, `.agents/log/` appear.
+
+### Requirement: Multi-agent state-file glob defaults SHALL reference the real per-agent paths
+
+The system SHALL list the live `.codex/settings.local.json` and `.claude/settings.local.json` paths (not `.agents/settings.local.json`) in the auto-transfer, auto-resolve, and worktree-prune state-file glob defaults.
+
+#### Scenario: Template script defaults expand cleanly
+- **WHEN** a contributor inspects `AUTO_TRANSFER_EXCLUDE_DEFAULT` in `templates/scripts/agent-branch-start.sh`, `AUTO_RESOLVE_SAFE_GLOBS_DEFAULT` in `templates/scripts/agent-branch-finish.sh`, and `WORKTREE_STATE_EXCLUDE_GLOBS_DEFAULT` in `templates/scripts/agent-worktree-prune.sh`
+- **THEN** each default contains `:.codex/settings.local.json:.claude/settings.local.json:`
+- **AND** none of them contain `:.agents/settings.local.json:`.
+
+#### Scenario: Agent contract Git Hygiene list matches
+- **WHEN** a contributor reads the "Never stage or commit" list in `AGENTS.md` (and the `CLAUDE.md` symlink)
+- **THEN** `.codex/settings.local.json` and `.claude/settings.local.json` are present
+- **AND** `.agents/settings.local.json` is absent.

openspec/changes/agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27/specs/remove-vscode-icon-submodule-and-prune-agents-dir/spec.md

@@ -0,0 +1,37 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27`; branch=`agent/claude/remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27`; scope=`drop vscode submodule + legacy .agents bridge + migrate state-file globs`; action=`continue in worktree or finish via gx branch finish ... --via-pr --wait-for-merge --cleanup`.
+- Copy prompt: Continue `agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27` on branch `agent/claude/remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27`. Work inside the existing sandbox, review `openspec/changes/agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/claude/remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27`.
+- [x] 1.2 Define normative requirements in `specs/remove-vscode-icon-submodule-and-prune-agents-dir/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Drop the `vscode-material-icon-theme` submodule (gitlink + `.gitmodules` stanza).
+- [x] 2.2 Delete the `.agents` symlink and remove its four stale `.gitignore` entries.
+- [x] 2.3 Migrate the agent contract's Code Conventions row from `.agents/conventions/git-workflow.md` to `.codex/conventions/git-workflow.md`.
+- [x] 2.4 Replace `.agents/settings.local.json` with the live `.codex/settings.local.json` + `.claude/settings.local.json` entries in `AGENTS.md`'s "Never stage or commit" list and in the three `templates/scripts/*.sh` glob defaults.
+- [x] 2.5 Drop the `.agents/hooks/skill_guard.py` import from the skill-guard regression test; keep the negative assertion that settings commands must not reference `/.agents/hooks/`.
+
+## 3. Verification
+
+- [ ] 3.1 Run `node --test test/setup.test.js` and confirm both the "repo hook settings reference real local hook directories" and "repo skill guard blocks shell output redirect bypasses" tests pass.
+- [ ] 3.2 Run `openspec validate agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27 --type change --strict`.
+- [ ] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/claude/remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).

openspec/changes/agent-claude-remove-vscode-icon-submodule-and-prune-a-2026-05-16-00-27/tasks.md

@@ -17,7 +17,7 @@ WAIT_TIMEOUT_SECONDS_RAW="${GUARDEX_FINISH_WAIT_TIMEOUT_SECONDS:-1800}"
 WAIT_POLL_SECONDS_RAW="${GUARDEX_FINISH_WAIT_POLL_SECONDS:-10}"
 PARENT_GITLINK_AUTO_COMMIT_RAW="${GUARDEX_FINISH_PARENT_GITLINK_AUTO_COMMIT:-true}"
 AUTO_RESOLVE_MODE_RAW="${GUARDEX_FINISH_AUTO_RESOLVE:-none}"
-AUTO_RESOLVE_SAFE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+AUTO_RESOLVE_SAFE_GLOBS_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.codex/settings.local.json:.claude/settings.local.json:.codex/state/**:.claude/state/**'
 AUTO_RESOLVE_SAFE_GLOBS_RAW="${GUARDEX_FINISH_AUTO_RESOLVE_SAFE_GLOBS-$AUTO_RESOLVE_SAFE_GLOBS_DEFAULT}"
 PREFLIGHT_ENABLED_RAW="${GUARDEX_FINISH_PREFLIGHT:-true}"
 PREFLIGHT_SCRIPT_RAW="${GUARDEX_FINISH_PREFLIGHT_SCRIPT:-scripts/agent-preflight.sh}"

templates/scripts/agent-branch-finish.sh

@@ -17,7 +17,7 @@ OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 OPENSPEC_TIER_RAW="${GUARDEX_OPENSPEC_TIER:-T3}"
 REUSE_EXISTING_RAW="${GUARDEX_BRANCH_START_REUSE_EXISTING:-true}"
 AUTO_TRANSFER_ENABLED_RAW="${GUARDEX_AUTO_TRANSFER:-true}"
-AUTO_TRANSFER_EXCLUDE_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.agents/settings.local.json:.codex/state/**:.claude/state/**'
+AUTO_TRANSFER_EXCLUDE_DEFAULT='.omc/**:.omx/state/**:.dev-ports.json:apps/logs/**:.codex/settings.local.json:.claude/settings.local.json:.codex/state/**:.claude/state/**'
 AUTO_TRANSFER_EXCLUDE_RAW="${GUARDEX_AUTO_TRANSFER_EXCLUDE-$AUTO_TRANSFER_EXCLUDE_DEFAULT}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()