gentle-pi 2.1.2 → 2.2.0

package/skills/issue-creation/SKILL.md

@@ -1,223 +1,149 @@
 ---
 name: gentle-ai-issue-creation
-description: "Create Gentle AI issues with issue-first checks. Trigger: creating GitHub issues, bug reports, or feature requests."
+description: "Create and triage GitHub issues from repository evidence. Trigger: issue creation, bug reports, feature requests, or issue approval."
 license: Apache-2.0
 metadata:
   author: gentleman-programming
-  version: "1.0"
+  version: "1.2"
 ---
 
-## When to Use
+# Issue Creation
 
-Use this skill when:
-- Creating a GitHub issue (bug report or feature request)
-- Helping a contributor file an issue
-- Triaging or approving issues as a maintainer
+## When To Use
 
----
+Use this skill when creating, drafting, triaging, or approving an issue in the current GitHub repository.
 
-## Critical Rules
+## Core Rule
 
-1. **Blank issues are disabled** — MUST use a template (bug report or feature request)
-2. **Every issue gets `status:needs-review` automatically** on creation
-3. **A maintainer MUST add `status:approved`** before any PR can be opened
-4. **Questions go to [Discussions](https://github.com/Gentleman-Programming/agent-teams-lite/discussions)**, not issues
+Discover the repository's actual contribution workflow before proposing or publishing an issue. Templates, labels, approval gates, and Discussions support are repository policy, not universal GitHub behavior.
 
----
+## Safe Discovery
 
-## Workflow
+Run read-only checks first:
 
+```bash
+gh auth status
+REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)"
+REPO_URL="$(gh repo view --json url -q .url)"
+HOST="${REPO_URL#*://}"
+HOST="${HOST%%/*}"
+gh repo view --json nameWithOwner,url,hasDiscussionsEnabled,hasIssuesEnabled,isBlankIssuesEnabled
+git ls-files CONTRIBUTING.md CONTRIBUTING.* .github/CONTRIBUTING.md .github/ISSUE_TEMPLATE
+gh api --hostname "$HOST" --paginate "repos/$REPO/labels?per_page=100" --jq '.[].name'
 ```
-1. Search existing issues for duplicates
-2. Choose the correct template (Bug Report or Feature Request)
-3. Fill in ALL required fields
-4. Check pre-flight checkboxes
-5. Submit → issue gets status:needs-review automatically
-6. Wait for maintainer to add status:approved
-7. Only then open a PR linking this issue
-```
-
----
-
-## Issue Templates
 
-### Bug Report
+Also inspect:
 
-Template: `.github/ISSUE_TEMPLATE/bug_report.yml`
-Auto-labels: `bug`, `status:needs-review`
+- repository instructions such as `CONTRIBUTING.md` and `README.md`;
+- files under `.github/ISSUE_TEMPLATE`;
+- `.github/ISSUE_TEMPLATE/config.yml` when present;
+- issue forms, required fields, and labels declared by each template;
+- existing open and closed issues for duplicates and established wording.
 
-#### Required Fields
+Stop and ask for repository context if authentication, repository resolution, verification that REPO and HOST are non-empty, required metadata is unavailable, hasIssuesEnabled is false, or policy discovery fails. Never continue from failed discovery into issue publication.
 
-| Field | Description |
-|-------|-------------|
-| **Pre-flight Checks** | Checkboxes: no duplicate + understands approval workflow |
-| **Bug Description** | Clear description of the bug |
-| **Steps to Reproduce** | Numbered steps to reproduce |
-| **Expected Behavior** | What should have happened |
-| **Actual Behavior** | What happened instead (include errors/logs) |
-| **Operating System** | Dropdown: macOS, Linux variants, Windows, WSL |
-| **Agent / Client** | Dropdown: Claude Code, OpenCode, Gemini CLI, Cursor, Windsurf, Codex, Other |
-| **Shell** | Dropdown: bash, zsh, fish, Other |
+A no-template fallback is allowed only when isBlankIssuesEnabled is explicitly true. Otherwise follow discovered contact links or stop and ask; never publish.
 
-#### Optional Fields
-
-| Field | Description |
-|-------|-------------|
-| **Relevant Logs** | Log output (auto-formatted as code block) |
-| **Additional Context** | Screenshots, workarounds, extra info |
-
-#### Example — Bug Report via CLI
+After discovery and review, build optional label arguments using only labels that exist and repository policy permits the actor to apply:
 
 ```bash
-gh issue create --template "bug_report.yml" \
-  --title "fix(scripts): setup.sh fails on zsh with glob error" \
-  --body "
-### Pre-flight Checks
-- [x] I have searched existing issues and this is not a duplicate
-- [x] I understand this issue needs status:approved before a PR can be opened
-
-### Bug Description
-Running setup.sh on zsh throws a glob error when no matching files exist.
-
-### Steps to Reproduce
-1. Clone the repo
-2. Run \`./scripts/setup.sh\` in zsh
-3. See error: \`zsh: no matches found: skills/*\`
-
-### Expected Behavior
-The script should handle missing glob matches gracefully.
-
-### Actual Behavior
-Script crashes with glob error.
+LABEL_ARGS=()
+# Repeat for each reviewed, permitted discovered label.
+LABEL_ARGS+=(--label "$LABEL")
+```
 
-### Operating System
-macOS
+An empty array applies no label; do not invent labels.
 
-### Agent / Client
-Claude Code
+## Workflow
 
-### Shell
-zsh
+1. Describe the problem or request in one sentence and derive a short search query.
+2. Search open and closed issues:
 
-### Relevant Logs
-\`\`\`
-zsh: no matches found: skills/*
-\`\`\`
-"
-```
+   ```bash
+   gh issue list --repo "$HOST/$REPO" --state all --search "$QUERY" --limit 1000
+   ```
 
----
+   If 1000 results are returned or completeness remains uncertain, narrow the search, use read-only API discovery, or stop and ask before publishing.
 
-### Feature Request
+3. If an issue already covers the same behavior, comment there instead of creating a duplicate.
+4. Choose a repository-provided template only when its purpose matches the report.
+5. Fill every required template field from known evidence. Ask for missing facts rather than inventing them.
+6. Apply labels only when they exist and repository guidance establishes who should apply them.
+7. Publish only after the title, body, target repository, and selected template or fallback have been reviewed, and the pre-submission privacy review below has passed.
 
-Template: `.github/ISSUE_TEMPLATE/feature_request.yml`
-Auto-labels: `enhancement`, `status:needs-review`
+## Pre-submission Privacy Review
 
-#### Required Fields
+Pre-submission privacy review is mandatory. Scan every issue body immediately before `gh issue create`. The scan replaces — never deletes — environment-specific data with explicit placeholders so the reproduction still teaches:
 
-| Field | Description |
-|-------|-------------|
-| **Pre-flight Checks** | Checkboxes: no duplicate + understands approval workflow |
-| **Problem Description** | The pain point this feature solves |
-| **Proposed Solution** | How it should work from the user's perspective |
-| **Affected Area** | Dropdown: Scripts, Skills, Examples, Documentation, CI/Workflows, Other |
+| Category | Replace with | Example (before → after) |
+|----------|---------------|---------------------------|
+| Private project names | `<project-name>` | `my-private-project-b` → `<project-name>` |
+| Usernames | `<user>` | `C:\Users\my-real-username\go\bin` → `C:\Users\<user>\go\bin` |
+| Hostnames | `<hostname>` | `devbox-macbook.local` → `<hostname>` |
+| Home paths | `/home/<user>` or `C:\Users\<user>` | (covered above) |
+| API keys, tokens, passwords | `<token>` / `<password>` | `ghp_abc123...` → `<token>` |
+| Internal ports / hostnames | `<host>:<port>` | `10.0.0.42:5432` → `<host>:<port>` |
 
-#### Optional Fields
+Do NOT redact intentionally public identifiers: tool names (`gentle-ai`, `engram`, `go`, `node`, `python`), package names, public documentation URLs, generic example domains (`example.com`, `localhost`). Keep reproduction structure with placeholders — never redact an example into nothingness.
 
-| Field | Description |
-|-------|-------------|
-| **Alternatives Considered** | Other approaches or workarounds |
-| **Additional Context** | Mockups, examples, references |
+**Rule of thumb:** if the reader can run the reproduction step after you replace every identifier with its placeholder, the sanitization is correct. If a step becomes impossible (because the placeholder consumed a needed value), that step needs the value — and you should mark it `<value-required>` and explain in the body what the user should fill in.
 
-#### Example — Feature Request via CLI
+## Template Paths
 
-```bash
-gh issue create --template "feature_request.yml" \
-  --title "feat(scripts): add Codex support to setup.sh" \
-  --body "
-### Pre-flight Checks
-- [x] I have searched existing issues and this is not a duplicate
-- [x] I understand this issue needs status:approved before a PR can be opened
-
-### Problem Description
-The setup script only configures Claude Code, Gemini CLI, and OpenCode. Codex users have to manually copy skills.
-
-### Proposed Solution
-Add a Codex option to setup.sh that links skills to the .codex/ directory.
-
-Example:
-\`\`\`bash
-./scripts/setup.sh --agent codex
-\`\`\`
-
-### Affected Area
-Scripts (setup, installation)
-
-### Alternatives Considered
-Manually symlinking, but that defeats the purpose of the setup script.
-"
-```
+Do not guess a template filename. If multiple templates could apply and repository guidance does not distinguish them, stop and ask which one to use.
 
----
+- .yml and .yaml files are GitHub Issue Forms. Do not parse or render their schema. Open the web issue chooser and stop for human completion:
 
-## Label System
+  ```bash
+  gh issue create --repo "$HOST/$REPO" --web "${LABEL_ARGS[@]}"
+  ```
 
-### Applied Automatically on Issue Creation
+- .md files are Markdown templates. Read the matching template, complete it from known evidence into a reviewed BODY_FILE, then publish it:
 
-| Template | Labels added |
-|----------|-------------|
-| Bug Report | `bug`, `status:needs-review` |
-| Feature Request | `enhancement`, `status:needs-review` |
+  ```bash
+  gh issue create --repo "$HOST/$REPO" --title "$TITLE" --body-file "$BODY_FILE" "${LABEL_ARGS[@]}"
+  ```
 
-### Applied by Maintainers
+## No-Template Fallback
 
-| Label | When to apply |
-|-------|--------------|
-| `status:approved` | Issue accepted for implementation — PRs can now be opened |
-| `priority:high` | Critical bug or urgent feature |
-| `priority:medium` | Important but not blocking |
-| `priority:low` | Nice to have |
+When the repository permits issue creation, provides no matching template, and isBlankIssuesEnabled is explicitly true, prepare a structured body with these sections:
 
----
+- problem or requested outcome;
+- reproduction or motivating example;
+- expected behavior;
+- actual behavior or current limitation;
+- environment and relevant evidence;
+- alternatives or workarounds, when applicable.
 
-## Maintainer Approval Workflow
+Publish the reviewed fallback explicitly:
 
-```
-1. New issue arrives with status:needs-review
-2. Review the issue — is it valid, clear, and in scope?
-3. If YES → add status:approved label
-4. If NO → comment with reason, close if needed
-5. Contributor can now open a PR linking this issue
+```bash
+gh issue create --repo "$HOST/$REPO" --title "$TITLE" --body "$BODY" "${LABEL_ARGS[@]}"
 ```
 
----
+If blank issues are not explicitly enabled, follow discovered contact links or stop and ask. Never publish a no-template fallback.
 
-## Decision Tree
+## Labels And Approval
 
-```
-Is it a bug?                    → Use Bug Report template
-Is it a new feature/improvement? → Use Feature Request template
-Is it a question?               → Use Discussions, NOT issues
-Is it a duplicate?              → Link to existing issue, close
-```
+Treat labels and approval gates as conditional:
 
----
+- use only labels returned by repository discovery;
+- follow contribution guidance for who may apply each label;
+- wait when repository policy requires maintainer approval before implementation;
+- do not invent a status or priority taxonomy when none is documented.
 
-## Commands
+## Questions And Discussions
 
-```bash
-# Search existing issues before creating
-gh issue list --search "keyword"
+Use Discussions only when `hasDiscussionsEnabled` is true and repository guidance routes the question there. Otherwise follow documented support/contact links or ask the user where the question belongs. Never link to another repository's Discussions page.
 
-# Create bug report
-gh issue create --template "bug_report.yml" --title "fix(scope): description"
+## Triage Decision
 
-# Create feature request
-gh issue create --template "feature_request.yml" --title "feat(scope): description"
+Before approving or closing an issue, verify:
 
-# Maintainer: approve an issue
-gh issue edit <number> --add-label "status:approved"
+- it describes a concrete bug or scoped improvement rather than an unsupported question;
+- it is not a duplicate;
+- the report contains enough evidence for an implementation decision;
+- the requested behavior is in repository scope;
+- labels and status changes follow the current repository's policy.
 
-# Maintainer: add priority
-gh issue edit <number> --add-label "priority:high"
-```
+If any point is uncertain, keep the issue in the repository's review state and request the smallest missing evidence.

package/skills/judgment-day/SKILL.md

@@ -4,13 +4,15 @@ description: "Trigger: judgment day, judgement day, dual review, adversarial rev
 license: Apache-2.0
 metadata:
   author: gentleman-programming
-  version: "1.4"
+  version: "1.7"
 ---
 
 ## Activation Contract
 
 Load this skill only when the user explicitly requests Judgment Day, Judgement Day, dual/adversarial review, or an equivalent trigger. Resolve one exact target before starting.
 
+Judgment Day is a standalone developer tool: judges run whenever asked, on any runtime, and need no review transaction, runtime identity, or delivery-receipt machinery to start. It replaces ordinary 4R as the adversarial method for that target; never run both.
+
 Judgment Day starts only when explicitly requested and replaces ordinary review for that lineage.
 
 ## Transaction Rules
@@ -25,6 +27,8 @@ Initial discovery and scoped re-judgment are separate modes.
 
 During initial discovery, run exactly once against the supplied `initial_review_tree` and return candidate rows only.
 
+Judges hold a sweep budget: one exhaustive read-only sweep per judge is the standard budget, and at most two sweeps for a full-4R-scale target (hot auth/update/security/payments paths, or more than 400 changed lines). There is no loop-until-dry mechanism; the sweep budget is the entire discovery pass.
+
 During initial discovery, do not persist state, mutate claims, launch actors, request fixes, validate fixes, or deliver anything.
 
 On controller-requested scoped re-judgment, receive only requested frozen IDs, their exact hash-bound rows, and the fix diff.
@@ -59,6 +63,8 @@ Each scoped fix returns candidate-tree and fix-diff evidence. It cannot mint aut
 
 ## Lifecycle Boundary
 
+A judgment issues no receipt and carries no delivery authority: it satisfies no commit, push, PR, or release gate. When the caller explicitly wants delivery authority for the same target, run the ordinary negotiated review lifecycle as its own step; a runtime that cannot uphold receipt guarantees loses the receipt, not the judgment.
+
 Pre-commit, pre-push, and PR gates validate approved receipts and exact typed targets with zero actors.
 Release from protected `main` may bypass receipt validation only when the tag targets the current immutable `origin/main` SHA, required CI for that exact SHA is successful, the remote head is rechecked before tag push, and no fresh risk evidence exists; otherwise release fails closed through native receipt validation.
 Major and post-incident releases require explicit extraordinary review even when fast-path checks pass.

package/skills/judgment-day/references/prompts-and-formats.md

@@ -23,6 +23,8 @@ Initial discovery and scoped re-judgment are separate modes.
 
 During initial discovery, run exactly once against the supplied `initial_review_tree` and return candidate rows only.
 
+Run one exhaustive read-only sweep — at most two sweeps for a full-4R-scale target (hot auth/update/security/payments paths, or more than 400 changed lines). Do not edit, delegate, refute, or inspect unrelated scope.
+
 During initial discovery, do not persist state, mutate claims, launch actors, request fixes, validate fixes, or deliver anything.
 
 Each candidate contains stable ID, exact location, severity, evidence class, and concrete user-impact claim. WARNING and SUGGESTION are informational. Return an empty `rows` array when clean.

package/skills/rdd-defect-workflow/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gentle-ai-rdd-defect-workflow
+description: "Trigger: RDD, receipt-driven development, review authority, receipt/lineage, correction/recovery, delivery gate/kill switch, bounded review defects. Guide work."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "1.0"
+---
+
+## Activation Contract
+
+Load when the frontmatter trigger terms apply to a defect workflow.
+
+This skill guides public collaboration. It does not grant issue approval, label, review, exception, or merge authority.
+
+## Hard Rules
+
+- Check the user-owned RDD kill switch first. When disabled, do not start receipt reviews or fabricate approval; follow ordinary policy and report `disabled/unmanaged`.
+- Require an approved issue (`status:approved`) and clean current `main` reproduction before implementation. Audit existing PRs for supersession or conflict; stop or narrow stale claims.
+- Group by causal authority invariant. Use one issue and one PR or explicit chain per independent invariant and rollback boundary. Split independent causes; never merge a superseded or conflicting authority line.
+- Inventory every operator flow claimed by the issue or PR, including entry, mode, environment, expectation, and negative controls. Require one truthful black-box bench journey per CLI or lifecycle flow, or actual runtime E2E proof when the core bench cannot represent it. Synthetic proxy coverage never proves another runtime.
+- Use CodeGraph-first impact mapping, a dedicated worktree, and behavior-first tests. Run source-mutating normalization before candidate freeze.
+- Forecast authored changes before edits. The hard limit is 400 additions plus deletions; above it, STOP for a chain or explicit maintainer-approved exception.
+- Only when RDD is enabled, bind receipts, lineage, correction, recovery, and delivery gates to the exact candidate. Keep bounded review defects in one correction transaction.
+- Require independent read-only candidate validation before publication. Validation cannot edit source or authority; findings require a new candidate.
+- Keep communication humane and evidence-based. Repository labels and workflow metadata are maintainer-owned, never evidence of contributor blame.
+
+## Decision Gates
+
+| Condition | Action |
+| --- | --- |
+| RDD disabled | Ordinary policy; `disabled/unmanaged`; no receipt or approval claim. |
+| Issue gate or reproduction fails | Wait, stop, or narrow with evidence. |
+| Invariant or rollback is independent | Separate issue and authoritative PR line. |
+| Core bench fits / does not fit | Bench journey / actual runtime E2E; never proxy. |
+| Forecast exceeds 400 lines | Chain or approved exception before edits. |
+
+## Execution Steps
+
+1. Check mode, approval, PR conflicts, and current-main reproduction.
+2. Name invariant and rollback; isolate the worktree; CodeGraph-map code, tests, evidence, docs, distribution, and registration.
+3. Inventory flows and controls; add failing tests and the smallest correction.
+4. Normalize, enforce budget, run tests, and record each flow's exact candidate, command, scenario, and result.
+5. Freeze, validate read-only, and give the verdict, evidence, and one humane next action.
+
+## Output Contract
+
+Return `rdd_mode`, `issue_pr`, `causal_invariant`, `operator_flows`, `journey_runtime_evidence`, `changed_line_budget`, `tests`, `rollback`, and `unresolved_authority_decisions`.
+
+Identify approved and superseded/conflicting authority lines; every flow, negative control, and candidate-bound proof; additions plus deletions and chain/exception; test results; independent rollback; and unresolved maintainer decisions.
+
+## References
+
+No supporting files. Current repository policy remains authoritative.