@shiwenbin1617/pstack 0.14.4

package/automations/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md

@@ -0,0 +1,205 @@
+# Feature-map example
+
+Map every user-facing feature Benny may reproduce. Read the relevant section before driving the app. Keep this map at the user point of view. Discover internals and current code paths at runtime instead of freezing them here.
+
+Copy this file outside `.claude/automations/benny/`, for example to `.claude/benny/feature-map.md`, and set `control.feature_map_path` to the copy. Pack refreshes must not overwrite it.
+
+## Per-feature template
+
+### `<feature name>`
+
+`<one-line user-visible purpose>`
+
+#### How a user gets there
+
+- Click path: `<screen> -> <menu, tab, or panel> -> <control>`
+- Keyboard shortcut: `<shortcut or none>`
+
+#### How the control adapter drives it
+
+- `<adapter action>` with `<inputs>` should `<visible result>`.
+- Reset: `<how the adapter returns to a fresh state>`.
+
+#### Stable selectors
+
+- `<role and accessible name>`
+- `<ARIA relationship>`
+- `<data-component or purpose-named data attribute>`
+
+Never use generated CSS or StyleX classes, dynamic hashes, child indexes, or brittle DOM position.
+
+#### States to exercise
+
+- Default, hover, focus-visible, active, disabled
+- Loading, empty, error
+- Selected, open, expanded
+- `<relevant feature-specific variants>`
+
+Mark states that do not apply.
+
+#### Preconditions and setup
+
+- Auth: `<account state>`
+- Data: `<fixture>`
+- Permissions: `<role>`
+- Flags: `<flag or none>`
+- Services: `<required availability>`
+
+#### Evidence and cross-check
+
+- Screenshot: `<app identity, feature, and discriminating state>`
+- Video: `<entry path, interaction, and final state>`
+- Cross-check: `<read-only state or value that confirms the UI>`
+
+#### Gotchas
+
+- `<known dead end or wrong surface>`
+- `<safe environment translation>`
+
+## Fictional example
+
+These features belong to a fictional task app. They are examples, not required Benny features.
+
+### Sign in
+
+Lets a user enter the task app.
+
+#### How a user gets there
+
+- Open the app and choose `Sign in`. No shortcut.
+
+#### How the control adapter drives it
+
+- `open_app`, `click Sign in`, `fill credentials`, and `click Continue` should open the item list.
+- Reset by signing out and clearing the disposable session.
+
+#### Stable selectors
+
+- Button `Sign in`, textboxes `Email` and `Password`, `data-component="sign-in-form"`
+
+#### States to exercise
+
+- Default, focus-visible, submitting, disabled, loading, error
+
+#### Preconditions and setup
+
+- Disposable account and available authentication service
+
+#### Evidence and cross-check
+
+- Record landing page through item list. Check read-only session state.
+
+#### Gotchas
+
+- A marketing page is the wrong surface. A missing auth service is a block.
+
+### Item list and detail
+
+Lets a user browse items and open one.
+
+#### How a user gets there
+
+- Open the `Items` tab, then choose a row.
+
+#### How the control adapter drives it
+
+- `select_tab Items` and `click <fixture item>` should open its detail.
+- Reset by closing the detail and clearing selection.
+
+#### Stable selectors
+
+- Tab and list named `Items`, fixture-named row, `data-component="item-detail"`
+
+#### States to exercise
+
+- Loading, empty, error, selected, open, expanded
+
+#### Preconditions and setup
+
+- Named fixture items, read permission, available item service
+
+#### Evidence and cross-check
+
+- Show selection and matching detail title. Check selected-item ID.
+
+#### Gotchas
+
+- Search results may look similar but use a different path.
+
+### Item editor
+
+Lets a user create or edit an item.
+
+#### How a user gets there
+
+- Choose `Edit` from detail or `New item` from the list.
+
+#### How the control adapter drives it
+
+- `click Edit`, `fill <field>`, and `click Save` should update detail.
+- Reset by restoring the fixture.
+
+#### Stable selectors
+
+- Buttons `Edit`, `New item`, `Save`, form `Item editor`, label-linked fields
+
+#### States to exercise
+
+- Default, focus-visible, dirty, validating, disabled, saving, error, success
+
+#### Preconditions and setup
+
+- Editable fixture, write permission, available save service
+
+#### Evidence and cross-check
+
+- Show field change through updated detail. Check the stored item value read-only.
+
+#### Gotchas
+
+- Do not inject form state. A read-only detail field is not the editor.
+
+### Settings
+
+Lets a user change personal preferences.
+
+#### How a user gets there
+
+- Open the profile menu, then choose `Settings`.
+
+#### How the control adapter drives it
+
+- `open_menu Profile`, `click Settings`, and `toggle <preference>` should update the control.
+- Reset by restoring the starting preference.
+
+#### Stable selectors
+
+- Button `Profile`, menu item `Settings`, region `Settings`, purpose-named preference attribute
+
+#### States to exercise
+
+- Closed, open, selected, focus-visible, disabled, loading, error
+
+#### Preconditions and setup
+
+- Signed-in test account, known preferences, available preference service
+
+#### Evidence and cross-check
+
+- Show the menu path and final control state. Check the preference value read-only.
+
+#### Gotchas
+
+- Operating-system settings are a different surface.
+
+## Completeness checklist
+
+- Every reproducible user-facing feature has a section.
+- Every section names a user path, adapter actions, and reset.
+- Selectors use roles, names, ARIA, stable component markers, or purpose-named attributes.
+- No selector uses generated classes or DOM position.
+- Relevant interaction, loading, empty, error, selected, and expanded states are covered.
+- Auth, fixtures, permissions, flags, and services are explicit.
+- Screenshot, video, and underlying cross-check requirements are explicit.
+- Wrong surfaces, dead ends, and safe environment translations are listed.
+- Implementation details remain runtime discoveries.

package/automations/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md

@@ -0,0 +1,93 @@
+# Verify an existing fix
+
+Use this mode when an open pull request or merged commit plausibly fixes the report.
+
+The existing artifact owns the fix. Verify it. Do not edit it, author a competing patch, or open another pull request.
+
+## Qualify the artifact
+
+Require one concrete artifact:
+
+- An open pull request with code changes that address the symptom
+- A merged pull request
+- A merged commit with matching code and intent
+
+A thread claim, tracker status, branch name, or cause hypothesis without a pull request or commit is not enough.
+
+When several artifacts exist, choose the one linked from the source thread or tracker. Otherwise choose the closest match to the affected code and state why.
+
+## Protect the working tree
+
+Use an isolated worktree or another clean checkout when the repository supports it. Do not overwrite user changes.
+
+Record:
+
+- Baseline revision
+- Patched revision
+- Pull request or commit URL
+- Build and environment inputs shared by both runs
+
+Use regular `github.com` pull request links.
+
+## Measure the baseline
+
+For an open pull request, use its base branch as the baseline.
+
+For a merged fix, use the revision immediately before the fix when that revision builds and represents the old behavior.
+
+Through the configured control adapter:
+
+1. Bring up the baseline app.
+2. Confirm the correct app and environment.
+3. Run the reported path through real UI actions.
+4. Observe the discriminating symptom.
+5. Reset and repeat it.
+6. Capture baseline recording, screenshot, and state check.
+
+If the symptom does not appear twice on the baseline, there is no baseline. Do not claim that the fix works.
+
+## Measure the patched build
+
+Build and run the pull request or fix commit with the same environment and data.
+
+1. Run the same UI path.
+2. Repeat it twice.
+3. Confirm that the broken state is gone.
+4. Confirm the expected state appears.
+5. Capture after recording, screenshot, and the same state check.
+
+Do not stop at compilation or tests. The after result must come from a running patched app.
+
+## Outcomes
+
+### Confirmed
+
+The baseline reproduces twice and the patched build resolves it twice.
+
+- Mark operations status as verified.
+- Link the artifact.
+- Post one concise source-thread reply after the source preflight.
+- Include the before and after result.
+- Open no pull request.
+
+### Insufficient fix
+
+The symptom appears on both baseline and patched builds.
+
+- Mark operations status as reproduced but not fixed.
+- Link the artifact and say it did not resolve the symptom.
+- Post the normal confirmed-repro source update if the run has not already used it.
+- Open no competing pull request.
+
+### Inconclusive
+
+The baseline does not reproduce, the patched app cannot run, or the evidence does not show the discriminating state.
+
+- Do not claim success.
+- State which half could not be measured.
+- Keep the result in the operations thread or run output.
+- Post nothing in the source thread unless a direct question requires an answer.
+
+## Cleanup
+
+Stop both builds, remove temporary profiles and captures according to retention policy, and return the repository to its prior state without discarding user work.

package/automations/benny/skills/setup-benny/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: setup-benny
+description: Configure Benny and prepare its triage and repro automations. Use when installing Benny or changing its Slack, tracker, repository, routing, control, model, or budget settings.
+disable-model-invocation: true
+---
+
+# Set up Benny
+
+Benny ships as a dormant automation pack inside pstack. The plugin manifest exposes only pstack's normal skill root; this file and the two operational files are not slash skills.
+
+The human enters setup by pointing their agent at the pack's `FOR_AGENTS.md`. The bootstrap flow copies the whole pack into the target repository, then reads this file directly at `.claude/automations/benny/skills/setup-benny/SKILL.md`.
+
+Benny needs external configuration and two live scheduled automations. On Claude Code create them with the `schedule` skill (cron routines); on Codex use `~/.codex/automations`. Both need a Slack MCP server connected for the channel side.
+
+Do not create or update an automation until the user explicitly asks. Never put a secret value in plugin files, prompts, or committed configuration.
+
+## 1. Copy the pack and enable shared pstack skills
+
+Do this before asking for Benny configuration and before invoking the built-in `/automate` skill.
+
+Ask which repository will run the automations. The source pack is the directory containing `FOR_AGENTS.md`. The destination is `<target-repository>/.claude/automations/benny/`.
+
+Merge the entire source pack into the destination:
+
+1. Create the destination when it is absent.
+2. Copy every source file to the same relative path.
+3. Preserve destination-only files. Never delete unrelated files during install or refresh.
+4. Keep user-owned configuration, feature maps, and routing maps outside the destination. Never overwrite them.
+5. When an existing source-managed file differs, inspect the diff and merge without discarding local edits. If ownership is ambiguous, stop and ask before replacing it.
+6. Verify that the destination contains `FOR_AGENTS.md`, this setup file, both operational files, their references, and the templates.
+
+If this file is already being read from the target destination, treat the copy as complete and run the same verification before continuing.
+
+Add pstack to the target repository's `.claude/settings.json`. If the file or `.claude` directory does not exist, create it.
+
+Merge this entry into the existing JSON or JSONC:
+
+```json
+{
+	"plugins": {
+		"pstack": { "enabled": true }
+	}
+}
+```
+
+Preserve every unrelated top-level setting and every other plugin entry. If `plugins.pstack` already exists, change only its `enabled` value. Preserve comments and valid JSONC syntax when the file uses JSONC. Validate the file after editing it.
+
+Reload the target project or start a fresh agent rooted there. Verify that these shared pstack skills resolve from project scope:
+
+- `how`
+- `why`
+- `tdd`
+- `unslop`
+- `principle-separate-before-serializing-shared-state`
+- `principle-minimize-reader-load`
+- `principle-guard-the-context-window`
+- `principle-sequence-verifiable-units`
+- `principle-fix-root-causes`
+- `principle-prove-it-works`
+
+Do not count a skill loaded from the current session or a user-scoped plugin. The check must show that a fresh agent in the target repository receives pstack through project settings.
+
+If project-scoped plugin installation is unavailable or any shared dependency does not resolve, stop and explain the failure.
+
+The Benny files are read directly from `.claude/automations/benny/`. Do not add that directory to a plugin manifest or expect its `SKILL.md` files to appear in the slash-skill list.
+
+Tell the user that `.claude/settings.json`, `.claude/automations/benny/`, and any referenced secret-free configuration must be committed before either automation is enabled. Do not commit them unless the user asks.
+
+Once this check passes, live automation prompts may read the committed operational files by their stable repository-relative paths. They must not embed a plugin cache path or copy the file contents.
+
+## 2. Adapt the configuration
+
+Open these copied examples:
+
+- `../../templates/configuration.example.yaml`
+- `../reproduce-and-fix-issues/references/feature-map.example.md`
+
+Create user-owned copies outside `.claude/automations/benny/`. These are configuration files, not pack files. Example locations:
+
+- Project config, such as `.claude/benny/configuration.yaml`
+- Project feature map, such as `.claude/benny/feature-map.md`
+- Project routing map, such as `.claude/benny/routing.md`
+- User config, such as `~/.config/benny/configuration.yaml`
+- User feature map, such as `~/.config/benny/feature-map.md`
+
+Fill one feature-map section for every user-facing feature the automation may reproduce. Keep it at the user point of view. Do not freeze implementation details or current code paths in the map.
+
+Do not edit the copied examples. Pack refreshes may update source-managed files after conflict review, but they must never touch the user-owned copies.
+
+Prefer committed, secret-free files in the target repository when a fresh automation checkout must read them. Otherwise paraphrase the required values into the live prompt. Reference a repository file only after the built-in `/automate` skill confirms that the file is committed in the repository where the automation runs.
+
+Use stable repository-relative paths for committed pack and configuration files. Never reference the plugin source directory or a plugin cache path from a live automation.
+
+## 3. Fill the required choices
+
+Ask for or confirm:
+
+- Source Slack channel ID
+- Optional operations or status channel ID
+- Repository URL and default branch
+- Triage identity or Slack user ID
+- Issue tracker type, team, project, labels, and intake status
+- Tracker adapter skill or MCP actions
+- Optional routing map path
+- Required control skill name
+- Required user-facing feature-map path
+- Status emoji strings
+- Pull request URL format
+- Polling and effort budgets
+- Model slug for triage, repro, code work, and media review
+
+Use only model values the `Agent` tool's `model` enum accepts in this session. Do not guess a value and do not carry over a private default.
+
+The source channel, triage identity, repository, tracker adapter, control skill, and feature map must be explicit. Fail setup if any required value stays ambiguous.
+
+Use pstack's `unslop` skill on the final automation names, descriptions, and prompt shims before saving them.
+
+## 4. Check integration capabilities
+
+The triage automation needs:
+
+- Read access to the configured source Slack channel and its threads
+- Thread-reply access in that channel
+- Attachment metadata and file download access when reports include media
+- Search, read, create, and update access through the configured issue-tracker adapter
+
+The repro automation needs:
+
+- Read access to the source thread
+- Thread-reply access in the source channel
+- Optional post and edit access in the configured operations channel
+- Repository read and history access
+- A pull request action that can open a draft pull request
+- The configured control-adapter skill
+
+Prefer a connected Slack MCP server's actions for reads and posts. The optional `BENNY_SLACK_BOT_TOKEN` may fill a narrow gap such as editing one operations status message or downloading an attachment. Store the value in a secret manager or environment, not in YAML.
+
+Do not use undocumented integration endpoints.
+
+## 5. Prepare the routing map
+
+If the user wants reroutes or owner pings:
+
+1. Copy `../triage-issue-reports/references/routing.example.md` outside `.claude/automations/benny/`.
+2. Replace every placeholder with public or organization-local values.
+3. Keep owner pings off by default.
+4. Allow a ping only for a configured feature owner or a confirmed likely regression author.
+
+If no routing map is configured, triage may classify a report but must not guess a destination or owner.
+
+## 6. Verify the control adapter
+
+Read `../reproduce-and-fix-issues/references/control-adapter.md` and the user's completed feature map.
+
+Confirm that the named skill can:
+
+- Bring up the target app
+- Navigate every mapped feature through the real UI
+- Exercise mapped states through declared adapter actions
+- Inspect state without forcing the result
+- Capture screenshots
+- Start and stop a recording
+- Clean up its processes and temporary data
+
+If any capability is missing, leave the repro automation disabled. It must fail closed rather than claim a reproduction it did not perform.
+
+## 7. Prepare the live automations
+
+Ask whether this is first-time creation or configuration of existing automations.
+
+Read `../../FOR_AGENTS.md` from the copied pack as the primary user-intent source for either path. Use it to understand the two triggers, tools, instructions, outcomes, and shared rules.
+
+### First-time creation
+
+Create one automation at a time.
+
+For each automation:
+
+1. Read the matching copied prompt template as secondary internal source material.
+2. Turn `FOR_AGENTS.md`, the finished Benny configuration, and the template intent into a complete natural-language request.
+3. Tell the live prompt to read and follow its exact committed operational file under `.claude/automations/benny/`.
+4. Use the stable repository-relative path, not a plugin source or cache path. Do not copy the operational file contents into the live prompt.
+5. Read and follow the built-in `automate` skill.
+6. Let `automate` discover Slack channels, the repository, and connected integrations.
+7. Let `automate` confirm that the copied pack and any referenced configuration files are committed in the same repository where the automation will run.
+8. Let `automate` show its draft table, obtain approval, ask readiness, and open the Automations editor.
+9. Finish the editor handoff for this automation before starting the next one.
+
+Give `automate` this complete triage intent, filled from configuration:
+
+- Name `benny-triage`.
+- Read and follow `.claude/automations/benny/skills/triage-issue-reports/SKILL.md` for every run.
+- Trigger on each new top-level report in the configured source Slack channel.
+- Read the triggering thread and reply only inside it.
+- Use the configured issue-tracker integration.
+- Classify, inspect evidence, trace cause, dedupe, and create only clear new bugs.
+- End one thread-only verdict with the configured `[benny:bug]`, `[benny:performance]`, or `[benny:other]` marker and optional tracker URL.
+- Never post a source-channel root message.
+
+After the triage editor handoff is complete, give `automate` this complete repro and fix intent:
+
+- Name `benny-reproduce`.
+- Read and follow `.claude/automations/benny/skills/reproduce-and-fix-issues/SKILL.md` for every run.
+- Trigger on the same new top-level reports in the configured source Slack channel.
+- Use the configured repository and default branch.
+- Read the source thread and reply only inside it.
+- Include pull request creation and the configured tracker, control-adapter, and feature-map requirements. Paraphrase mapped user paths and states unless `automate` confirms an eligible committed file in the same repository.
+- Wait for a trusted triage marker before acting.
+- Reproduce the exact symptom twice through the mapped real UI and capture evidence.
+- Verify an existing fix without authoring over it.
+- Attempt an optional bounded fix only after confirmed repro, then open a draft pull request when proof and checks pass.
+- Never post a source-channel root message.
+
+Do not duplicate `automate`'s Slack, repository, integration, completeness, authentication, draft-review, approval, readiness, or editor-handoff work.
+
+### Existing automations
+
+The built-in `automate` skill is creation-only. Do not use it to search for, inspect, or update existing automations.
+
+Finish configuration, routing, control-adapter, and feature-map validation. Then give the user this concise editor checklist.
+
+For the existing triage automation, update:
+
+- Name and description
+- Direct instruction to read `.claude/automations/benny/skills/triage-issue-reports/SKILL.md`
+- New top-level Slack report trigger and source channel
+- Slack thread read and reply capabilities
+- Issue-tracker integration
+- Paraphrased triage instructions, thread-only rule, and Benny verdict markers
+
+For the existing repro automation, update:
+
+- Name and description
+- Direct instruction to read `.claude/automations/benny/skills/reproduce-and-fix-issues/SKILL.md`
+- Matching Slack trigger and source channel
+- Repository and default branch
+- Slack thread read and reply capabilities
+- Pull request action
+- Tracker, control-adapter, and feature-map requirements
+- Paraphrased marker wait, evidence, verification, and bounded-fix instructions
+
+Ask the user to update each existing automation directly in its Automations editor. Do not create replacements or duplicates.
+
+### Creation boundary
+
+Never call a direct automation backend service or backend automation tool, and never build or open an editor protocol deep link. For new automations, the only finish path is the host's own reviewed automation editor: the `schedule` skill on Claude Code, `~/.codex/automations` on Codex.
+
+Do not enable either automation until the thread-safety test passes after the editor save.
+
+## 8. Test thread safety
+
+Use a test channel or a harmless test report.
+
+Before testing, confirm that the target repository's `.claude/settings.json`, `.claude/automations/benny/`, and every referenced secret-free configuration file are committed on the branch used by the automation checkout. Confirm that both live prompts point at their exact committed operational files. If any check fails, stop. Tell the user that the automation cannot be enabled yet.
+
+Verify:
+
+1. Triage stores the root `thread_ts` and posts exactly one verdict as a reply.
+2. The verdict contains one configured marker.
+3. Repro accepts the marker only from the configured triage identity.
+4. Repro keeps the same immutable source coordinates.
+5. No source-channel root message appears.
+6. A delegated worker cannot use any Slack write action.
+7. Missing coordinates, a deleted parent, or a failed preflight produces no post and no tracker issue.
+
+Enable normal traffic only after all seven checks pass.