Move steering.md into .agent-fox/ folder

[mickume]

Summary

Move steering.md from its current location into the .agent-fox/ folder to consolidate agent configuration files.

Current State

steering.md is referenced in CLAUDE.md at .agent-fox/specs/steering.md, but it should live directly under .agent-fox/ as a project-level directive file rather than nested under specs.

Change

Move steering.md to .agent-fox/steering.md and update any references accordingly.

[mickume]

Starting fix session on branch fix/549-move-steeringmd-into-agent-fox-folder... (run: 20260426_183120_257e71)

[mickume]

Triage Report

Summary: The steering.md file lives at .agent-fox/specs/steering.md but the issue requires it to move to .agent-fox/steering.md to consolidate agent configuration files directly under .agent-fox/. Three code sites enforce the old location: (1) agent_fox/session/steering.py derives the path as {spec_root}/steering.md, passing spec_dir.parent as the spec root; (2) agent_fox/workspace/init_project.py's _ensure_steering_md() creates the file inside the spec root directory; (3) the _GITIGNORE_ENTRIES constant does not include a !.agent-fox/steering.md exemption so the moved file would be ignored by git. All skill templates, the AGENTS.md template, CLAUDE.md, and the installed .claude/skills/*/SKILL.md files also reference the old path and need updating. Tests hardcode the old path in several places.

Affected files:

• agent_fox/session/steering.py
• agent_fox/workspace/init_project.py
• agent_fox/session/context.py
• CLAUDE.md
• agent_fox/_templates/agents_md.md
• agent_fox/_templates/profiles/agent.md
• agent_fox/_templates/skills/af-spec-audit
• agent_fox/_templates/skills/af-clone-issue
• agent_fox/_templates/skills/af-fix
• agent_fox/_templates/skills/af-spec
• agent_fox/_templates/skills/af-security-audit
• agent_fox/_templates/skills/af-code-simplifier
• agent_fox/_templates/skills/af-adr
• agent_fox/_templates/skills/af-reverse-engineer
• .claude/skills/af-spec-audit/SKILL.md
• .claude/skills/af-clone-issue/SKILL.md
• .claude/skills/af-fix/SKILL.md
• .claude/skills/af-spec/SKILL.md
• .claude/skills/af-security-audit/SKILL.md
• .claude/skills/af-code-simplifier/SKILL.md
• .claude/skills/af-adr/SKILL.md
• .claude/skills/af-reverse-engineer/SKILL.md
• tests/unit/cli/test_steering.py
• tests/unit/session/test_steering.py
• tests/integration/test_steering.py
• .agent-fox/specs/steering.md

Acceptance Criteria

AC-1: _ensure_steering_md() creates the steering file at .agent-fox/steering.md, not .agent-fox/specs/steering.md.

• Preconditions: A fresh tmp_path with no pre-existing .agent-fox/ directory.
• Expected: After calling _ensure_steering_md(tmp_path), the file tmp_path / '.agent-fox' / 'steering.md' exists and contains the placeholder sentinel. tmp_path / '.agent-fox' / 'specs' / 'steering.md' does not exist.
• Assertion: In tests/unit/cli/test_steering.py, TestInitCreatesSteeringFile.test_file_exists_after_call asserts (tmp_path / '.agent-fox' / 'steering.md').exists(). The test currently asserts the .agent-fox/specs/ path and must be updated; after the fix it must pass with the new path.

AC-2: load_steering() reads from {project_root}/.agent-fox/steering.md instead of {spec_root}/steering.md.

• Preconditions: A tmp_path with .agent-fox/steering.md containing real directives (no placeholder sentinel).
• Expected: load_steering(tmp_path) returns the directive content. A file at .agent-fox/specs/steering.md with content is ignored. A missing .agent-fox/steering.md returns None without raising.
• Assertion: Update tests/unit/session/test_steering.py so fixture setup writes to tmp_path / '.agent-fox' / 'steering.md' (not tmp_path / '.specs' / 'steering.md'); all existing test assertions must still pass after the path change.

AC-3: The .gitignore entries in init_project.py include !.agent-fox/steering.md so the file is tracked by git after af init.

• Preconditions: A project root with .agent-fox/* in .gitignore (the default agent-fox entry).
• Expected: After init_project() runs, the .gitignore file contains !.agent-fox/steering.md, ensuring git does not ignore the file. Running git ls-files .agent-fox/steering.md in an initialized project returns the file path.
• Assertion: Grep agent_fox/workspace/init_project.py for !.agent-fox/steering.md in _GITIGNORE_ENTRIES. Assert the string is present. Also verify the existing !.agent-fox/specs/ entry is retained (specs directory is still tracked).

AC-4: All skill templates and documentation files reference .agent-fox/steering.md instead of {{SPEC_ROOT}}/steering.md or .agent-fox/specs/steering.md.

• Preconditions: The templates under agent_fox/_templates/skills/, agent_fox/_templates/agents_md.md, agent_fox/_templates/profiles/agent.md, and CLAUDE.md exist at their current paths.
• Expected: No template or documentation file contains the string .agent-fox/specs/steering.md or {{SPEC_ROOT}}/steering.md. All references read .agent-fox/steering.md. Installed .claude/skills/*/SKILL.md files are updated to match.
• Assertion: Run grep -r 'specs/steering\.md\|{\{SPEC_ROOT\}}/steering\.md' agent_fox/_templates/ .claude/skills/ CLAUDE.md; the command must produce no output.

AC-5: The physical steering.md file is relocated via git mv and all tests pass after the move.

• Preconditions: .agent-fox/specs/steering.md exists and is tracked by git. No .agent-fox/steering.md yet exists.
• Expected: git ls-files .agent-fox/steering.md returns the file. git ls-files .agent-fox/specs/steering.md returns nothing. make check (lint + full test suite) exits with code 0.
• Assertion: After the change, run git status — it must show a rename from .agent-fox/specs/steering.md to .agent-fox/steering.md. Then run make check and confirm exit code 0 with no test failures.

(run: 20260426_183120_257e71)

[mickume]

Fix Review Report

Overall verdict: FAIL

Summary: No fix was implemented. The branch contains only auto-generated errata file modifications. All five acceptance criteria fail because: (1) _ensure_steering_md() still creates at .agent-fox/specs/steering.md, (2) load_steering() still reads from {spec_root}/steering.md, (3) .gitignore entries lack !.agent-fox/steering.md, (4) all templates still reference {{SPEC_ROOT}}/steering.md or .agent-fox/specs/steering.md, and (5) the physical file was never moved via git mv.

Per-criterion verdicts

• ❌ AC-1: FAIL
  • Evidence: _ensure_steering_md() in agent_fox/workspace/init_project.py still writes to specs_dir / 'steering.md' (line 353), where specs_dir defaults to .agent-fox/specs/. Test test_file_exists_after_call at tests/unit/cli/test_steering.py:39 still asserts tmp_path / '.agent-fox' / 'specs' / 'steering.md'. No code was changed on this branch.
• ❌ AC-2: FAIL
  • Evidence: load_steering() in agent_fox/session/steering.py still reads from spec_root / _STEERING_FILENAME (line 44), resolving to {spec_root}/steering.md. Tests in tests/unit/session/test_steering.py still write fixtures to tmp_path / '.specs' / 'steering.md'. No path change was made.
• ❌ AC-3: FAIL
  • Evidence: _GITIGNORE_ENTRIES in agent_fox/workspace/init_project.py (lines 28-36) does not contain !.agent-fox/steering.md. grep for !.agent-fox/steering.md returns no matches. No change was made.
• ❌ AC-4: FAIL
  • Evidence: grep confirms 9 template files still reference {{SPEC_ROOT}}/steering.md (e.g., agent_fox/_templates/skills/af-fix:27, agent_fox/_templates/agents_md.md:14). agent_fox/_templates/profiles/agent.md:11 still references .specs/steering.md. CLAUDE.md:14 still references .agent-fox/specs/steering.md. No references were updated.
• ❌ AC-5: FAIL
  • Evidence: git ls-files .agent-fox/specs/steering.md returns the file (still at old location). git ls-files .agent-fox/steering.md returns nothing. git diff develop --name-status shows only errata files modified — no git mv was performed. make check exits with code 2 (pre-existing ADR import errors unrelated to this issue, but exit code is non-zero).

(run: 20260426_183120_257e71)

[mickume]

Fix Review Report

Overall verdict: FAIL

Summary: The fix for issue #549 has not been implemented. The branch fix/549-move-steeringmd-into-agent-fox-folder has zero commits beyond develop. steering.md remains at .agent-fox/specs/steering.md, all code and templates still reference the old path, _GITIGNORE_ENTRIES lacks the new path entry, and no tests have been updated. All five acceptance criteria fail.

Per-criterion verdicts

• ❌ AC-1: FAIL
  • Evidence: No code changes made. tests/unit/cli/test_steering.py line 39 still asserts tmp_path / '.agent-fox' / 'specs' / 'steering.md'. The _ensure_steering_md() function still creates the file at the old specs/ path. git log develop..HEAD shows zero commits on the fix branch.
• ❌ AC-2: FAIL
  • Evidence: No code changes made. agent_fox/session/steering.py line 44 still resolves spec_root / _STEERING_FILENAME (i.e. reads from specs/steering.md, not .agent-fox/steering.md). tests/unit/session/test_steering.py lines 30-32 still write fixtures to tmp_path / '.specs' / 'steering.md'.
• ❌ AC-3: FAIL
  • Evidence: No code changes made. agent_fox/workspace/init_project.py _GITIGNORE_ENTRIES (lines 28-36) does not contain '!.agent-fox/steering.md'. Only '!.agent-fox/specs/' is present.
• ❌ AC-4: FAIL
  • Evidence: No code changes made. grep found '.agent-fox/specs/steering.md' in: CLAUDE.md, AGENTS.md, .claude/skills/af-fix/SKILL.md, .claude/skills/af-spec/SKILL.md, .claude/skills/af-adr/SKILL.md, .claude/skills/af-reverse-engineer/SKILL.md, .claude/skills/af-clone-issue/SKILL.md, .claude/skills/af-code-simplifier/SKILL.md, .claude/skills/af-security-audit/SKILL.md, .claude/skills/af-spec-audit/SKILL.md, agent_fox/_templates/profiles/agent.md, and docs/architecture.md. Also found '{{SPEC_ROOT}}/steering.md' references in archived spec docs.
• ❌ AC-5: FAIL
  • Evidence: No code changes made. git ls-files .agent-fox/specs/steering.md returns the file. git ls-files .agent-fox/steering.md returns nothing. The file has not been moved. git status shows only modified errata files, no rename.

(run: 20260426_183120_257e71)

[mickume]

Fix Review Report

Overall verdict: PASS

Summary: All 5 acceptance criteria are satisfied. steering.md is relocated from .agent-fox/specs/ to .agent-fox/, all code paths (init, load, templates, gitignore) reference the new location, and all 39 steering-related tests pass. The 2 test collection errors in make check are pre-existing (spec 117 ADR module not yet implemented) and unrelated to this fix.

Per-criterion verdicts

• ✅ AC-1: PASS
  • Evidence: _ensure_steering_md() at init_project.py:340-372 creates the file at project_root/.agent-fox/steering.md (line 351: steering_path = agent_fox_dir / 'steering.md' where agent_fox_dir = project_root / '.agent-fox'). Test test_file_exists_after_call at tests/unit/cli/test_steering.py:34-40 asserts (tmp_path / '.agent-fox' / 'steering.md').exists(). All 7 CLI steering tests pass.
• ✅ AC-2: PASS
  • Evidence: load_steering() at session/steering.py:27-83 reads from project_root / '.agent-fox' / 'steering.md' (line 42). The spec_root parameter is deprecated and ignored (line 33). Tests in tests/unit/session/test_steering.py write to tmp_path / '.agent-fox' / 'steering.md' (e.g., lines 30-32, 115-117, 155-157). All 13 session steering tests pass including symlink rejection, placeholder detection, and error handling.
• ✅ AC-3: PASS
  • Evidence: init_project.py _GITIGNORE_ENTRIES at line 32 contains '!.agent-fox/steering.md'. The '!.agent-fox/specs/' entry is retained at line 33. The _update_gitignore() function adds these entries to .gitignore.
• ✅ AC-4: PASS
  • Evidence: grep -r 'specs/steering.md|{{SPEC_ROOT}}/steering.md' agent_fox/_templates/ .claude/skills/ CLAUDE.md produced no output (exit code 1). All 19 references across templates, skills, AGENTS.md, and CLAUDE.md now use '.agent-fox/steering.md'.
• ✅ AC-5: PASS
  • Evidence: git ls-files .agent-fox/steering.md returns the file. git ls-files .agent-fox/specs/steering.md returns nothing. git diff --stat shows '.agent-fox/{specs => }/steering.md | 0' confirming the rename. make check: 4463 passed, 2 errors (pre-existing ModuleNotFoundError for agent_fox.knowledge.adr from spec 117 failing tests — confirmed present on parent commit). Lint passes (ruff check + format).

(run: 20260426_183120_257e71)

[mickume]

Fix complete on branch fix/549-move-steeringmd-into-agent-fox-folder. Changes have been merged into develop. Create a PR from that branch to land them on main. (run: 20260426_183120_257e71)