v0.2.0: land structured recipes, Git-aware change detection, and OrthoConfig v0.10 integration

[leynos]

Goal

Track the feature spine for Netsuke v0.2.0 after the v0.1.0 final hardening release.

v0.2.0 should be the release where Netsuke moves beyond the original shell-string recipe surface, gains deterministic local manifest composition, and starts exposing more of the agent-native and localization infrastructure expected from OrthoConfig v0.10.0.

Release scope

Structured rules and commands

Use PR #573 as the design basis for the new structured rule/command syntax, including argv-safe invocation, explicit shell mode, environment overlays, stream routing, pipelines, and backend execution planning.

Treat both RFC 0001 amendments in PR #600 as part of the structured-command design:

• cwd and working-directory semantics;
• runtime bindings and secure execution contexts.

Structured processes must support:

• capability-scoped literal cwd in direct and shell modes;
• independent working directories for adjacent commands and pipeline stages;
• bounded UTF-8 standard-output capture into an action-local named environment binding;
• pipe: stderr, connecting one stage's standard error to the next stage's standard input without merging output streams;
• cwd: { env: NAME }, distinguishing ordinary text paths from runner-owned directory capabilities; and
• runner-created private temporary working directories, optionally bound to an environment name for later commands and removed on every completion path.

Runtime bindings must never mutate Netsuke's parent process environment or enter manifest-time Jinja. Captured text must not grant external filesystem authority merely by containing an absolute path. Secure tempdirs must carry typed directory authority, owner-only access, bounded lifecycle ownership, and mandatory cleanup.

The implementation must preserve backwards compatibility for existing shell-string recipes while providing a shell-free path for commands that do not require shell semantics.

Manifest composition and bundle provenance

Use the staged RFC suite in PR #600:

1. RFC 0002: Repository-relative manifest includes
   • literal repository-relative paths;
   • deterministic depth-first composition;
   • cycle and duplicate-load detection;
   • namespaces, retained source provenance, and duplicate declaration rejection.
2. RFC 0003: Versioned local manifest bundles
   • explicit bundle identity and Semantic Versioning;
   • typed parameters and private-by-default exports;
   • deterministic local catalogue selection;
   • canonical content digests and lock records.
3. RFC 0004: Digest-pinned external bundles and Git provenance
   • only after local includes and bundles are stable;
   • exact tagged Git resolution, including annotated and lightweight tags;
   • recorded tag-object and peeled-commit identities;
   • mandatory canonical content digests, bounded acquisition, verified caches,
     lock comparison, and offline operation.

The implementation sequence is normative: local includes first, versioned local bundles second, and networked external acquisition only later. A Git tag is a discovery handle rather than a trust anchor; reviewed digest and lock provenance bind the selected bytes.

v0.2.0 should at minimum accept the complete RFC sequence and implement the local composition foundation needed by downstream Netsukefile migrations. External Git acquisition may be staged later if its bounded transport, cache, and verification work would otherwise delay the local feature spine.

Git-aware change detection

Use PR #584 as the design basis for deterministic Git-aware manifest planning and change-selection helpers.

The feature should keep Git access bounded and explicit, preserve path fidelity, avoid shell pipelines, and compose with manifest conditions rather than inventing a second conditional language.

Git-aware change detection and external bundle acquisition share provenance concepts but remain separate capabilities. Change detection must not implicitly fetch or resolve bundle repositories.

OrthoConfig v0.10.0 integration

Adopt the relevant OrthoConfig v0.10.0 agent-native and localization capabilities as they become available, without duplicating generic CLI/configuration machinery in Netsuke.

Candidate integration areas include:

• richer command metadata and context/schema output;
• stable structured result and error metadata;
• vocabulary and global-option consistency;
• non-interactive/mutation metadata;
• localization/help-generation improvements; and
• capability provenance useful to agents.

The exact subset is gated by what OrthoConfig v0.10.0 actually ships. Netsuke should consume upstream capabilities through narrow integration boundaries rather than blocking v0.2.0 on unrelated OrthoConfig work.

Acceptance criteria

• The structured recipe implementation is usable end to end and documented, with explicit shell escape hatches rather than implicit shell dependence.
• Structured commands support the literal and environment-selected cwd contracts from PR RFCs: structured execution contexts and manifest composition #600 in direct, shell, sequence, and pipeline execution.
• Standard-output environment capture is bounded before strict UTF-8 conversion, redacted by default, action-local, and committed only after successful execution.
• pipe: stderr preserves raw bytes, keeps standard output independent, validates stream conflicts, and follows the pipeline cleanup and exit policy.
• Secure temporary directories are owner-private before child access, may be shared through typed sequence-local directory bindings, and are cleaned after success, failure, cancellation, timeout, and spawn error.
• Text bindings cannot manufacture external-directory capability, and no runtime binding mutates the parent process environment.
• Existing v0.1.x manifests remain supported or have an explicit migration path.
• Repository-relative includes have deterministic composition, provenance, cycle detection, capability confinement, and duplicate semantics.
• Versioned local bundles have typed parameters, explicit exports, deterministic SemVer selection, canonical digests, and lock verification.
• The external bundle RFC is accepted with exact tagged Git resolution and digest-pinned provenance; implementation follows only after the local layers are stable.
• Git-aware change detection is available through documented manifest/CLI surfaces with deterministic and bounded behaviour.
• Relevant OrthoConfig v0.10.0 agent-native/localization functionality is adopted and covered by integration tests.
• Human and --json behaviour remain coherent across the new surfaces.
• Security boundaries introduced during v0.1.0 hardening are not weakened by the new execution or composition models.
• At least two downstream migration canaries consume the local composition and structured execution surfaces without copying one monolithic Netsukefile.
• Full repository quality gates pass.

Related work

• PR RFC: structured command blocks and argv templates #573: RFC 0001 structured command blocks and argv templates.
• PR RFCs: structured execution contexts and manifest composition #600: RFC 0001 execution-context amendments plus RFCs 0002–0004 for includes and bundles.
• PR Define Git change-detection helpers #584: Git change-detection helper design.
• Unify parser and configuration metadata for generated help #559: parser/configuration metadata composition for generated help.
• Gate v0.1.0 with three representative downstream Netsukefile migration canaries #598: downstream Netsukefile migration canaries.
• v0.1.1: remove dependency-only action no-op recipes #597: narrow v0.1.1 dependency-only action gate.
• v0.3.0 test/dependency work is intentionally out of scope for this release.