diff --git a/GOALS-archive.md b/GOALS-archive.md new file mode 100644 index 00000000..8d96bdfc --- /dev/null +++ b/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- [achieved ] → detail: goals/archive/G--.md +Scope: +Acceptance: +``` + +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-`. + +## Archived goals + +_None yet._ diff --git a/GOALS.md b/GOALS.md new file mode 100644 index 00000000..de4a2841 --- /dev/null +++ b/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--.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- [] +Scope: +Goal: +Detail: goals/G--.md <- optional, omit if absent +Acceptance: +``` + +### Status tags +- `proposed` — not yet started; awaiting user confirmation to go `active` +- `active` — in progress +- `achieved ` — done; kept as a one-line record +- `abandoned` — dropped; one line on why stays in the entry +- `superseded by G-` — 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 ` 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-`. +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--.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. diff --git a/goals/AGENTS.md b/goals/AGENTS.md new file mode 100644 index 00000000..e60f4c67 --- /dev/null +++ b/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--.md` — e.g. `G-007-bytecompiler.md`. The `` is the stable reference (taken from the `G-` 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- + +Status: +Scope: +Acceptance: + +## Context + + +## Approach + + +## Alternatives considered +- — rejected because +- — deferred, see G-NNN + +## Notes + +``` + +### Archive + +- `goals/archive/` holds detail files for goals that have been achieved and moved to `GOALS-archive.md`. +- On archive: move `goals/G--.md` → `goals/archive/G--.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) diff --git a/goals/archive/.gitkeep b/goals/archive/.gitkeep new file mode 100644 index 00000000..93d689ed --- /dev/null +++ b/goals/archive/.gitkeep @@ -0,0 +1 @@ +# Placeholder so the archive directory is tracked before any files are moved into it.