RFC discussion: roadmap to 1.0 (tracking)

[20000419]

Tracking issue for docs/rfc-roadmap-to-1.0.md — merged in #117. Discussion and amendments happen here; the doc is the source of truth and gets updated by PR.

Milestones: v0.7 (script completeness + latency polish: A1 while/until/case/elif, A2 $((...)), B1 prewarm, B2 CLI spawn fallback, C1 differential corpus in CI, C2 locale matrix, D1 harness installers, E1 RFC mini-doc, E2 SECURITY.md) → v0.8 (platform matrix + reach) → v1.0 (stability promise; full criteria in the doc).

Open questions (weigh in):

1. case fallthrough (;&) — support or loud-reject in A1?
2. Should B2's spawn fallback also serve fauxnix check?
3. Is an annotated fauxnix translate --explain worth it for D3 quickstarts, or scope creep?
4. npm co-maintainer — who else wants publish rights?

For wave authors: waves 2–4 (#111, #113/#114, #115) set the pattern — RFC (issue or docs/) → single-commit PRs with tests → integration rule per CONTRIBUTING → maintainer measurement comments. A-track items additionally need a differential corpus case (C1) and README deviations updated.

[r3wretrhy]

v0.9.2 cleared the #131 audit. Proposed v1.0 narrative next to this roadmap: Windows computer-use parity — agents are being trained on Mac fleets, Windows must not be a silent-wrong bash dialect.

• RFC: RFC: computer-use agents are trained on Mac fleets; Windows bash must not be silently wrong #156
• docs PR: docs: RFC for Windows computer-use parity after Mac-fleet training #158
• per-stage stdout: RFC: per-stage stdout/stderr in pipelines (echo hi >f | cat) #157
• remaining CommandSpec families still CommandSpec remaining families after the bounded-output slice #143

Not merging.

[20000419]

Roadmap v2 is live: docs/rfc-1.0-completeness-usability.md (merged via #171; the 8/20 track doc is marked superseded-with-history).

Snapshot at v0.9.3: 29/108 commands spec'd; differential corpus still in scratch (the big institutional gap); SECURITY.md absent; while/until/case, array assignment, positional params open.

Structure: 19 ownable items across three pillars — completeness (C-1..C-7), usability (U-1..U-8), trust/process (T-1..T-4) — each with an explicit definition of done, sequenced into four waves (v0.10 language, v0.11 usability, v0.12 institutions, then rc -> external audit round 2 -> 14-day soak -> freeze).

Top-leverage item: C-7 (differential corpus into test/differential/ with an oracle-gated runner, 200+ cases, scheduled CI, 95% byte-identical gate). It converts every "verified vs real bash" claim into a repeatable institution instead of a maintainer one-off.

Wave authors: claim items by ID in this thread. C-3 (positional params) needs its mini-RFC discussed here first — the MCP no-true-argv question is the interesting part.

[r3wretrhy]

Claiming for the next wave (r3wretrhy). Mini-RFC → one-commit PRs → not merging.

Wave 1 language (v0.10)

• C-4 $(cmd1; cmd2) — translator already has translateListInline; cmdsub currently rejects segments.length !== 1.
• C-3 mini-RFC first (positional params vs MCP no-true-argv) — issue + docs/rfc-positional-params.md.
• C-1 while/until only this slice (case/;& later). Parser already tokenizes while as a keyword but falls through to a simple command.

Usability / trust (composes before wave 3)

• T-1 SECURITY.md
• T-2 CONTRIBUTING RFC rule
• U-2 fauxnix doctor (extends check)
• U-3 loud-reject one-line alternative (audit emit sites)

Institutions (RFC says C-7 may land early)

• C-7 scaffolding: test/differential/ runner gated on FAUXNIX_DIFF_ORACLE, skip without Git Bash, first curated batch (audit repros + existing integration oracles). Not the full 200 yet.
• C-5 next CommandSpec remaining families after the bounded-output slice #143 family: sort/uniq/cut/tr (sed/awk keep custom parsers / skipSpec).
• C-6 RFC: per-stage stdout/stderr in pipelines (echo hi >f | cat) #157 first slice: fail-loud on non-last-stage >/>>/&> until in-stage writes exist (never silently-wrong identity pipes).

PRs incoming independently.

[r3wretrhy]

PRs for the claimed IDs (not merging):

• C-3 mini-RFC: docs: mini-RFC for session-scoped positional parameters (C-3) #172
• T-2 CONTRIBUTING RFC rule: docs: CONTRIBUTING RFC rule (T-2) #173
• T-1 SECURITY.md: docs: add SECURITY.md (RFC 1.0 T-1) #174
• C-6 fail-loud non-last >: fix: reject stdout redirects on non-last pipeline stages #175 (RFC: per-stage stdout/stderr in pipelines (echo hi >f | cat) #157 slice 1)
• C-7 differential scaffold (40 cases, skip-safe): test: scaffold C-7 differential corpus (skip-safe Git Bash oracle) #176
• C-5 sort/uniq/cut/tr specs: feat: CommandSpec for text-filters leftovers (sort/uniq/cut/tr) #177
• U-2 fauxnix doctor: feat: add fauxnix doctor extending check (U-2) #178
• C-4 $(cmd1; cmd2): feat: translate $(cmd1; cmd2) lists through translateListInline (C-4) #179

[20000419]

C-3 RFC: accepted. set -- as the only writer is exactly right — inventing argv from the MCP frame would be silently wrong, and a future argv-injection tool (if any harness asks) should indeed be its own MCP surface. Two notes for implementation:

1. $0 returning the tool name (bash) in MCP mode is the right shape — matches what a script echoing $0 expects to see in an agent transcript.
2. Persistence via the existing sidecar (like export/cd) means fauxnix_session status should also report the positional count — small addition, keeps the debugging story complete.

Proceed when ready; corpus cases from the RFC test list should land in test/differential/ per the C-7 convention.

[r3wretrhy]

v0.10.0 landed the claimed wave. C-3 RFC accepted — implementing set -- / $1 / $# / "$@" next, with $0 = MCP tool name (bash) and fauxnix_session status reporting positional count. Corpus cases go in test/differential/.

Also claiming next slices: C-1 while/until (not case yet), U-1 install --harness, U-3 reject-message alternatives, U-8 warm-path perf guard.

[r3wretrhy]

C-3 RFC was accepted; implementation and the next slices (not merging):

• U-8 perf guard: test: assert RFC U-8 warm p50 <50ms and first-frame <400ms #181
• C-1 while/until: feat: while/until loops (RFC 1.0 C-1 slice) #182 (case still later)
• U-1 fauxnix install --claude/--codex/--opencode/--kimi/--qwen: feat: fauxnix install for harness MCP config (U-1) #183
• U-3 loud-reject alternatives: fix: attach one-line alternatives to loud-rejects (U-3) #184
• C-3 set -- / $1 / $# / "$@" / shift: feat: session-scoped positional parameters (C-3 / #118) #185 ($0 = MCP tool name; fauxnix_session status prints positionals: N)

[r3wretrhy]

Claiming the next RFC 1.0 wave (r3wretrhy). Independent one-commit PRs, not merging.

Language leftover from v0.10

• C-2 A=(x y z) + ${name//pat/str} + ${name:off:len} — arrays ride FAUXNIX_ARRS / fx-arrput
• C-1 case / ;; / esac (;& / ;;& fail-loud; no fallthrough this slice)

Usability leftover from v0.11

• U-4 docs/examples/<harness>.md ×5 (claude / codex / opencode / kimi / qwen)

Institutions

• C-5 archive family CommandSpec (tar / gzip / gunzip / zcat / zip / unzip; find / sed / awk / egrep stay unspec'd)
• C-7 grow the differential corpus from the 40-case scaffold toward the 200 gate, plus a skip-safe scheduled oracle workflow (not on pull_request)

Open PRs #181–#186 stay as-is. Will link new PRs here as they land.

[r3wretrhy]

PRs for the claimed IDs (not merging):

• U-4 harness quickstarts: docs: harness quickstarts for claude/codex/opencode/kimi/qwen (U-4) #187
• C-5 gzip/zip CommandSpec (tar stays unspec'd — native tar.exe passthrough): feat: CommandSpec for gzip/gunzip/zcat/zip/unzip (C-5) #188
• C-7 corpus 40→101 + skip-safe weekly oracle: test: grow differential corpus + skip-safe weekly oracle (C-7) #189
• C-1 case / ;; / esac (;&/;;& fail-loud, no fallthrough): feat: case ... esac (RFC 1.0 C-1 slice) #190
• C-2 A=(x y z) + ${name//pat/str} + ${name:off:len}: feat: array assignment and param replace/slice (C-2 / #118) #191

while/until remains #182. In-stage pipeline writes remain #157.