From 5da307ebe273fd1cacfcd475ed7c61c76a39f6e3 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Mon, 13 Jul 2026 14:28:51 +1000
Subject: [PATCH] goals: add G-077 (punk executable -e one-liner support)

Proposed goal, wording user-approved 2026-07-13: make the perl/python/node -e
reflex work on punk kits (top-level and script subcommand forms) instead of
erroring, without ever reproducing stock-tclsh argv-swallow/stdin misparse
behaviour. Companion to the tclsh -e guardrails commit (AGENTS.md entry +
claude deny hook).

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
---
 GOALS.md                               |  4 ++++
 goals/G-077-punkexe-dash-e-oneliner.md | 21 +++++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 goals/G-077-punkexe-dash-e-oneliner.md

diff --git a/GOALS.md b/GOALS.md
index 7991e993..238d7f94 100644
--- a/GOALS.md
+++ b/GOALS.md
@@ -297,3 +297,7 @@ Detail: goals/G-075-punkargs-package-ids.md
 ### G-076 [active] Adopt upstream tcl9 dead-console fix: shared version gate for watchdog and help tcl warning
 Scope: src/modules/punk/lib-999999.0a1.0.tm (punk::lib::check), src/modules/punk/repl-999999.0a1.0.tm (repl::start watchdog arming), src/modules/punk/AGENTS.md, src/tests/modules/punk/lib/testsuites/lib/checkbugs.test
 Detail: goals/G-076-tcl9-deadconsole-fix-adoption.md
+
+### G-077 [proposed] punk executable -e one-liner support: make the tclsh-agent instinct work
+Scope: src/vfs/_config/punk_main.tcl (top-level arg dispatch), src/lib/app-punkscript/punkscript.tcl (script subcommand arg forms), src/tests/shell/testsuites/punkexe/scriptexec.test
+Detail: goals/G-077-punkexe-dash-e-oneliner.md
diff --git a/goals/G-077-punkexe-dash-e-oneliner.md b/goals/G-077-punkexe-dash-e-oneliner.md
new file mode 100644
index 00000000..bdfb79d5
--- /dev/null
+++ b/goals/G-077-punkexe-dash-e-oneliner.md
@@ -0,0 +1,21 @@
+# G-077 punk executable -e one-liner support: make the tclsh-agent instinct work
+
+Status: proposed
+Scope: src/vfs/_config/punk_main.tcl (top-level arg dispatch), src/lib/app-punkscript/punkscript.tcl (script subcommand arg forms), src/tests/shell/testsuites/punkexe/scriptexec.test
+Goal: `<punkexe> -e <script> ?args...?` and `<punkexe> script -e <script> ?args...?` execute the given Tcl code as a one-liner (args after the script land in `::argv`, `::argv0` = `-e`, non-interactive), so the -e reflex agents carry over from perl/python/node works on punk kits instead of erroring - while stock-tclsh misparse behaviour (argv-swallow + stdin read) is never reproduced.
+Acceptance: `punksys -e {puts hi}` and `punk902z script -e {puts hi}` print hi and exit 0 with and without piped stdin present (the one-liner may itself read stdin); a -e with no following script argument is a usage error, never an interactive fall-through; error in the one-liner prints errorInfo to stderr and exits 1 (matching the script subcommand's file form); scriptexec.test covers the above against the built executable.
+
+## Context
+
+Agents and harnesses habitually try `tclsh -e "script"` (the one-liner reflex from perl/python/node).
+Stock tclsh has no such flag: only `-encoding name` is recognised, and any other leading-dash
+argument is not treated as a script file - all arguments land in `$argv` and tclsh reads commands
+from stdin instead (hangs at an interactive prompt on a console; silently ignores the supposed
+one-liner when stdin is piped). Root `AGENTS.md` User Preferences documents the pitfall and a
+claude-harness PreToolUse hook (`.claude/settings.json`) denies such invocations with corrective
+guidance.
+
+The punk kits currently fail fast instead (`punk script: script file not found: '-e'`) but offer
+no one-liner form. This goal makes the instinct work on punk executables, removing the failure
+class for the kits entirely. app-punkscript's existing stdin form already provides the execution
+scaffolding (argv0/argv setup, errorInfo-to-stderr, exit-code discipline).