sdd-implement

Walk the Plan Graph

Resources

Before opening shared/..., follow symlinks in this loaded file's path, then derive <plugin-root> from <plugin-root>/skills/<name>/SKILL.md; fallback search roots are repository/user .agents/ (including $HOME/.agents/plugins/*/), Codex ${CODEX_HOME:-$HOME/.codex}/plugins/cache/*/*/*/, and runtime-configured skill roots. Accept only a root containing this skill, shared/agent-runtime.md, and the matching plugin manifest; never use the working directory. Then read <plugin-root>/shared/agent-runtime.md, <plugin-root>/shared/path-resolution.md, <plugin-root>/shared/vcs-detection.md, <plugin-root>/shared/autonomy.md, <plugin-root>/shared/completion-evidence.md, and <plugin-root>/shared/language-verification.md with the matching <plugin-root>/shared/language-specs/ reference file.

Resource boundary: Read the plugin, all SKILL.md files, and shared/ resources in place. Never copy or symlink them into the working directory, target repository, or planning root. Only generated SDD outputs may be materialized from bundled resources.

Routing: Graph Plans vs v1 Plans

Route by graph presence:

• Plans/<Name>/<Name>-Graph.json exists → the walk loop below. States derive from observations; completion is sync-only; the sdd binary refuses everything a narrated protocol used to let drift.
• No graph → the plan is a v1 markdown plan and keeps the v1 protocol (§ v1 Plans below) until converted with sdd graph convert.

The Walk Loop

The loop is claim → red → green → sync → merge, repeated until the frontier is empty. Every arrow is a CLI call whose refusal text names the fix. You never assert an outcome — you show the tool a report and it records what the report says.

1. Preconditions. Plan README status is approved or active (flip approved → active when starting). sdd graph status --plan <Name> for the derived picture: state counts, closure, claims.
2. Claim. sdd next Plans/<Name> --claim --by <identity> claims the heaviest claimable frontier node, records a lease, and allocates an isolated workspace (git targets: a worktree on its own branch). The printed payload carries contract, cited requirement text, named tests, hazard triage, and workspace path — don't re-read plan documents for what it already states. When nothing is claimable, react to the refusal's actual reason (capacity, BLOCKED/RED nodes, or a genuinely finished walk).
3. Red — prove the tests can fail. Write the node's named tests first (runner-visible ids must match the payload exactly), run them in the workspace against the unimplemented or broken state, and sync the failing report: sdd graph sync --plan <Name> --node <id> --by <identity> --report red.xml. A red run is a successful sync — it stamps red_seq, which arms red-before-green: a hazard-discharging test never observed failing will refuse the later green.
4. Green — implement, commit, sync the pass. Implement inside the workspace until the named tests pass. Commit the complete slice in the workspace first — sync refuses a passing report from a dirty worktree, because the revision anchor must name the tested bytes. Then sync the passing report. A clean pass by the claim holder merges atomically: observation recorded, claim cleared, workspace released. A shared-dirty pass records provisionally instead (STALE, never GREEN) until a clean re-verify. There is no assert path.
5. Integrate the slice into the mainline. The merging sync completes the claim; the VCS integration is a separate deliberate act because it can conflict, and conflicts are judgment. On git targets the workspace branch survives the release (git branch --list 'graph/<id>-*') — merge it into the mainline checkout now. Until the bytes land on the mainline the node honestly derives STALE from the shared tree; integration self-heals it to GREEN. Integrate after every merge, before the next claim of dependent work.
6. Between rounds. sdd graph status between claims; sdd graph path when choosing what to unblock. Command gates: run the gate's command and sdd graph sync --node <id> --command-exit <N> --command-log out.txt. Review gates: run the four-lane review flow (sdd review scaffold → fill lanes → sdd review resolve), then sdd graph review --plan <Name> --node <gate> --artifact <frozen review path>. The artifact must be resolved + frozen: true + verdict Aligned (all three — a reopened review is not evidence), must review a document of this plan, and greens exactly one gate. Findings that name scope nodes demote them to RED in the same write — the finding doing its job, not an error to route around. Record gates after the scope's work is integrated into the mainline.