complete shell 100-item plan across parser, execution, security, and docs

Implement the full BareOS shell roadmap end-to-end, including grammar/tokenization
diagnostics, expansion/runtime hardening, execution graph tooling, builtins/job-control
stability, policy/sandbox controls, and release/traceability documentation updates.

- Add shell grammar baseline and diagnostics primitives:
  - introduce `docs/reference/shell-grammar.md` with lexer modes and EBNF contract
  - add rich diagnostic tokenizer output (mode + span metadata) via `tokenizeBareShellLineDetailed`
  - export structured parse snapshot helpers (`bareOsShellAstSnapshot`) and shell error kinds
  - add determinism coverage for tokenizer and AST snapshot outputs

- Harden expansion semantics and guardrails:
  - enforce expansion byte budgets (`BARE_OS_SHELL_EXPANSION_MAX_BYTES`)
  - add expansion trace hooks (`BARE_OS_SHELL_EXPANSION_TRACE`) with stage-level rows
  - add expansion recursion depth limits (`BARE_OS_SHELL_EXPANSION_MAX_DEPTH`)
  - tighten POSIX-mode arithmetic invalid-token diagnostics
  - preserve declared expansion ordering and document it in code/docs

- Extend redirection/pipeline execution model:
  - add normalized redirection planner (`planShellRedirections`) independent of side effects
  - add execution graph builder/debug surface (`buildShellExecutionGraph`)
  - support `<<-` operator in tokenizer/parser paths
  - add pipeline stage timeout safety (`BARE_OS_SHELL_PIPELINE_STAGE_TIMEOUT_MS`)
  - keep pipefail/pipestatus behavior verified with integration tests

- Improve builtins and control-flow reliability:
  - expand `read` builtin support:
    - `-r` raw mode
    - `-d` single-char delimiter
    - `-t` timeout semantics
  - refine wait/jobs semantics:
    - stable `jobs -l` parseable format expectations
    - synthetic pid mapping (`wait 410x`) and `wait all` support
  - keep trap registration/listing behavior deterministic and test-covered
  - add trap signal dispatch helper (`dispatchShellTrapSignal`) with normalization

- Add security and policy enforcement hooks:
  - command deny/allow policy gates:
    - `BARE_OS_SHELL_DENY_COMMANDS`
    - `BARE_OS_SHELL_ALLOW_COMMANDS`
  - sandbox mode (`BARE_OS_SHELL_SANDBOX`) to block external command execution
  - redirect path safety guard (`BARE_OS_SHELL_REDIRECT_GUARD`) for pseudo-path/traversal risks
  - emit structured shell audit event rows (`ctx.shellAuditEvents`) for start/error/finish

- Improve interactive UX resilience:
  - add prompt-hook timeout protection in fish readline:
    - `resolveShellPromptHookSegment`
    - env control `BARE_OS_SHELL_PROMPT_HOOK_TIMEOUT_MS`
  - ensure prompt segment resolution is non-blocking and safe on timeout/error

- Add reliability/performance artifacts and shell fast lane:
  - add `scripts/bench-shell-phases.mjs` for shell microbench sanity checks
  - add `scripts/gen-shell-reliability-report.mjs` and generate reliability JSON artifact
  - add root scripts:
    - `test:shell-fast`
    - `bench:shell`
    - `report:shell-reliability`

- Expand shell-focused docs and traceability:
  - add:
    - `docs/reference/shell-unsupported-behavior.md`
    - `docs/reference/shell-troubleshooting.md`
  - add contributor guides:
    - `developer-guide/17-how-to-add-shell-builtin.md`
    - `developer-guide/18-how-to-add-shell-grammar-feature.md`
  - update indexes/traceability/release gate docs:
    - `docs/reference/README.md`
    - `docs/reference/posix-issue7-traceability.md`
    - `docs/reference/environment-and-posix-appendix.md`
    - `docs/release-checklist.md`
    - `developer-guide/README.md`
    - `scripts/README.md`

- Add and update shell regression tests in `packages/bare-os-booter/test.js` for:
  - tokenizer spans/modes and deterministic output
  - AST snapshot schema/shape
  - redirection planner and execution graph behavior
  - expansion trace and strict arithmetic paths
  - `<<-` support
  - pipeline stage timeout handling
  - `read` delimiter/raw/timeout semantics
  - jobs/wait parseability and selection semantics
  - trap dispatch and normalization behavior
  - policy/sandbox/redirect-guard/audit-event pathways

Validation:
- `npm run test -w bare-os-booter`
- `npm run test:shell-bracket -w bare-os-booter`
- `npm run test:shell-fast`
- `npm run report:shell-reliability`

developer-guide/README.md

@@ -73,6 +73,8 @@ Full script index: [scripts/README.md](../scripts/README.md). Gate everything wi
 - **[14 — How to add a seed RPC](14-how-to-add-seed-rpc.md)** — Registry, channel wiring, booter policy, tests, and docs.
 - **[15 — How to add a `/proc/bare_os` node](15-how-to-add-proc-node.md)** — VFS wiring, snapshot alignment, tests, and schema docs.
 - **[16 — How to add a `/bin` utility](16-how-to-add-bin-utility.md)** — Build, man pages, POSIX matrix, seeder parity, and tests checklist.
+- **[17 — How to add a shell builtin](17-how-to-add-shell-builtin.md)** — Parser/executor/doc/test checklist for builtins.
+- **[18 — How to add a shell grammar feature](18-how-to-add-shell-grammar-feature.md)** — Grammar-first workflow (fixtures, fuzz-lite, perf guardrails).
 - **[Holepunch contributor track](13-holepunch-contributor-track.md)** — practical task map from Holepunch repos to Bare OS command, proc, and policy work.
 - **[13 — Privacy, telemetry, and PII](13-privacy-telemetry-pii.md)** — Scrub lists for NDJSON / OTel mirrors; non-secret posture.
 - **[Node → Bare module map](node-to-bare-modules.md)** — Guest-safe replacements for **`node:*`** built-ins (**`bare-crypto`**, **`bare-module`**, …).