docs: community reach ideas + Pharo 12/13/14 compatibility plan

.beads/issues.jsonl

@@ -0,0 +1,8 @@
+{"id":"postern-0g5","title":"Strip dated incident framing from /help/lint, /help/safety, /help/git","description":"Several sections contain dated Punt Labs incident references: /help/lint (\"On 2026-04-07, seven dispatch rounds reported lint zero...\"), /help/safety (\"This happened on 2026-04-06. The orphan subprocess held port 8422...\"), /help/git (\"This happened on 2026-04-06: two packages were deleted\"). Either remove the incident paragraphs entirely (the rule stands on its own) or reformulate as illustrative scenarios without calendar dates (\"For example, a subprocess can hold port 8422 after a hang, requiring manual cleanup\"). Scope is only the inline incident references in non-/help/lessons sections; /help/lessons itself is covered by its own bead.","status":"open","priority":2,"issue_type":"chore","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:40.116228924-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:16:40.116228924-07:00","labels":["help-generalization","public-release"]}
+{"id":"postern-1ro","title":"Remove hardcoded project prefixes from /help/testing and Makefile","description":"/help/testing says make test \"runs all test classes in packages ending with -Tests that belong to the project (prefixed Claude-, Postern-, PharoKeyring-, PharoSupervisedProcess-)\". These are Punt Labs own project set baked into the Makefile. A public users project will have different prefixes. Fix in two places: (1) make the Makefiles test/lint/filein targets read prefixes from config (env var, .postern.conf, or a Smalltalk-side config class) or use a convention-based filter (all -Tests packages that are not Pharo platform packages), and (2) update /help/testing (and /help/lint and /help/makefile) to describe whatever mechanism is chosen. Same hardcoding likely affects make lint and make filein.","notes":"APPROACH: introspect loaded packages for test prefixes. Add PosternHelp class\u003e\u003etestPackagePrefixes returning distinct first-segment prefixes from RPackageOrganizer default packages where a sibling '-Tests' package exists and the package is not a Pharo platform package. Rewrite /help/testing and /help/lint narrative to describe the convention and enumerate the prefixes that apply to the current image. Makefile side (separate phase): make test/lint/filein should consume the in-image helper via /repl, or read from a generated .postern/prefixes.txt. Start with the in-image helper only; Makefile rewiring is a second commit after the helper lands.","status":"open","priority":0,"issue_type":"task","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:39.972701734-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:20:31.840023656-07:00","labels":["help-generalization","public-release"]}
+{"id":"postern-brl","title":"/help/pharo — de-brand naming and package examples","description":"The naming conventions table in /help/pharo says: \"Domain prefix for product classes (e.g., Claude*, Postern*)\". Claude* is a sibling Punt Labs project (claude-agent-sdk-smalltalk), not Postern. The packages example then uses Claude-SDK-Types. Drop the Claude references — keep Postern* as the single illustrative case, or use a neutral example like MyApp*. Small change, low risk, improves public-release polish.","status":"open","priority":2,"issue_type":"chore","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:40.045527099-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:16:40.045527099-07:00","labels":["help-generalization","public-release"]}
+{"id":"postern-c6p","title":"Design: live-introspection for /help examples (eliminate hardcoding at the root)","description":"Several generalization problems — repo names, project prefixes, package lists, manifest class names, dashboard classes — could be solved at the root by having PosternHelp compute examples from live image state at request time instead of hardcoding strings. For example: PosternHelp class \u003e\u003e gitExampleRepoName returns (IceRepository registry ifEmpty: [#(\"\u003cyour-repo\u003e\")] ifNotEmpty: [:rs | rs first name]). The help then becomes self-verifying: whatever image it runs in, the examples match reality, and future drift is impossible. Lower priority than the direct fixes but could eliminate the whole class of hardcoding bugs. Design decision: introspection-based help vs. static strings with placeholders, and which sections warrant the extra complexity. Should be scheduled after the direct fixes land so we can compare concrete outputs.","notes":"DECISION 2026-04-11: Direction (2) chosen — targeted introspection for /help/git (repo name) and /help/testing (package prefixes) only. This bead is now the reflection follow-up: after postern-np5 and postern-1ro ship, evaluate whether introspection should expand to other sections (manifest in /help/lint, naming in /help/pharo, Makefile content in /help/makefile). Do not work this bead until both direct introspection beads are closed.","status":"open","priority":3,"issue_type":"feature","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:40.188042824-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:20:31.685091688-07:00","labels":["decision-made","design","help-generalization","public-release"]}
+{"id":"postern-eh0","title":"/help/makefile should yield copy-pasteable Makefile content, not prose","description":"The section currently describes what make setup/start/rebuild/filein/test/lint/status/check/eval/transcript/save/clean/clean-image *do* in prose tables but never shows the actual Makefile text. A user setting up Postern in their own Pharo project has to reverse-engineer the Makefile from the repo. Include copy-pasteable Makefile snippets (or a reference Makefile) organized by section: setup/lifecycle, development, cleanup. Each snippet should be runnable as-is with documented substitution points (project name, Pharo version, package prefixes, port). Consider whether to serve the full Makefile at a distinct endpoint (e.g. /help/makefile.mk plain text) or inline it in the markdown with triple-backtick blocks. User called this out explicitly as the biggest gap for public release.","status":"open","priority":0,"issue_type":"task","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:39.829134934-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:16:39.829134934-07:00","labels":["help-generalization","public-release"]}
+{"id":"postern-np5","title":"/help/git — generalize hardcoded claude-agent-sdk-smalltalk repo name","description":"Every Iceberg example in /help/git uses detect: [:r | r name = \"claude-agent-sdk-smalltalk\"]. Wrong even for Posterns own repo (should be \"postern\"), and wrong for any public user. Options: (a) use a placeholder like \u003cyour-repo-name\u003e with a note, (b) introspect the live image and generate the examples at request time from actually-registered Iceberg repos (IceRepository registry first ifNotNil: [:r | r name]), (c) use a generic pattern like IceRepository registry first with a warning. Option (b) is most powerful — the help becomes self-verifying for whatever image it runs in. Also strip the dated incident language (\"This happened on 2026-04-06: two packages were deleted from the repository\") — the rule stands without the date.","notes":"APPROACH: introspect IceRepository registry. Add PosternHelp class\u003e\u003egitExampleRepoName returning (IceRepository registry ifEmpty: ['\u003cyour-repo-name\u003e'] ifNotEmpty: [:rs | rs first name]). Rewrite PosternHelp class\u003e\u003egit to substitute the value into all Iceberg detect: blocks. Strip the dated 2026-04-06 incident sentence. Tests in PosternHelpTest: (a) registry has one repo → name is substituted into all three examples, (b) registry empty → placeholder appears, (c) no hardcoded 'claude-agent-sdk-smalltalk' remains in the section output.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Claude Agento","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:39.903250456-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:20:39.53983536-07:00","labels":["help-generalization","public-release"]}
+{"id":"postern-xvj","title":"Rewrite /help/lessons — private incident log to public principles","description":"All four lessons are dated Punt Labs internal incidents (2026-04-06, 2026-04-07, 2026-04-08) referencing specific projects (claude-agent-sdk-smalltalk, TTTBoardMorph, Spec2 dashboard), specific agents (kwb), and specific files (.claude/agents/kwb.md). The underlying patterns — silent tool success, lint rule-scope traps, refactoring blast radius, subscription lifecycle — are valuable teaching material; the presentation is a private incident report. Options: (a) rewrite as \"anti-patterns and mechanizations\" with illustrative scenarios stripped of dates and project names, or (b) fold the mechanisms into the relevant sections (/help/lint, /help/safety, /help/git) where they already partially appear and drop /help/lessons entirely. Prefer (a) if a standalone teaching narrative is stronger; prefer (b) if it just duplicates content. Must be decided before public release.","status":"open","priority":1,"issue_type":"task","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:39.759652046-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:16:39.759652046-07:00","labels":["help-generalization","public-release"]}
+{"id":"postern-zk6","title":"De-brand /help/dispatch — remove named sub-agent (kwb)","description":"/help/dispatch says \"All Smalltalk implementation in this image goes through a sub-agent (kwb)\" and later references `.claude/agents/kwb.md`. kwb is a Punt Labs ethos identity; public users wont have it. Rewrite the section to describe the *pattern* of delegating to a sub-agent without naming one. Include a recommended sub-agent definition template (required spec elements, TDD gates, stop conditions, out-of-scope list) that a user can adapt to whatever agent system they use (Claude Code, Codex, Cursor, custom). Keep the existing dispatch template (eval curl pattern, fluid class def, compile:classified:, TDD cycle, make lint gate, Iceberg commit with refreshDirtyPackages) — those are generic and good.","status":"open","priority":1,"issue_type":"task","owner":"claude@punt-labs.com","created_at":"2026-04-11T07:16:39.707701015-07:00","created_by":"Claude Agento","updated_at":"2026-04-11T07:16:39.707701015-07:00","labels":["help-generalization","public-release"]}

docs/ideas.md

@@ -0,0 +1,138 @@
+# Postern — ideas for community reach
+
+Postern is a remote HTTP driver for a live Pharo image. The code is stable
+and small. This document captures ideas that could extend Postern's reach
+into the broader Pharo community — beyond its original role as the driver
+for the Claude Agent SDK for Smalltalk.
+
+These are ideas, not commitments. Each one has been thought through but
+none has a bead, a PR, or an owner yet. They are recorded here so the
+repositioning conversation has a durable artifact to come back to.
+
+## Repositioning — from "our image driver" to "Pharo release tool"
+
+Current framing: Postern is the HTTP server that lets the Claude Agent
+SDK drive a Pharo image remotely.
+
+Possible repositioning: Postern is a release engineering tool for Pharo
+itself. The Pharo release workflow is largely human-in-the-loop today —
+launch a GUI, eyeball a Transcript, click through to verify a load.
+Postern flips that to black-box verification anyone can script.
+
+The repositioning is cheap because Postern already has zero Anthropic
+dependency. The change is mostly narrative and distribution (catalog
+entry, README first paragraph, community outreach) rather than code.
+
+## Target audiences under the new framing
+
+| Audience | Current pain | What Postern offers |
+|----------|--------------|---------------------|
+| Pharo core release engineer | Build a 13 image, launch GUI, click to verify classes/methods. No automation. | `curl localhost:8422/repl` from a CI script. Headless bring-up verification in seconds. |
+| Package maintainer (compat across 12/13/14) | Install library on each Pharo in turn, eye-check tests, hope nothing regressed | Three images up on three ports, one script diffs test results across all three. Regression matrix in one pass. |
+| Release QA | Human-driven smoke test: open browser, compile a known class, check it works | Scripted smoke battery hitting `/repl` with known-good evaluations. Automated go/no-go. |
+| VM developer | Correlate VM changes to image-level behavior differences | Run identical eval suite against two VMs + same image. Postern's request log (currently a bounded ring buffer) provides a timeline; a future append-only mode could extend this. |
+| Agent-driven dev (future) | None — no existing mechanism | LLM agents drive image iteration, compile/test/revert via tool calls. Pharo becomes LLM-native. |
+
+## Endpoint ideas
+
+Three endpoints that would make Postern more useful for release
+engineering work, beyond its current `/repl` + `/help` surface.
+
+### `/info` — environment fingerprint
+
+Returns JSON with:
+
+- Pharo version (major.minor.patch)
+- VM version and architecture
+- Image hash
+- List of loaded Metacello baselines with their resolved commits
+
+One request, full environment fingerprint. Makes matrix reporting
+trivial — CI stores the `/info` response alongside the test results so
+any regression can be correlated to the exact image it was observed on.
+
+### `/smoke` — scripted smoke battery
+
+Takes a spec (list of baselines to load + assertions to run), returns
+structured JSON pass/fail. Pharo release team scripts "did 13.1-rc2
+load and pass smoke?" as one HTTP call. The spec is declarative so the
+caller doesn't need to know Smalltalk internals.
+
+### Pharo-version-aware `/help`
+
+The existing `/help` endpoint documents the API. Extend it to indicate
+which endpoints require which Pharo version, so community users running
+older Pharo know what's available without reading source.
+
+## Multi-image orchestration
+
+A thin CLI wrapper (working name: `postern-matrix`) that spins up N
+Pharo images on different ports, runs the same request against all,
+diffs the results. The mechanism exists in Postern already; this is
+packaging and convenience. Example shape:
+
+```bash
+postern-matrix start --pharo=12,13,14
+postern-matrix run "Smalltalk version"
+postern-matrix diff --baseline pharo-12
+```
+
+Best home for this is probably a separate repo, not inside Postern
+itself, to keep Postern's surface area small.
+
+## Bootstrap mode
+
+An endpoint or CLI mode that drives a bare Pharo image through initial
+Metacello loads — essentially what `make rebuild` does for the Claude
+Agent SDK repo, but generalized and exposed as a Postern feature. Useful
+for CI pipelines that want to assemble a known image state before
+testing.
+
+## Distribution — making Postern discoverable
+
+| Asset | Purpose |
+|-------|---------|
+| `punt-labs/postern` repo | Primary code location (current) |
+| Pharo Catalog / Iceberg catalog entry | Discoverability. Users find it via `Metacello catalog`. |
+| `punt-labs/pharo-ci-matrix` (new repo) | Reference project showing Postern driving Pharo 12 + 13 + 14 matrix CI. GitHub Actions workflow other projects can copy. |
+| ESUG talk | "Headless Pharo release engineering with Postern." ESUG audience includes the people who would use this. |
+| Discord / mailing list announcement | Timed to a Pharo GA or alpha release, depending on Pharo's own cadence. |
+
+## Principles to preserve
+
+Three disciplines that keep the repositioning credible, in order of
+priority:
+
+1. **Postern stays tiny and stable.** If Postern becomes a kitchen sink,
+   the Pharo core team will not trust it for release work. Surface area
+   stays small — HTTP + eval + introspection + `/help` plus a couple of
+   new endpoints. Everything bigger (CI matrix, smoke batteries,
+   orchestration) lives in separate companion projects that depend on
+   Postern.
+2. **Zero Anthropic surface, visible.** Postern already has zero Claude
+   dependency. Double down on that framing. README first paragraph makes
+   the neutrality explicit. Community needs to trust this as neutral
+   infrastructure, not "that thing the Claude SDK people ship."
+3. **Pharo core team gets a path to adopt it.** Stated willingness to
+   hand the repo over to the Pharo org, if they want ownership,
+   removes hesitation on their side up front.
+
+## Lowest-risk first step (if we pursue the repositioning)
+
+Create `punt-labs/pharo-ci-matrix` as a public demonstration:
+
+- GitHub Actions workflow that spins up Pharo 12, 13, 14 images
+- Uses Postern to drive each through the same test suite
+- Outputs a pass/fail matrix as a PR comment
+- README explains the pattern so other package authors can copy it
+
+Concrete, visible use of Postern serving the community. Once it exists,
+catalog entry + Discord post + ESUG talk build on top of it. If the
+Pharo core team sees value, organic adoption follows without lobbying.
+
+## Status
+
+None of these ideas are committed to. Multi-Pharo-version support for
+Postern itself (the prerequisite for most of this) is being planned
+separately; see the docs for the `pharo-13-14-support` effort when it
+lands.