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`

docs/reference/posix-issue7-traceability.md

@@ -7,7 +7,7 @@ This index links **IEEE Std 1003.1-2017 (Issue 7)** areas to **Bare OS** surface
 | XBD | Definitions / environment | Session **`vfs.env`**, **`/proc/self/environ`**, **`/proc/bare_os/security_posture.json`** | [environment-and-posix-appendix.md](environment-and-posix-appendix.md), handbook [ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) |
 | XSH | File I/O, metadata | **`ctx.bareOsSyscall`** ops + **`/proc/bare_os/syscalls.json`** (**`opsDetail`**, **`posixXsh`**, **`schemaVersion`**) | [POSIX_DECLARED_PROFILE.md](../architecture/POSIX_DECLARED_PROFILE.md), [posix-syscall-facade-map.md](posix-syscall-facade-map.md) |
 | XSH | Sockets (logical) | Socket bridge env (**`BARE_OS_POSIX_SOCKET_FD_BRIDGE`**, **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`**), **`socketMsgSurface`** in syscalls proc JSON | [syscall-socket-contract.md](syscall-socket-contract.md), handbook [ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) |
-| XCU | Shell | **`packages/bare-os-booter/lib/shell.js`**, env gates `**BARE_OS_SHELL_*`** | Handbook [ch.9 §3](../../handbook/09-posix-utilities-shell-and-vfs.md#3-shell-lists-pipelines-and-builtins-packagesbare-os-booterlibshelljs) |
+| XCU | Shell | **`packages/bare-os-booter/lib/shell.js`**, env gates `**BARE_OS_SHELL_*`** and signal trap dispatch helper (`dispatchShellTrapSignal`) | Handbook [ch.9 §3](../../handbook/09-posix-utilities-shell-and-vfs.md#3-shell-lists-pipelines-and-builtins-packagesbare-os-booterlibshelljs), [shell-grammar.md](shell-grammar.md), [shell-unsupported-behavior.md](shell-unsupported-behavior.md), [shell-troubleshooting.md](shell-troubleshooting.md) |
 | XCU | Utilities | **`/bin`** (from **`bare-os-coreutils`**), **`/etc/bare-os/posix_utilities.json`**, **`man`**, **`/share/man/man.json`** | Handbook [ch.9 §5](../../handbook/09-posix-utilities-shell-and-vfs.md#5-bin-utilities-catalog) |
 | XCU | **`awk`**, **`expr`**, `**test`/`[**` | Bounded engines in **`packages/bare-os-coreutils`**; profile **`BARE_OS_POSIX_PROFILE_VERSION`** + [posix-compliance-matrix.json](posix-compliance-matrix.json) **`susv4Refs`** rows | Handbook [ch.9 §7](../../handbook/09-posix-utilities-shell-and-vfs.md#7-awk-sed-grep-and-text-utils-packagesbare-os-coreutils) |
 | (informative) | P2P / replication | **`/proc/bare_os/replication`**, **`/proc/bare_os/swarm`**, **`/proc/bare_os/swarm_health.json`**, **`disk.os`** RPC, **`ctx.bareOsHrpcRequest`** (versioned route table) | [KERNEL_CONTRACT.md](../architecture/KERNEL_CONTRACT.md), handbook [ch.3](../../handbook/03-protocol-and-disk.md) |