RFCs: structured execution contexts and manifest composition

docs/contents.md

@@ -37,6 +37,22 @@ operator, user, and contributor references are easier to find.
 - [rfcs/0001-structured-command-blocks.md](rfcs/0001-structured-command-blocks.md):
   Proposed structured command blocks, shell-free argv templates, typed Jinja
   interpolation, stream routing, and pipeline semantics.
+- [rfcs/0009-structured-command-working-directories.md][rfc-0009]:
+  Normative amendment adding capability-scoped per-command working directories
+  to RFC 0001.
+- [rfcs/0010-runtime-bindings-and-secure-tempdirs.md][rfc-0010]:
+  Normative amendment adding bounded stdout environment capture, standard-error
+  pipelines, environment-selected working directories, and secure temporary
+  execution directories to RFC 0001.
+- [rfcs/0002-repository-relative-includes.md][rfc-0002]:
+  Deterministic repository-relative manifest includes with cycle detection,
+  provenance, namespaces, and duplicate rejection.
+- [rfcs/0003-versioned-local-bundles.md](rfcs/0003-versioned-local-bundles.md):
+  Versioned local bundles with typed parameters, explicit exports, SemVer
+  selection, canonical digests, and lock records.
+- [rfcs/0004-digest-pinned-external-bundles.md][rfc-0004]:
+  Later digest-pinned external Git bundles with exact tag resolution, immutable
+  object provenance, bounded acquisition, caching, and offline verification.
 - [RFC 0005: Harden release integrity and
   admission](rfcs/0005-release-hardening.md): Proposed release-profile
   invariants, secret and dependency policy, and exact-commit release admission.
@@ -52,6 +68,11 @@ operator, user, and contributor references are easier to find.
   self-consistency, health-signal ownership, and scheduled coverage-guided
   fuzzing.
 
+[rfc-0009]: rfcs/0009-structured-command-working-directories.md
+[rfc-0010]: rfcs/0010-runtime-bindings-and-secure-tempdirs.md
+[rfc-0002]: rfcs/0002-repository-relative-includes.md
+[rfc-0004]: rfcs/0004-digest-pinned-external-bundles.md
+
 ## Decision records
 
 - [adr-001-replace-serde-yml-with-serde-saphyr.md](adr-001-replace-serde-yml-with-serde-saphyr.md):

docs/netsuke-design.md

@@ -702,6 +702,72 @@ explicit, structured, and self-documenting nature.
 | Target Build    | my_program: main.o utils.o\\t$(CC) $^ -o $@                                        | { targets: { name: my_program, rule: link, sources: [main.o, utils.o] }                                           |
 | Readability     | Relies on cryptic automatic variables ($@, $\<, $^) and implicit pattern matching. | Uses explicit, descriptive keys (name, rule, sources) and standard YAML list/map syntax.                          |
 
+### 2.8 Manifest composition and bundle resolution
+
+RFC 0003 defines deterministic resolution for versioned local bundles. The
+following sequence shows how a manifest resolves, validates, and locks a
+namespaced bundle.
+
+For screen readers: The manifest asks the resolver to resolve a bundle source
+and version. The resolver enumerates sorted catalogue candidates, selects the
+highest compatible SemVer, validates parameters and exports, obtains the
+canonical content digest, verifies the lock, and returns namespaced exported
+declarations.
+
+```mermaid
+sequenceDiagram
+    participant Manifest
+    participant Resolver
+    participant Catalogue
+    participant Bundle
+    participant Lock
+
+    Manifest->>Resolver: resolve bundle source and version
+    Resolver->>Catalogue: enumerate candidates in sorted order
+    Catalogue-->>Resolver: bundle descriptors
+    Resolver->>Resolver: select highest compatible SemVer
+    Resolver->>Bundle: validate parameters and exports
+    Bundle-->>Resolver: canonical content digest
+    Resolver->>Lock: verify selected version and digests
+    Lock-->>Resolver: lock status
+    Resolver-->>Manifest: namespaced exported declarations
+```
+
+Figure: Local bundle resolution and lock verification.
+
+RFC 0004 extends this composition flow to external Git bundles. It preserves
+the same verification boundary while adding exact reference resolution,
+provenance, and content-addressed caching.
+
+For screen readers: The manifest asks the Git resolver for an exact tag or
+commit. The resolver fetches normalized Git references or a full commit, then
+the verifier checks the subdirectory, metadata, SemVer, and canonical digest.
+The verifier reads or publishes the verified content-addressed bundle, compares
+tag, peeled-commit, and digest values with the lock, and returns a verified
+bundle instance to the manifest.
+
+```mermaid
+sequenceDiagram
+    participant Manifest
+    participant GitResolver
+    participant GitRemote
+    participant Cache
+    participant Verifier
+    participant Lock
+
+    Manifest->>GitResolver: resolve exact tag or commit
+    GitResolver->>GitRemote: fetch normalized refs/tags/... or full commit
+    GitRemote-->>GitResolver: Git objects and tag provenance
+    GitResolver->>Verifier: verify subdir, metadata, SemVer, and canonical digest
+    Verifier->>Cache: read or publish content-addressed bundle
+    Cache-->>Verifier: verified content
+    Verifier->>Lock: compare tag, peeled commit, and digest
+    Lock-->>Verifier: lock verification result
+    Verifier-->>Manifest: verified bundle instance
+```
+
+Figure: External Git bundle verification and cache-backed lock resolution.
+
 ## Section 3: Parsing and Deserialization Strategy
 
 Once the Jinja evaluation stage has produced a pure YAML string, the next
@@ -2353,6 +2419,35 @@ remains responsible for invoking Ninja correctly and, most importantly, for
 ensuring that the commands it generates for Ninja to run are constructed
 securely.
 
+### Structured command working directories
+
+RFC 0009 gives structured commands an explicit, capability-checked working
+directory. The sequence below shows that resolution and validation happen
+before the child process receives its `current_dir`.
+
+For screen readers: The compiler provides a process specification with a
+working directory to the action runner. The runner asks the workspace
+capability to resolve and validate that directory, receives a
+capability-relative directory, spawns the child process with that directory as
+its current directory, and receives the process result.
+
+```mermaid
+sequenceDiagram
+    participant Compiler
+    participant ActionRunner
+    participant WorkspaceCapability
+    participant ChildProcess
+
+    Compiler->>ActionRunner: provide ProcessSpec with cwd
+    ActionRunner->>WorkspaceCapability: resolve and validate cwd
+    WorkspaceCapability-->>ActionRunner: capability-relative directory
+    ActionRunner->>ChildProcess: spawn with current_dir(cwd)
+    ChildProcess-->>ActionRunner: process result
+```
+
+Figure: Capability-checked working-directory resolution for a structured
+command.
+
 ### 6.1 Invoking Ninja
 
 Netsuke uses Rust's standard library `std::process::Command` API to configure