fix(codex): keep graph-first guidance with dirty graph output (#913)

* fix(codex): keep graph-first guidance with dirty graph output

* fix(codex): include dirty graph guidance in agents install

---------

Co-authored-by: hanmo1 <hanmo1@lenovo.com>

graphify/__main__.py

@@ -311,6 +311,7 @@ When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"
 
 Rules:
 - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
 - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

graphify/skill-codex.md

@@ -55,6 +55,8 @@ If the user invoked `/graphify --help` or `/graphify -h` (with no other argument
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
+If `graphify-out/` exists, use `graphify query`, `graphify explain`, or `graphify path` for orientation before broad grep, rg, or multi-file reads. Dirty `graphify-out/` artifacts are expected after hooks or incremental updates; dirty graph files are not a reason to skip Graphify. Only skip Graphify if the task is specifically about stale or incorrect graph output, or the user explicitly says not to use it.
+
 Follow these steps in order. Do not skip steps.
 
 ### Step 1 - Ensure graphify is installed

tests/test_install.py

@@ -104,6 +104,24 @@ def test_codex_skill_contains_spawn_agent():
     assert "spawn_agent" in skill
 
 
+def test_codex_skill_uses_graphify_with_dirty_graph_output():
+    """Codex skill must keep graph-first orientation even when graph output is dirty."""
+    import graphify
+    skill = (Path(graphify.__file__).parent / "skill-codex.md").read_text()
+    assert "Dirty `graphify-out/` artifacts are expected" in skill
+    assert "not a reason to skip Graphify" in skill
+    assert "graphify query" in skill
+    assert "graphify explain" in skill
+    assert "graphify path" in skill
+
+
+def test_codex_agents_install_mentions_dirty_graph_output(tmp_path):
+    _agents_install(tmp_path, "codex")
+    content = (tmp_path / "AGENTS.md").read_text()
+    assert "Dirty graphify-out/ files are expected" in content
+    assert "not a reason to skip graphify" in content
+
+
 def test_opencode_skill_contains_mention():
     """OpenCode skill file must reference @mention."""
     import graphify

tests/test_install_strings.py

@@ -115,3 +115,8 @@ def test_report_is_still_referenced_as_fallback():
         f"The fix should demote the report, not delete the reference — users need to know "
         f"it's available for broad-architecture queries."
     )
+
+
+def test_agents_section_does_not_skip_dirty_graph_output():
+    assert "Dirty graphify-out/ files are expected" in _AGENTS_MD_SECTION
+    assert "not a reason to skip graphify" in _AGENTS_MD_SECTION