gentle-pi 0.4.0 → 0.4.1

package/README.md

@@ -45,10 +45,10 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 
 | Capability                     | What it does                                                                                                                                  |
 | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| **el Gentleman persona**       | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default.               |
-| **Rose startup intro**         | Adds a pink rose fade-in, compact project/runtime panel, and visible startup collaboration credit for @aporcelli's `pi-gentle-startup` ideas. |
+| **el Gentleman persona**       | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default; neutral mode is saved globally with project overrides. |
+| **Configurable startup intro** | Adds a rose/text-logo startup intro, compact runtime panel, color presets, and commands to hide or show the decorative parts.                  |
 | **Work routing discipline**    | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec.                          |
-| **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, and `archive`.              |
+| **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `onboard`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, `sync`, and `archive`. |
 | **Lazy SDD preflight**         | Asks once per session for SDD mode, artifact store, PR chaining strategy, and review budget before the first SDD flow.                        |
 | **Subagent orchestration**     | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context.                             |
 | **Strict TDD support**         | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence.                   |
@@ -56,7 +56,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents.                                                       |
 | **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill.          |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
-| **Shell safety**               | Blocks destructive shell commands and asks for confirmation for sensitive operations.                                                         |
+| **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Install
 
@@ -88,10 +88,12 @@ pi
 
 ```text
 /gentle-ai:status          Check package, SDD assets, OpenSpec, and global model config.
+/gentle-ai:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
 /gentle-ai:sdd-preflight   Run or reuse the session SDD preflight explicitly.
 /sdd-init                  Create or refresh openspec/config.yaml.
 /gentle:models             Assign global model/effort routing to SDD/custom agents.
 /gentle:persona            Switch between gentleman and neutral persona modes.
+/gentle:banner             Configure startup rose, text logo, and color preset.
 ```
 
 Typical flow:
@@ -315,13 +317,19 @@ Delegation contract:
 | `gentleman` | Senior architect, teacher, direct technical feedback, Rioplatense Spanish/voseo when the user writes Spanish. |
 | `neutral`   | Same discipline, warmer professional language, no regional expression.                                        |
 
-Saved at:
+Saved globally at:
+
+```text
+~/.pi/gentle-ai/persona.json
+```
+
+A project can still override the global default with:
 
 ```text
 .pi/gentle-ai/persona.json
 ```
 
-Run `/reload` or start a new Pi session after switching persona.
+`/gentle:persona` writes the global config and updates an existing project override when one is present, so the current project does not stay stale. Run `/reload` or start a new Pi session after switching persona.
 
 ## Model and effort assignment
 
@@ -376,8 +384,9 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | Command                          | What it does                                                        |
 | -------------------------------- | ------------------------------------------------------------------- |
 | `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
-| `/gentle:models`                 | Opens global model + effort assignment UI.                          |
-| `/gentle:persona`                | Switches persona mode.                                              |
+| `/gentle-ai:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
+| `/gentle:models`                 | Opens global model + effort assignment UI. Press `x` to export and `r` to restore saved routing. |
+| `/gentle:persona`                | Switches global persona mode, with project override support.        |
 | `/gentle:banner`                 | Configures startup banner rose, text logo, and color preset.        |
 | `/gentle:toggle-rose`            | Toggles the startup rose.                                           |
 | `/gentle:toggle-text-logo`       | Toggles the startup text logo.                                      |
@@ -385,7 +394,6 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
 | `/gentle-ai:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
 | `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
-
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
 
 Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
@@ -407,6 +415,10 @@ Compatibility aliases:
 /gentleman:models
 /gentle-ai:persona
 /gentleman:persona
+/gentle-ai:banner
+/gentle-ai:toggle-rose
+/gentle-ai:toggle-text-logo
+/gentle-ai:banner-color
 ```
 
 ## Included skills
@@ -443,10 +455,10 @@ Memory contract for SDD delegation:
 
 | Path                           | Purpose                                                                                                    |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `extensions/gentle-ai.ts`      | Injects identity, ensures global SDD assets, registers commands, applies model config, and protects shell execution. |
-| `extensions/startup-banner.ts` | Shows the rose startup intro, compact runtime panel, and collaboration credit.                             |
+| `extensions/gentle-ai.ts`      | Injects identity, auto-refreshes global SDD assets, registers commands, applies model/persona config, exports/restores model routing, and enforces runtime safety. |
+| `extensions/startup-banner.ts` | Shows and configures the startup intro, color presets, compact runtime panel, and collaboration credit.     |
 | `extensions/sdd-init.ts`       | Registers `/sdd-init` for OpenSpec initialization.                                                         |
-| `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills.                                               |
+| `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills and closes file watchers on shutdown.          |
 | `assets/orchestrator.md`       | Parent-session orchestration contract.                                                                     |
 | `assets/agents/`               | SDD agents installed as global Pi runtime assets.                                                          |
 | `assets/chains/`               | SDD chains installed as global Pi runtime assets.                                                          |

package/assets/orchestrator.md

@@ -31,7 +31,9 @@ User-facing conversation should stay in the user's language and follow the curre
 
 Subagent-facing prompts should be written in English by default, even when the user speaks Spanish. Translate the user's request into concise English before delegation. This keeps token usage lower and gives built-in/project subagents a consistent operating language without changing the user-facing persona.
 
-Generated artifacts — whether by the parent inline or by subagents — (code, UI copy, comments, identifiers, commit messages, filenames, PR descriptions) default to English, regardless of the user's conversation language. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
+Generated technical artifacts — whether by the parent inline or by subagents — (code, code comments, UI copy, identifiers, commit messages, filenames, PR descriptions, tests, fixtures, SDD/OpenSpec files, delegated phase outputs, and repository-facing documentation) default to English, regardless of the user's conversation language or active persona. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
+
+Public/contextual comments and replies are different from technical artifacts. When using `comment-writer` or drafting a human-facing GitHub, PR review, Slack, Discord, or async comment, write in the target context language by default. Spanish issue/thread -> Spanish comment. English thread -> English comment. Mixed context -> target message language. Explicit user language or tone override wins. Spanish comments default to neutral/professional Spanish unless the user or target context clearly calls for regional tone.
 
 Exceptions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/scripts/verify-package-files.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 const root = join(fileURLToPath(new URL("..", import.meta.url)));
 
 const requiredPaths = [
+  "assets/orchestrator.md",
   "assets/agents/sdd-apply.md",
   "assets/agents/sdd-archive.md",
   "assets/agents/sdd-design.md",
@@ -30,7 +31,15 @@ const requiredPaths = [
   "prompts/gis.md",
   "prompts/gpr.md",
   "prompts/gwr.md",
+  "skills/branch-pr/SKILL.md",
+  "skills/chained-pr/SKILL.md",
+  "skills/cognitive-doc-design/SKILL.md",
+  "skills/comment-writer/SKILL.md",
   "skills/gentle-ai/SKILL.md",
+  "skills/issue-creation/SKILL.md",
+  "skills/judgment-day/SKILL.md",
+  "skills/release/SKILL.md",
+  "skills/skill-registry/SKILL.md",
   "skills/work-unit-commits/SKILL.md",
 ];
 

package/skills/comment-writer/SKILL.md

@@ -27,7 +27,7 @@ Use it for:
 | Keep it short | Prefer 1 to 3 short paragraphs or a tight bullet list. |
 | Explain why | Give the technical reason when asking for a change. |
 | Avoid pile-ons | Comment on the highest-value issue, not every tiny preference. |
-| Match thread language | Write in the thread/user language and follow the active persona/tone. Do not force regional Spanish; use voseo only when the active persona or existing thread does. |
+| Match target context language | Write in the target context language by default: Spanish issue/thread -> Spanish comment, English issue/thread -> English comment, mixed context -> target message language. If the user explicitly requests a language or tone, follow that request. Do not use the active persona as the source of truth for public comments. For Spanish comments, use neutral/professional Spanish by default unless the user or target context clearly calls for regional tone. |
 | No em dashes | Use commas, periods, or parentheses instead. |
 
 ## Comment Formula
@@ -45,25 +45,25 @@ Use it for:
 ### Request change
 
 ```markdown
-Buenísimo el enfoque. Acá separaría este cambio en otro commit porque mezcla la validación con el wiring de UI.
+Good approach overall. I'd split this into a separate commit because it mixes validation logic with UI wiring.
 
-Eso le baja carga al reviewer y hace que el rollback sea más claro si falla la integración.
+That keeps the reviewer's focus narrower and makes rollback cleaner if the integration fails.
 ```
 
 ### Approve with a note
 
 ```markdown
-Está bien encaminado y el scope se entiende rápido.
+Approved. The scope is clear and the change is well-contained.
 
-Dejo aprobado. Para el próximo PR, agregá el link al anterior y al siguiente así la cadena queda navegable.
+For the next PR, add links to the previous and following PRs so the chain stays navigable.
 ```
 
 ### Ask for split
 
 ```markdown
-Este PR supera el presupuesto de 400 líneas cambiadas, así que necesitamos dividirlo o justificar `size:exception`.
+This PR exceeds the 400-line budget, so we need to split it or justify `size:exception`.
 
-Mi sugerencia: primero foundation + tests, después integración, después docs. Así cada review tiene inicio y fin claros.
+Suggested order: foundation + tests first, then integration, then docs. That gives each review a clear start and end.
 ```
 
 ## Commands

package/tests/artifact-language.test.ts

@@ -49,7 +49,14 @@ test("orchestrator keeps conversation language separate from generated artifact
 	);
 	assert.match(
 		orchestrator,
-		/Generated artifacts[\s\S]*default to English, regardless of the user's conversation language/,
+		/Generated technical artifacts[\s\S]*default to English, regardless of the user's conversation language or active persona/,
+	);
+	for (const artifactScope of ["code comments", "tests", "fixtures", "delegated phase outputs"]) {
+		assert.match(orchestrator, new RegExp(artifactScope));
+	}
+	assert.match(
+		orchestrator,
+		/Public\/contextual comments and replies[\s\S]*target context language by default/,
 	);
 });
 
@@ -89,3 +96,35 @@ test("persistent harness prompt assets do not hardcode Spanish SDD artifact copy
 
 	assert.deepEqual(failures, []);
 });
+
+test("comment-writer is context-reactive and neutral by default for Spanish comments", async () => {
+	const skill = await readFile(join(ROOT, "skills/comment-writer/SKILL.md"), "utf8");
+
+	for (const required of [
+		"target context language",
+		"explicitly requests a language",
+		"neutral/professional Spanish by default",
+	]) {
+		assert.match(skill, new RegExp(required.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+	}
+
+	for (const regionalDefault of [
+		/\bAcá\b/,
+		/\bagregá\b/,
+		/\bpodés\b/,
+		/\btenés\b/,
+		/\bfijate\b/,
+		/\bdale\b/,
+		/\bquerés\b/i,
+	]) {
+		assert.doesNotMatch(skill, regionalDefault);
+	}
+
+	for (const englishExample of [
+		"Good approach overall",
+		"Approved. The scope is clear",
+		"This PR exceeds the 400-line budget",
+	]) {
+		assert.match(skill, new RegExp(englishExample.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+	}
+});