punkshell/GOALS.md

Project Goals

This file is the canonical, harness-agnostic index of technical project goals for ShellSpy. It is referenced from the root AGENTS.md Child DOX Index and is a required read for any non-trivial work, so that agents can discover goals whose scope intersects their work.

Detail prose for goals that need it lives in goals/G-<id>-<slug>.md (see goals/AGENTS.md). The index entry is canonical; a detail file only elaborates and never contradicts its index entry.

Format

Each goal is one block:

### G-<id> [<status>] <short title>
Scope: <repo paths or module areas this goal touches>
Goal: <one line — what done looks like, self-contained>
Detail: goals/G-<id>-<slug>.md            <- optional, omit if absent
Acceptance: <measurable, verifiable pass/fail criterion>

Status tags

• proposed — not yet started; awaiting user confirmation to go active
• active — in progress
• achieved <YYYY-MM-DD> — done; kept as a one-line record
• abandoned — dropped; one line on why stays in the entry
• superseded by G-<id> — replaced; do not delete the old entry

Maintenance rules

• Only the user adds or edits goals. Agents must not invent goals.
• An agent whose work satisfies a goal's Acceptance: must flip that goal to achieved <date> as part of its DOX closeout pass, and report the flip in its completion summary.
• Agents must not flip proposed → active. They flag it in their completion report for the user to confirm.
• The Goal: line must stay self-contained enough that an agent who skips the detail file still does no harm. Detail files are enrichment, not load-bearing for safety.
• When the achieved section grows past ~30 entries, the oldest are moved to GOALS-archive.md and their detail files to goals/archive/.
• If a goal cannot be safely summarized in one line, that is a signal it is really two goals — split it.

Authoring a new goal (for agents)

When the user asks to "write a goal for X" or "help me draft a goal for Y", do the following:

1. Read this file in full so you know the format and can pick the next free G-<id>.
2. Ask the user only the questions below. Do not invent answers; ask them one at a time or batched if the user prefers. Stop asking once every required field has a real answer.
   • Scope: Which repo paths or module areas does this goal touch? (paths are preferred; module names are acceptable if paths are not yet known)
   • Goal: In one sentence, what does done look like? Push for an outcome, not an activity ("X compiles to bytecode ≤ 1.10× cost of Y", not "improve compiler performance").
   • Acceptance: What is the measurable, verifiable pass/fail criterion an agent can check against? If the user cannot state one, propose 2-3 candidate criteria and ask them to pick or refine.
   • Status: Default to proposed unless the user says it is already in progress (active).
   • Detail file? Only if the goal has non-obvious rationale, a multi-phase plan, alternatives worth recording, or needs more than ~3 lines of prose to state properly. If yes, propose a slug and offer to draft the detail file too. If no, omit the Detail: line.
3. Draft the goal block in this file's format and show it to the user for review and edit. Do not commit it as active unless the user confirms.
4. If a detail file is warranted and the user approves, create goals/G-<id>-<slug>.md using the structure in goals/AGENTS.md.
5. Do not delete or rewrite existing goals to make room for a new one. Append with the next free ID.

Goals

G-001 [proposed] Pluggable console backends for non-detectable terminals

Scope: src/modules/opunk/console-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm, src/modules/punk/repl-999999.0a1.0.tm, src/lib/app-punkshell/punkshell.tcl Detail: goals/G-001-pluggable-console-backends.md Goal: an interactive REPL can be launched against a non-detectable terminal-like device (ssh channel, tk text widget) via an ::opunk::Console subclass, with no edits to the base class or punk::console. Acceptance: a subshell started with an ssh-channel-backed and a tk-widget-backed ::opunk::Console subclass runs an interactive REPL that reads/writes through that console; size, at_eof, and can_respond are answered by the subclass overrides; the base ::opunk::Console and punk::console module are unchanged.

G-002 [proposed] Non-nested subshell with console targeting and inter-subshell comms

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm Detail: goals/G-002-non-nested-subshell.md Goal: a subshell can target a named console (default or non-default) and run without blocking the parent, replacing the synchronous nested interp-eval model. Acceptance: a parent REPL launches a subshell against a named console and continues processing its own input while the subshell runs; the parent can signal/query the running subshell; thread::send -async dispatched from within the subshell's code interp arrives at that interp (so packages like promise work when thread features aren't disabled); the "first subshell asymmetry" TODO at repl-999999.0a1.0.tm:3130 is resolved; existing synchronous subshell punk/safe/safebase/punksafe behaviour is preserved as a default mode.

G-003 [proposed] Configurable resource limits and sandboxing on subshell interps

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm Detail: goals/G-003-subshell-resource-limits.md Goal: a subshell's code interp can be launched with configurable resource limits (command-count, time) and sandboxing features, building on the resolved first-subshell asymmetry from G-002. Acceptance: a subshell can be launched with at least one resource limit (command-count via interp limit -command, or time via interp limit -time) and one sandboxing feature (e.g. interp hide of a command, or full safe-interp restrictions) applied to its code interp, enforceable regardless of subshell nesting depth; a subshell can be configured anywhere on the spectrum from unrestricted to fully safe via expose/hide of commands; the existing default subshell behaviour (no limits, no extra sandbox beyond the existing safe/safebase/punksafe types) is preserved when no limits are configured.