[Bug]: runtime-graph.json not built for very simple initial stage

[gmatev]

Description

First, apologies if this report is incomplete. Just trying out this project and learning.

I am trying to create a new plugin to replace the core "aidlc" plugin. The docs, and existing tests imply this is supported.

To get my feet wet, creating simple pass through stages that simply create an arfitact recording the name of the stage. The stage routing is based on a scope specific to the plugin. This is just to get a feel for the setup.

I am observing that I cannot exit my first stage because of missing runtime-graph.json

Steps to Reproduce

1. Create a new simple plugin

• Stages - stage1, stage2 (create .md artifacts that have a single# <stage> line)
• Scope - simple-scope - basically stage1 -> stage2

2. Create a project where only the simple plugin is installed.

3. Run with /aidlc --scope simple-scope "Create hello world" - the task is not important

4. Observe proper intent creation, stage1 entry, and stage 1 artifact creation

5. Observe attempt to go through the learning step which fails with missing runtime-graph.json

6. Attempted recovery with /aidlc --resume eventually fails with the same problem. Some of the output indicates that it tries to run aidlc engine graph compile which appears to be the wrong command anyway

Expected Behavior

User is able to complete stage 1 and eventually execute the full scope

Actual Behavior

Unable to exit stage1 because runtime-graph.json is misisng

AI-DLC Version

v2 (current on main)

Release / Commit

No response

AI-DLC Phase

Initialization

Harness

Codex CLI

AI Model

gpt-5.6-sol

Environment

• OS: MacOS
• Harness: codex-cli 0.154.0

Additional Context

I had Codex debug the session and it came up with

---

The hook saw the activity, but its filters prevented the runtime compiler from running:

1. aidlc engine intent create recorded STAGE_STARTED, but the hook’s command allowlist intentionally excludes intent commands. It returned before inspecting that event. See [aidlc-lib.ts (line 1663)](/.codex/tools/aidlc-lib.ts:1663).
2. Writing the Question artifact did not help because the runtime rebuild hook is attached only to Bash commands, not file writes. See [hooks.json (line 107)](/.codex/hooks.json:107).
3. The later reuse command produced QUESTION_ANSWERED and ARTIFACT_REUSED, but the hook only accepts these audit events:
   GATE_APPROVED, STAGE_STARTED, STAGE_AWAITING_APPROVAL, AUDIT_MERGED, UNIT_MERGED, or WORKFLOW_COMPLETED.
   See aidlc-rebuild-stage-graph.ts (line 188).
4. The next qualifying event would be STAGE_AWAITING_APPROVAL, but AI-DLC requires the learnings step before recording that event—and the learnings step refuses to run without runtime-graph.json.
   So this is a first-stage bootstrapping deadlock: the initial STAGE_STARTED event is skipped, while the next accepted event occurs only after a step that already requires the missing runtime graph.""

---

On the surface this makes sense, but I'm too new to the project to know if it accurate.
Looking at what it described in (1) the hook does indeed explicitly skip intent create which seems like a reasonable place to get this setup, but I lack the context for the decision why this is the case.

(2) Suggests that if my stage had used Bash in some way the graph would have been written. Have not tried it yet but is is not a reasonable requirement that this should be the case.

I can recover the intent with aidlc engine runtime compile but this is not ideal

[wowzoo]

Thanks for trying this out and for the report — the detail on which hook filters skipped the rebuild made the cause easy to find.

Both problems are addressed:

• A missing runtime-graph.json no longer stops the stage from finishing. The learnings step now derives the stage diary path from the compiled stage graph (stage-graph.json) and prints a warning instead of failing (fix: recompute the stage diary path when runtime-graph.json is absent #1230, in v2.10.0). That covers a plugin's own stages too, as long as they are in the compiled stage graph.
• The recovery hint was the wrong command, as you suspected. The doctor now points to runtime compile rather than graph compile (fix(doctor): compare the audit against the per-stage checkboxes #1272). That fix is on main and will ship in the next release.

Closing as fixed. If a plugin-only setup still cannot leave its first stage on a build that has both changes, please reopen with the /aidlc --doctor output.