Support serial dependency ordering for actions and targets

[lodyai]

Problem

Netsuke currently treats dependencies as a graph. A consumer that needs an
aggregate workflow to run named gates in a defined sequence must either nest
netsuke build invocations or create synthetic proxy actions and rules solely
to impose ordering. Both alternatives make the manifest harder to read.

Requirement

Actions and targets should be able to request serial execution of their direct
dependencies. A declarative field such as dependency_order: serial would be
clearer than a bare serial flag.

For a serial dependency list, Netsuke should:

• run dependencies in declaration order;
• run a shared dependency at most once for the encompassing build;
• stop before later dependencies when an earlier dependency fails; and
• retain the existing parallel behaviour when the field is omitted.

The serial property should affect only the dependencies of the annotated action
or target. It should not act as a global worker limit or accidentally
serialise unrelated graph branches.

Example

Catnap currently implements its comprehensive all action with nested
Netsuke invocations so formatting, linting, tests, and spelling run in order:

https://github.com/leynos/catnap/blob/a4499e3a7c508325a39c2cb46f06532a63172863/Netsukefile#L3-L9

A native serial-dependency feature would allow that action to declare the
ordered gates directly. It would eliminate the nested orchestration while
keeping the public gates independently runnable.

Acceptance criteria

• Document the action and target syntax and its execution semantics.
• Preserve declared order in generated Ninja execution.
• Add regression coverage for ordering, shared dependencies, failure
  short-circuiting, and the unchanged default parallel behaviour.
• Keep serialisation scoped to the annotated dependency list.

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

Add a closed dependency_order enum field on Target in the AST, defaulting to Parallel, so existing manifests stay unaffected.

Lower a serial deps list into a deterministic chain of phony gate edges, where each gate aliases one dependency and depends order-only on the previous gate. This enforces declaration order, propagates failure, and stays scoped to the annotated target.

Teach ninja_gen.rs to emit Ninja's built-in phony rule for the reserved gate action id, so the gate chain renders as valid Ninja with || ordering links.

Add IR, snapshot, and BDD regression coverage plus documentation for the syntax, semantics, and lowering strategy.

Design Choices

Design Choice 1: How to enforce serial ordering in Ninja, which has no native "serial dependency" primitive

Options Considered:

1. Assign the annotated dependencies to a Ninja pool with depth = 1. Web search confirms a depth-1 pool limits concurrency to one job but gives no FIFO or declaration-order guarantee, and it acts as a shared worker limit rather than a scoped ordering. This fails the ordering and scoping requirements.
2. Add order-only edges directly between the real dependency edges (d2 || d1, d3 || d2). This modifies the shared edges globally, so any unrelated target that depends on d2 also inherits the ordering. This breaks the "do not serialise unrelated branches" requirement.
3. Synthesize a per-target chain of phony "gate" edges. Each gate aliases one dependency and depends order-only on the previous gate. The annotated target depends on the gates instead of the raw dependencies.

Chosen Option: 3

Rationale: The runner shells out to ninja and cannot schedule steps itself. Ordering must be encoded in the graph. Gate synthesis is the only approach that enforces declaration order, propagates failure through the order-only chain, keeps shared dependencies as single deduplicated edges, and scopes the ordering to the annotated target without touching shared edges.

Design Choice 2: Which dependency list the field serializes

Options Considered:

1. Serialize deps (implicit dependencies) only. Aggregate actions, such as the Catnap all example, express their ordered gates as deps.
2. Serialize sources and deps. This mixes recipe inputs with ordering intent and complicates lowering.

Chosen Option: 1

Rationale: The field could apply to sources, deps, or both. deps is the natural "direct dependencies" list for aggregate actions, and sources remain recipe inputs.

Design Choice 3: Whether to store the ordering intent on `BuildEdge`

Options Considered:

1. Add a dependency_order field to BuildEdge and have ninja_gen.rs interpret it. This pushes graph semantics into the pure rendering adapter.
2. Encode ordering entirely as synthesized gate edges during lowering. BuildEdge stays semantics-free and ninja_gen.rs stays a renderer.

Chosen Option: 2

Rationale: The IR could carry a dependency_order field, or encode ordering purely through synthesized gates. Gate synthesis keeps the hexagonal boundary intact and needs no ordering field on BuildEdge.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Manifest schema for dependency_order

Add the surface syntax for serial ordering, and reject invalid values at parse time. This phase makes the field available to authors and pins its default to the current parallel behaviour.

Task 1: Add the `DependencyOrder` enum and field to the AST

Define the ordering enum and attach it to targets and actions.

• Add a DependencyOrder enum to src/ast.rs with variants Parallel and Serial. Derive Default on Parallel. Apply #[serde(rename_all = "lowercase")] so the manifest reads parallel/serial.
• Add a dependency_order: DependencyOrder field to Target with #[serde(default)]. Target covers both targets: and the actions: shorthand, so actions inherit the field.
• Add a /// doc comment on the enum and the field. State that the field orders the deps list only, and that omission keeps parallel behaviour.
• Do not add the field to Rule. Reusable rules already reject deps.
• Do not touch src/manifest/expand.rs or src/manifest/render.rs. The field is a closed enum, not a control key and not a template.

Task 2: Add AST parsing tests

Prove the field parses, defaults, and rejects bad input.

• Add cases to tests/ast_tests/ (mirror parsing.rs/manifest_files.rs) that parse dependency_order: serial and dependency_order: parallel on a target and on an action.
• Add a case that asserts the default is Parallel when the field is omitted.
• Add a case that asserts an unknown value (for example dependency_order: sequential) fails deserialization. #[serde(deny_unknown_fields)] already guards unknown keys; the enum guards unknown values.

🤖 Prompt for AI agents

Implement the manifest schema surface for `dependency_order`. The goal is to let
authors declare `dependency_order: serial` on targets and actions, defaulting to
the current parallel behaviour when omitted.

- In `src/ast.rs`, add a `DependencyOrder` enum with variants `Parallel` and
`Serial`. Derive `Default` on `Parallel`. Apply `#[serde(rename_all =
"lowercase")]` so the manifest accepts `parallel`/`serial` as literal strings.
- Add a `dependency_order: DependencyOrder` field to `Target`, marked
`#[serde(default)]`. Because `Target` covers both `targets:` entries and the
`actions:` shorthand, actions inherit the field automatically.
- Add `///` doc comments on both the enum and the field. State clearly that the
field orders the `deps` list only, and that omitting the field keeps parallel
behaviour.
- Do not add `dependency_order` to `Rule`. Reusable rules already reject `deps`.
- Do not modify `src/manifest/expand.rs` or `src/manifest/render.rs`. The field
is a closed enum value, not a flow-control key and not a template expression.
- Add parsing tests under `tests/ast_tests/` (follow the existing style in
`parsing.rs`/`manifest_files.rs`):
- Parse `dependency_order: serial` and `dependency_order: parallel` on both a
target and an action.
  - Assert the default value is `Parallel` when the field is omitted.
- Assert an unknown value (for example `dependency_order: sequential`) fails
deserialization.

Phase 2: Gate synthesis in IR lowering

Translate a serial deps list into a deterministic chain of phony gate edges during lowering. This phase produces the graph shape that Ninja can execute in order, scoped to the annotated target.

Task 1: Add a serial-gate lowering pass

Create the gate chain for each serial target.

• Add a helper module under src/ir/ (for example src/ir/serial.rs) that, given a target's lowered deps paths and its explicit outputs, produces the gate edges and the replacement dependency list.
• For a target T with serial deps [d1..dn]:
  • Create one phony gate BuildEdge per dependency. Gate Gi sets implicit_deps = [di]. For i > 1, gate Gi sets order_only_deps = [G(i-1)]. Set phony = true on gates.
  • Replace T.implicit_deps with the gate outputs [G1..Gn], so freshness of each di propagates through its phony gate to T, and the order-only chain forces sequential execution.
  • When deps has fewer than two entries, skip gate synthesis and lower as parallel. A single dependency needs no ordering.
• Mint gate output paths under a reserved namespace that user manifests cannot produce (for example .netsuke/serial/<hash>/<index>). Derive <hash> with the existing SHA-256 plus lower-hex idiom (see src/hasher.rs, src/manifest/expand.rs::entry_name_hash) over the target's sorted explicit outputs, so output is deterministic across runs.
• Give every gate edge a reserved sentinel action_id of "phony". Do not register a phony Action in graph.actions; Phase 3 handles emission.

Task 2: Wire the pass into `from_manifest`

Invoke gate synthesis at the correct point in lowering.

• Update src/ir/from_manifest.rs::process_targets to call the serial-gate pass when a target's dependency_order is Serial.
• Before inserting gate edges, reuse the existing duplicate_output_error/find_duplicates check (see src/ir/from_manifest_support.rs) against the reserved gate outputs, mirroring the per-target guard, so a collision fails loudly rather than overwriting an edge.
• Run gate synthesis before graph.detect_cycles() (already invoked after process_targets) so cycle detection sees the gate chain.
• Confirm src/ir/cycle.rs needs no change. The detector already traverses inputs and implicit_deps and excludes order_only_deps, so it visits T -> Gi -> di and ignores the ordering-only gate links.
• Confirm src/hasher.rs needs no change. Gates carry no registered Action, and BuildEdge is not hashed.

Task 3: Add IR lowering tests

Cover ordering, sharing, failure structure, and the parallel default at the IR level.

• Add cases to tests/ir_from_manifest_tests.rs that lower a serial target and assert the gate chain: gate count equals dependency count, each gate aliases one dependency in declaration order, and each gate after the first depends order-only on the previous gate.
• Add a case where two serial targets share a dependency and assert the shared dependency remains a single edge (built once).
• Add a case asserting a parallel target (field omitted) lowers to implicit_deps unchanged, with no gate edges.
• Add a case asserting gate output paths are deterministic across repeated lowering of the same manifest.
• Add or extend BDD scenarios in tests/features/ir.feature/ir_generation.feature and a step in tests/bdd/steps/ir.rs that asserts a target's dependencies are ordered serially.

🤖 Prompt for AI agents

Implement the serial-gate lowering pass that converts a serial `deps` list into
a deterministic chain of phony gate edges during IR lowering. The goal is a
graph shape that enforces declaration order, deduplicates shared dependencies,
and stays scoped to the annotated target.

- Add a helper module under `src/ir/` (for example `src/ir/serial.rs`). Given a
target's lowered `deps` paths and its explicit outputs, it must produce the gate
edges and the replacement dependency list.
- For a target `T` with serial `deps` `[d1..dn]`:
- Create one phony gate `BuildEdge` per dependency. Gate `Gi` sets
`implicit_deps = [di]`. For `i > 1`, gate `Gi` sets `order_only_deps =
[G(i-1)]`. Set `phony = true` on gates.
- Replace `T.implicit_deps` with the gate outputs `[G1..Gn]`. This propagates
freshness of each `di` through its phony gate to `T`, and the order-only chain
forces sequential execution.
- Skip gate synthesis when `deps` has fewer than two entries; lower as parallel
instead. A single dependency needs no ordering.
- Mint gate output paths under a reserved namespace that user manifests cannot
produce (for example `.netsuke/serial/<hash>/<index>`). Derive `<hash>` using
the existing SHA-256 plus lower-hex idiom (see `src/hasher.rs`,
`src/manifest/expand.rs::entry_name_hash`) over the target's sorted explicit
outputs, so output stays deterministic across runs.
- Give every gate edge a reserved sentinel `action_id` of `"phony"`. Do not
register a phony `Action` in `graph.actions`; Phase 3 handles emission.

Wire the pass into lowering:
- Update `src/ir/from_manifest.rs::process_targets` to call the serial-gate pass
when a target's `dependency_order` is `Serial`.
- Before inserting gate edges, reuse the existing
`duplicate_output_error`/`find_duplicates` check (see
`src/ir/from_manifest_support.rs`) against the reserved gate outputs, mirroring
the per-target guard, so a collision fails loudly rather than overwriting an
edge.
- Run gate synthesis before `graph.detect_cycles()` (already invoked after
`process_targets`), so cycle detection sees the gate chain.
- Leave `src/ir/cycle.rs` unchanged. The detector already traverses `inputs` and
`implicit_deps` and excludes `order_only_deps`, so it visits `T -> Gi -> di` and
ignores the ordering-only gate links.
- Leave `src/hasher.rs` unchanged. Gates carry no registered `Action`, and
`BuildEdge` is not hashed.

Add test coverage:
- In `tests/ir_from_manifest_tests.rs`, add cases that lower a serial target and
assert the gate chain: gate count equals dependency count, each gate aliases one
dependency in declaration order, and each gate after the first depends
order-only on the previous gate.
- Add a case where two serial targets share a dependency, and assert the shared
dependency remains a single edge (built once).
- Add a case asserting a parallel target (field omitted) lowers to
`implicit_deps` unchanged, with no gate edges.
- Add a case asserting gate output paths are deterministic across repeated
lowering of the same manifest.
- Add or extend BDD scenarios in
`tests/features/ir.feature`/`ir_generation.feature`, and a step in
`tests/bdd/steps/ir.rs`, that assert a target's dependencies are ordered
serially.

Phase 3: Ninja emission of phony gates

Render gate edges as Ninja's built-in phony rule so the generated graph executes in order. This phase makes the synthesized gates real in build.ninja.

Task 1: Emit the built-in `phony` rule for gate edges

Special-case the reserved "phony" action id in the generator.

• Update src/ninja_gen.rs so the action-emission loop never writes a rule phony block. Ninja's phony is a built-in pseudo-rule and must not be declared.
• Update DisplayEdge (or its caller) so that when edge.action_id == "phony", it bypasses the graph.actions.get(...).ok_or(MissingAction) lookup and emits build <outputs>: phony <implicit_deps> || <order_only_deps>.
• Keep the existing dependency-punctuation order (| for implicit deps, || for order-only deps). Gate edges have no explicit inputs.
• Keep the current top-level determinism sort of edges and actions. The per-edge dependency order stays a verbatim pass-through, which preserves the gate chain order.

Task 2: Add Ninja emission regression coverage

Assert exact ordering in generated Ninja and validate against real ninja.

• Add a fixture tests/data/dependency_order_serial.yml that mirrors tests/data/implicit_deps.yml and declares a serial target with several ordered dependencies.
• Add a dependency_order_serial_manifest_ninja_snapshot test to tests/ninja_snapshot_tests.rs, following the three-step pattern (build IR, ninja_gen::generate, substring assertions plus assert_snapshot!). Assert the emitted build ... : phony ... gate lines and the || chain appear in declaration order. Commit the .snap file under tests/snapshots/ninja/.
• Use the existing round-trip step in tests/ninja_snapshot_tests.rs (invoke the real ninja with -t rules/-t targets/no-op) to confirm the generated file is valid and the gate freshness propagates through the phony aliases.
• Add or update BuildEdge literal construction sites in tests/ninja_gen_unit_tests.rs, tests/ninja_gen_integration_tests.rs, and src/ninja_gen_property_tests.rs if the phony special-case needs a dedicated unit case.

🤖 Prompt for AI agents

Implement rendering of synthesized phony gate edges as Ninja's built-in `phony`
rule, so the gate chain becomes valid, executable `build.ninja` content.

- In `src/ninja_gen.rs`, ensure the action-emission loop never writes a `rule
phony` block. Ninja's `phony` is a built-in pseudo-rule and must not be
declared.
- Update `DisplayEdge` (or its caller) so that, when `edge.action_id ==
"phony"`, it bypasses the `graph.actions.get(...).ok_or(MissingAction)` lookup
and emits `build <outputs>: phony <implicit_deps> || <order_only_deps>`.
- Keep the existing dependency-punctuation order: `|` for implicit deps, `||`
for order-only deps. Gate edges have no explicit inputs.
- Keep the current top-level determinism sort of edges and actions. The per-edge
dependency order stays a verbatim pass-through, which preserves the gate chain
order.

Add regression coverage:
- Add a fixture `tests/data/dependency_order_serial.yml` that mirrors
`tests/data/implicit_deps.yml` and declares a serial target with several ordered
dependencies.
- Add a `dependency_order_serial_manifest_ninja_snapshot` test to
`tests/ninja_snapshot_tests.rs`, following the existing three-step pattern
(build IR, `ninja_gen::generate`, substring assertions plus `assert_snapshot!`).
Assert the emitted `build ... : phony ...` gate lines and the `||` chain appear
in declaration order. Commit the `.snap` file under `tests/snapshots/ninja/`.
- Use the existing round-trip step in `tests/ninja_snapshot_tests.rs` (invoke
the real `ninja` with `-t rules`/`-t targets`/no-op) to confirm the generated
file is valid, and that gate freshness propagates through the phony aliases.
- Add or update `BuildEdge` literal construction sites in
`tests/ninja_gen_unit_tests.rs`, `tests/ninja_gen_integration_tests.rs`, and
`src/ninja_gen_property_tests.rs`, if the phony special-case needs a dedicated
unit case.

Phase 4: Documentation

Document the field, its execution semantics, and the lowering strategy. This phase satisfies the acceptance criterion to document syntax and semantics.

Task 1: Update the user guide

Describe author-facing syntax and behaviour.

• Update docs/users-guide.md (dependency-field section, around lines 300–330) with a dependency_order paragraph and an example. State the four guarantees: declaration order, shared dependency built once, stop before later dependencies on failure, and parallel default when omitted. State that the field scopes ordering to the annotated deps list only.

Task 2: Update the design document

Keep the architecture, diagrams, and lowering narrative in sync.

• Update docs/netsuke-design.md §2.4 (dependency-field table) and its summary bullets to add dependency_order.
• Update §3.2 (ast.rs) to add the dependency_order field and the DependencyOrder enum to the Target sample.
• Update §5.3 (AST to IR) with a paragraph describing serial-gate synthesis, and §5.4 (Ninja synthesis) with a note on how gates render as phony edges with || chaining. Do not add a dependency_order field to the §5.2 BuildEdge sample or Mermaid diagram; state that ordering is encoded as synthesized gate edges.
• Update §5.5 (Design decisions) with a bullet recording the gate-chain rationale and the reserved gate namespace.

Task 3: Update supporting docs

Record the internal boundary and the cycle-participation contract.

• Update docs/developers-guide.md with a subsection describing the serial-gate lowering pass and the reserved gate namespace.
• Update docs/formal-verification-methods-in-netsuke.md (cycle-participation contract) to state that gate implicit dependencies participate in cycle detection and the gate order-only links do not.
• Add a roadmap item to docs/roadmap.md §3.14 for dependency_order: serial, marked done only after all gates pass.

🤖 Prompt for AI agents

Document the `dependency_order` field, its execution semantics, and the lowering
strategy across the user guide, design document, and supporting docs. The goal
is to satisfy the acceptance criterion to document syntax and semantics.

- Update `docs/users-guide.md` (dependency-field section, around lines 300–330)
with a `dependency_order` paragraph and an example. State the four guarantees:
declaration order, shared dependency built once, stop before later dependencies
on failure, and parallel default when the field is omitted. State that the field
scopes ordering to the annotated `deps` list only.
- Update `docs/netsuke-design.md`:
- §2.4 (dependency-field table) and its summary bullets: add `dependency_order`.
- §3.2 (`ast.rs`): add the `dependency_order` field and the `DependencyOrder`
enum to the `Target` sample.
  - §5.3 (AST to IR): add a paragraph describing serial-gate synthesis.
- §5.4 (Ninja synthesis): add a note on how gates render as `phony` edges with
`||` chaining.
- Do not add a `dependency_order` field to the §5.2 `BuildEdge` sample or
Mermaid diagram. State instead that ordering is encoded as synthesized gate
edges.
- §5.5 (Design decisions): add a bullet recording the gate-chain rationale and
the reserved gate namespace.
- Update `docs/developers-guide.md` with a subsection describing the serial-gate
lowering pass and the reserved gate namespace.
- Update `docs/formal-verification-methods-in-netsuke.md` (cycle-participation
contract) to state that gate implicit dependencies participate in cycle
detection, and gate order-only links do not.
- Add a roadmap item to `docs/roadmap.md` §3.14 for `dependency_order: serial`.
Mark it done only after all gates pass.

Research

Netsuke loads a YAML manifest, expands flow control (src/manifest/expand.rs), deserialises a typed AST (src/ast.rs), lowers the AST into a build graph IR (src/ir/), renders the IR into a build.ninja file (src/ninja_gen.rs), and delegates execution to the real ninja binary (src/runner/). The IR is a map-based graph: BuildGraph holds content-hashed Actions and one BuildEdge per output path. Each BuildEdge carries inputs, implicit_deps, and order_only_deps as plain path vectors, in manifest declaration order. Ninja owns all scheduling and failure handling; Netsuke only passes -j and streams output. Therefore, all ordering and failure semantics must live in the generated Ninja graph.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the manifest schema surface for `dependency_order`. The goal is to let
authors declare `dependency_order: serial` on targets and actions, defaulting to
the current parallel behaviour when omitted.

- In `src/ast.rs`, add a `DependencyOrder` enum with variants `Parallel` and
`Serial`. Derive `Default` on `Parallel`. Apply `#[serde(rename_all =
"lowercase")]` so the manifest accepts `parallel`/`serial` as literal strings.
- Add a `dependency_order: DependencyOrder` field to `Target`, marked
`#[serde(default)]`. Because `Target` covers both `targets:` entries and the
`actions:` shorthand, actions inherit the field automatically.
- Add `///` doc comments on both the enum and the field. State clearly that the
field orders the `deps` list only, and that omitting the field keeps parallel
behaviour.
- Do not add `dependency_order` to `Rule`. Reusable rules already reject `deps`.
- Do not modify `src/manifest/expand.rs` or `src/manifest/render.rs`. The field
is a closed enum value, not a flow-control key and not a template expression.
- Add parsing tests under `tests/ast_tests/` (follow the existing style in
`parsing.rs`/`manifest_files.rs`):
- Parse `dependency_order: serial` and `dependency_order: parallel` on both a
target and an action.
  - Assert the default value is `Parallel` when the field is omitted.
- Assert an unknown value (for example `dependency_order: sequential`) fails
deserialization.
===============================================================================

Task: 2

Implement the serial-gate lowering pass that converts a serial `deps` list into
a deterministic chain of phony gate edges during IR lowering. The goal is a
graph shape that enforces declaration order, deduplicates shared dependencies,
and stays scoped to the annotated target.

- Add a helper module under `src/ir/` (for example `src/ir/serial.rs`). Given a
target's lowered `deps` paths and its explicit outputs, it must produce the gate
edges and the replacement dependency list.
- For a target `T` with serial `deps` `[d1..dn]`:
- Create one phony gate `BuildEdge` per dependency. Gate `Gi` sets
`implicit_deps = [di]`. For `i > 1`, gate `Gi` sets `order_only_deps =
[G(i-1)]`. Set `phony = true` on gates.
- Replace `T.implicit_deps` with the gate outputs `[G1..Gn]`. This propagates
freshness of each `di` through its phony gate to `T`, and the order-only chain
forces sequential execution.
- Skip gate synthesis when `deps` has fewer than two entries; lower as parallel
instead. A single dependency needs no ordering.
- Mint gate output paths under a reserved namespace that user manifests cannot
produce (for example `.netsuke/serial/<hash>/<index>`). Derive `<hash>` using
the existing SHA-256 plus lower-hex idiom (see `src/hasher.rs`,
`src/manifest/expand.rs::entry_name_hash`) over the target's sorted explicit
outputs, so output stays deterministic across runs.
- Give every gate edge a reserved sentinel `action_id` of `"phony"`. Do not
register a phony `Action` in `graph.actions`; Phase 3 handles emission.

Wire the pass into lowering:
- Update `src/ir/from_manifest.rs::process_targets` to call the serial-gate pass
when a target's `dependency_order` is `Serial`.
- Before inserting gate edges, reuse the existing
`duplicate_output_error`/`find_duplicates` check (see
`src/ir/from_manifest_support.rs`) against the reserved gate outputs, mirroring
the per-target guard, so a collision fails loudly rather than overwriting an
edge.
- Run gate synthesis before `graph.detect_cycles()` (already invoked after
`process_targets`), so cycle detection sees the gate chain.
- Leave `src/ir/cycle.rs` unchanged. The detector already traverses `inputs` and
`implicit_deps` and excludes `order_only_deps`, so it visits `T -> Gi -> di` and
ignores the ordering-only gate links.
- Leave `src/hasher.rs` unchanged. Gates carry no registered `Action`, and
`BuildEdge` is not hashed.

Add test coverage:
- In `tests/ir_from_manifest_tests.rs`, add cases that lower a serial target and
assert the gate chain: gate count equals dependency count, each gate aliases one
dependency in declaration order, and each gate after the first depends
order-only on the previous gate.
- Add a case where two serial targets share a dependency, and assert the shared
dependency remains a single edge (built once).
- Add a case asserting a parallel target (field omitted) lowers to
`implicit_deps` unchanged, with no gate edges.
- Add a case asserting gate output paths are deterministic across repeated
lowering of the same manifest.
- Add or extend BDD scenarios in
`tests/features/ir.feature`/`ir_generation.feature`, and a step in
`tests/bdd/steps/ir.rs`, that assert a target's dependencies are ordered
serially.
===============================================================================

Task: 3

Implement rendering of synthesized phony gate edges as Ninja's built-in `phony`
rule, so the gate chain becomes valid, executable `build.ninja` content.

- In `src/ninja_gen.rs`, ensure the action-emission loop never writes a `rule
phony` block. Ninja's `phony` is a built-in pseudo-rule and must not be
declared.
- Update `DisplayEdge` (or its caller) so that, when `edge.action_id ==
"phony"`, it bypasses the `graph.actions.get(...).ok_or(MissingAction)` lookup
and emits `build <outputs>: phony <implicit_deps> || <order_only_deps>`.
- Keep the existing dependency-punctuation order: `|` for implicit deps, `||`
for order-only deps. Gate edges have no explicit inputs.
- Keep the current top-level determinism sort of edges and actions. The per-edge
dependency order stays a verbatim pass-through, which preserves the gate chain
order.

Add regression coverage:
- Add a fixture `tests/data/dependency_order_serial.yml` that mirrors
`tests/data/implicit_deps.yml` and declares a serial target with several ordered
dependencies.
- Add a `dependency_order_serial_manifest_ninja_snapshot` test to
`tests/ninja_snapshot_tests.rs`, following the existing three-step pattern
(build IR, `ninja_gen::generate`, substring assertions plus `assert_snapshot!`).
Assert the emitted `build ... : phony ...` gate lines and the `||` chain appear
in declaration order. Commit the `.snap` file under `tests/snapshots/ninja/`.
- Use the existing round-trip step in `tests/ninja_snapshot_tests.rs` (invoke
the real `ninja` with `-t rules`/`-t targets`/no-op) to confirm the generated
file is valid, and that gate freshness propagates through the phony aliases.
- Add or update `BuildEdge` literal construction sites in
`tests/ninja_gen_unit_tests.rs`, `tests/ninja_gen_integration_tests.rs`, and
`src/ninja_gen_property_tests.rs`, if the phony special-case needs a dedicated
unit case.
===============================================================================

Task: 4

Document the `dependency_order` field, its execution semantics, and the lowering
strategy across the user guide, design document, and supporting docs. The goal
is to satisfy the acceptance criterion to document syntax and semantics.

- Update `docs/users-guide.md` (dependency-field section, around lines 300–330)
with a `dependency_order` paragraph and an example. State the four guarantees:
declaration order, shared dependency built once, stop before later dependencies
on failure, and parallel default when the field is omitted. State that the field
scopes ordering to the annotated `deps` list only.
- Update `docs/netsuke-design.md`:
- §2.4 (dependency-field table) and its summary bullets: add `dependency_order`.
- §3.2 (`ast.rs`): add the `dependency_order` field and the `DependencyOrder`
enum to the `Target` sample.
  - §5.3 (AST to IR): add a paragraph describing serial-gate synthesis.
- §5.4 (Ninja synthesis): add a note on how gates render as `phony` edges with
`||` chaining.
- Do not add a `dependency_order` field to the §5.2 `BuildEdge` sample or
Mermaid diagram. State instead that ordering is encoded as synthesized gate
edges.
- §5.5 (Design decisions): add a bullet recording the gate-chain rationale and
the reserved gate namespace.
- Update `docs/developers-guide.md` with a subsection describing the serial-gate
lowering pass and the reserved gate namespace.
- Update `docs/formal-verification-methods-in-netsuke.md` (cycle-participation
contract) to state that gate implicit dependencies participate in cycle
detection, and gate order-only links do not.
- Add a roadmap item to `docs/roadmap.md` §3.14 for `dependency_order: serial`.
Mark it done only after all gates pass.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!