add goals infrastructure: index format, archive stub, goals/ DOX doc

Harness-agnostic technical project goal system. GOALS.md holds the canonical one-line index with format spec, status taxonomy, maintenance rules, and an agent-authoring workflow so agents asked to 'help me write a goal for X' ask the right questions. GOALS-archive.md is the achieved-goals archive stub. goals/AGENTS.md is the DOX child doc covering naming (G-<id>-<slug>.md), when a detail file is warranted, and the no-orphans/archive rule. goals/archive/.gitkeep tracks the archive dir.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Assisted-by: harness=opencode; primary-model=unknown; api-location=unknown

GOALS-archive.md

@@ -0,0 +1,21 @@
+# Achieved Goals Archive
+
+This file holds one-line records of goals that have been achieved and moved out of the active `GOALS.md` index to keep that file lean. Records here are historical context only — they explain why code exists in its current shape and are useful when future agents refactor or revisit the same area.
+
+## Format
+
+Each archived goal is one line, preserving its original ID and acceptance criterion so it remains traceable:
+
+```
+### G-<id> [achieved <YYYY-MM-DD>] <short title> → detail: goals/archive/G-<id>-<slug>.md
+Scope: <as in original index>
+Acceptance: <as in original index>
+```
+
+If a goal had no detail file, omit the `→ detail:` clause.
+
+Do not edit archived entries except to fix a broken path. If an archived goal is reopened, move it back to `GOALS.md` with a new ID and mark the old entry `superseded by G-<new id>`.
+
+## Archived goals
+
+_None yet._

GOALS.md

@@ -0,0 +1,69 @@
+# 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
+
+<!-- Append new goals below using the format above. Keep the list ordered by G-<id>. -->
+
+### 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.

goals/AGENTS.md

@@ -0,0 +1,68 @@
+# goals/
+
+## Purpose
+
+Holds optional detail prose for goals in the root `GOALS.md` index that need more than a one-line summary to state properly. The index entry is canonical; a detail file only elaborates and never contradicts its index entry.
+
+## Ownership
+
+- Files here are owned by the goal authoring workflow described in root `GOALS.md`.
+- Only the user adds or edits goals. Agents may draft detail files for user review but must not invent goals.
+- The root `GOALS.md` index entry is the source of truth. If index and detail disagree, the index wins; fix the detail.
+
+## Local Contracts
+
+### When a detail file is warranted
+
+A goal earns a detail file when it has any of:
+- Non-obvious rationale (rejected alternatives, constraints discovered, why it is not done the obvious way)
+- Multi-phase plan with sub-acceptance criteria
+- External references or prior art worth citing
+- More than ~3 lines of prose to state properly
+
+Simple goals with a clear one-liner and measurable acceptance stay index-only. Do not create empty detail files for completeness.
+
+### Naming
+
+`G-<id>-<slug>.md` — e.g. `G-007-bytecompiler.md`. The `<id>` is the stable reference (taken from the `G-<id>` in the root index); the slug is human-readable and may change without breaking links as long as the ID prefix is preserved. Sortable by `ls goals/`.
+
+### Detail file structure (suggested)
+
+```
+# G-<id> <short title>
+
+Status: <as in index>
+Scope: <as in index>
+Acceptance: <as in index>
+
+## Context
+<why this goal exists, what problem it solves>
+
+## Approach
+<chosen direction, key design decisions>
+
+## Alternatives considered
+- <alt A> — rejected because <reason>
+- <alt B> — deferred, see G-NNN
+
+## Notes
+<implementation notes, references, links>
+```
+
+### Archive
+
+- `goals/archive/` holds detail files for goals that have been achieved and moved to `GOALS-archive.md`.
+- On archive: move `goals/G-<id>-<slug>.md` → `goals/archive/G-<id>-<slug>.md`. Do not rename the ID prefix.
+- No orphan detail files: every file under `goals/` (excluding `archive/` and this `AGENTS.md`) must correspond to an `active` or `proposed` entry in the root `GOALS.md` index.
+
+## Work Guidance
+
+LF line endings (per root AGENTS.md user preferences).
+
+## Verification
+
+None — this folder is documentation only.
+
+## Child DOX Index
+
+- `archive/` — detail files for achieved/archived goals (no child AGENTS.md needed; this file's archive rules cover it)

goals/archive/.gitkeep

@@ -0,0 +1 @@
+# Placeholder so the archive directory is tracked before any files are moved into it.