@gtrabanco/pi-agentic-workflow 0.16.0 → 0.18.0

package/dist/config/recommended.d.ts

@@ -9,6 +9,13 @@ export interface RecommendedProfile {
 /**
  * Built-in model profiles keyed by provider identifier.
  * Only these four models are ever used: nan/glm5.3, nan/glm5.3-flash,
- * nan/deepseek-v4-flash, nan/mimo-v2.5.
+ * nan/deepseek-v4-flash, nan/mimo-v2.6-flash.
+ *
+ * The judgment slots (audit-pr, product-audit, review-change, unit-lane) use
+ * the Xiaomi family for reviewer independence from the DeepSeek/GLM executors;
+ * mimo-v2.6-flash supersedes mimo-v2.5 there (same family, same 1.0B quota,
+ * OpenAI-`tools`-native, stronger on the shared coding/agentic benchmarks).
+ * Keep this list in step with the README's NaN guidance — there is no test
+ * asserting that parity, only the expectations in test/model-profiles.test.mjs.
  */
 export declare const RECOMMENDED_PROFILES: Readonly<Record<string, RecommendedProfile>>;

package/dist/config/recommended.js

@@ -3,16 +3,23 @@ export const RECOMMENDED_PROVIDERS = ["nan"];
 /**
  * Built-in model profiles keyed by provider identifier.
  * Only these four models are ever used: nan/glm5.3, nan/glm5.3-flash,
- * nan/deepseek-v4-flash, nan/mimo-v2.5.
+ * nan/deepseek-v4-flash, nan/mimo-v2.6-flash.
+ *
+ * The judgment slots (audit-pr, product-audit, review-change, unit-lane) use
+ * the Xiaomi family for reviewer independence from the DeepSeek/GLM executors;
+ * mimo-v2.6-flash supersedes mimo-v2.5 there (same family, same 1.0B quota,
+ * OpenAI-`tools`-native, stronger on the shared coding/agentic benchmarks).
+ * Keep this list in step with the README's NaN guidance — there is no test
+ * asserting that parity, only the expectations in test/model-profiles.test.mjs.
  */
 export const RECOMMENDED_PROFILES = {
     nan: {
         default: { model: ["nan/deepseek-v4-flash", "nan/glm5.3-flash"], thinking: "inherit" },
         commands: {
-            "audit-pr": { model: ["nan/mimo-v2.5", "nan/deepseek-v4-flash"], thinking: "high" },
-            "product-audit": { model: ["nan/glm5.3", "nan/mimo-v2.5", "nan/deepseek-v4-flash"], thinking: "high" },
-            "review-change": { model: ["nan/mimo-v2.5", "nan/glm5.3-flash", "nan/deepseek-v4-flash"], thinking: "high" },
-            "unit-lane": { model: ["nan/mimo-v2.5", "nan/glm5.3-flash", "nan/deepseek-v4-flash"], thinking: "high" },
+            "audit-pr": { model: ["nan/mimo-v2.6-flash", "nan/deepseek-v4-flash"], thinking: "high" },
+            "product-audit": { model: ["nan/glm5.3", "nan/mimo-v2.6-flash", "nan/deepseek-v4-flash"], thinking: "high" },
+            "review-change": { model: ["nan/mimo-v2.6-flash", "nan/glm5.3-flash", "nan/deepseek-v4-flash"], thinking: "high" },
+            "unit-lane": { model: ["nan/mimo-v2.6-flash", "nan/glm5.3-flash", "nan/deepseek-v4-flash"], thinking: "high" },
             "triage-issue": { model: ["nan/glm5.3-flash", "nan/deepseek-v4-flash"], thinking: "inherit" },
             "init-workspace": { model: ["nan/glm5.3-flash", "nan/deepseek-v4-flash"], thinking: "inherit" },
             "execute-phase": { model: ["nan/deepseek-v4-flash", "nan/glm5.3-flash"], thinking: "inherit" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 3.0.1
+version: 3.2.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -58,7 +58,7 @@ Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
 
 ## Progressive loading — bootstrap or upgrade, never both
 
-The reference allowlist is exactly the four linked paths below. Never invent or
+The reference allowlist is exactly the five linked paths below. Never invent or
 read another `references/` path. Step 0 selects exactly one route:
 
 **Hard rule for an existing Claude Code, Cursor, Copilot, or OpenCode
@@ -69,8 +69,12 @@ or portability unless the runtime platform has no named adapter at all.
 - Bare/foreign repository: read
   [bootstrap discovery](references/BOOTSTRAP_DISCOVERY.md), complete its
   interview, then read [bootstrap write](references/BOOTSTRAP_WRITE.md).
+  Both the discovery and write routes load
+  [SERENA language servers](references/SERENA.md) for stack detection.
 - Existing agentic-workflow scaffold: read [upgrade](references/UPGRADE.md)
   only. Its additive-only rule is absolute; do not replay bootstrap.
+  The upgrade route loads [SERENA language servers](references/SERENA.md)
+  for the additive provisioning step.
 - No named adapter exists for the detected runtime platform: add
   [portability](references/PORTABILITY.md) only for that fallback. Claude Code,
   Cursor, Copilot, and OpenCode are named supported adapters; a missing adapter
@@ -99,6 +103,12 @@ loads exactly upgrade and skips bootstrap plus portability.
   on its own. **The urgency label seeding is additive-only the same way:**
   create a missing `urgent`/`fix-next` label, never touch one that already
   exists (name, color, or description a project already customized).
+- **Serena convention.** `.serena/project.yml` is committed; `project.local.yml`
+  and `cache` stay local. Never write `.serena/` config without consent. LSP
+  never verifies documents — false positives happen when a file type's server
+  is not listed (markdown/yaml/json are never auto-detected), and a listed
+  server that fails to start must be removed (one failure disables every
+  server in the project). Document verification is a script's job.
 - **Never redefine the urgency label vocabulary here.** `skills/triage-issue
   /SKILL.md` is the sole owner of the `urgent`/`fix-next` names, colors, and
   apply rules — this skill only seeds those two labels into the repo; it never
@@ -178,6 +188,8 @@ OpenCode adapter does not load this fallback.
   listed as a residual when its hook API/dependency was unavailable.
   The adaptive lane conventions (unit document, triage, catalog steps, guards,
   evidence, commit formats) are written into AGENTS.md.
+- The Serena project config is provisioned (or reported as a residual with the
+  reason, and the health check ran).
 - **The closing `→ Next:` block is printed** (plus the offer to install the skills):
 
   ```

package/skills/init-workspace/references/BOOTSTRAP_DISCOVERY.md

@@ -67,4 +67,5 @@
      means Starlight). If no, leave the block commented out —
      then reports NOT-CONFIGURED instead of guessing. Never scaffold the
      website itself.
-   - **Naming conventions** and **MCP servers**, if any.
+   - **Naming conventions**, **MCP servers**, and **Serena language servers** (see
+     [SERENA](SERENA.md) for the mapping), if any.

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -21,11 +21,17 @@
    optional: an absent document means no project invariants are declared, not
    that the scaffold failed. If retained, add its documentation-map row and
    name the project's explicit architectural-decision authority.
-6. **Propagate the unit doc template.** Ensure
+7. **Propagate the unit doc template.** Ensure
    `docs/features/_TEMPLATE/SPEC.md` exists with all 13 mandatory sections.
    This is the template used when creating new unit documents.
-
-7. **Install accepted agent safety hooks.** Keep the canonical policy and
+8. **Provision the Serena project config.** Load
+   [SERENA](SERENA.md), ask consent, then: (a) append the `.gitignore`
+   block additively (skip when already present); (b) write `.serena/project.yml`
+   with the `language_servers` list for every detected language (never overwrite
+   an existing file — report it); (c) run the health check from SERENA.md and
+   record the result. If Serena is not installed, offer install or record as a
+   residual.
+9. **Install accepted agent safety hooks.** Keep the canonical policy and
    fullauto wrapper at `.agentic-workflow/hooks/`. Seed the shipped
    path-protection policy at `.agentic-workflow/path-policy.json` and its doc
    page at `.agentic-workflow/path-protection.md`, beside the hooks — the
@@ -38,10 +44,10 @@
    an unknown payload, or an existing customized hook file becomes a residual,
    never a silent overwrite. Direct merges remain blocked; do not create a
    `.automerge` exception.
-8. **Offer the workflow skills.** Propose installing them:
+10. **Offer the workflow skills.** Propose installing them:
    `npx skills add gtrabanco/agentic-workflow` (note the SSH/local-path variant if
    the source is private). Don't install without a yes.
-9. **State that reviews are self-contained; offer optional extras.** The
+11. **State that reviews are self-contained; offer optional extras.** The
    workflow ships its **own internal review pack** (`review-code`,
    `review-security`, `review-verify`, `review-debt`, `review-design`,
    `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
@@ -51,7 +57,7 @@
    under a short "Optional review extras" note so `review-change` and
    `product-audit` run them **in addition** — never as a dependency. Don't
    install anything without a yes.
-10. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
+12. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
    two capability-gated GitHub labels `triage-issue` owns and applies
    (`skills/triage-issue/SKILL.md` is the sole owner of the name/color
    vocabulary — this step only seeds it, never redefines it):
@@ -64,7 +70,7 @@
    forge is unavailable or the user declines forge setup, skip this step and
    list the two labels as a residual for the user to create manually later
    (never fail the whole scaffold on it).
-12. **Report.** List what was created, which placeholders still need human input,
+13. **Report.** List what was created, which placeholders still need human input,
    the companion skills recorded/installed, the urgency labels seeded (or
    skipped, with reason), and the next step:
    `discover-repository-state` → `/unit-lane` (or `workflow-status`) → catalog

package/skills/init-workspace/references/SERENA.md

@@ -0,0 +1,133 @@
+## Why this step exists
+
+LSP-backed navigation and verification must actually work. A project-local
+`.serena/project.yml` that pins the wrong `language_servers` silently disables
+the server, and every symbol call then times out with
+`Language server status: not initialized` (verified 2026-09-24 in this
+repository).
+
+## The convention this file owns
+
+- `.serena/project.yml` is **committed** to version control (the project's
+  config, not a dev-local override).
+- `.serena/project.local.yml` and `.serena/cache/` stay local (tool-internal
+  state).
+- The target's `.gitignore` must therefore ignore every `.serena` tree **except
+  the root `project.yml`** — the block below enforces that.
+
+## What to write into the target .gitignore
+
+When the target's `.gitignore` does not already contain the block below, append
+it (additive only — see rules below):
+
+```text
+# Ignore every .serena tree (tool-local state); version ONLY the root project
+# config. Serena's own .serena/.gitignore keeps cache and per-dev overrides local.
+**/.serena/
+!.serena/
+.serena/*
+!.serena/project.yml
+```
+
+**Rules:**
+
+- **Additive only** — append the block when it is absent.
+- If the target already ignores `.serena` wholesale (e.g. `.serena/` without
+  an `!` carve-out), **propose the narrowing** and apply it **only with consent**.
+- **Never rewrite unrelated lines.** Only touch the `.serena` block.
+- **Idempotent** — skip when the exact block (all four lines) is already
+  present.
+
+## Language servers for the detected stack
+
+Write language servers in this order: **fixed entries first** (always written,
+regardless of the target), then **detected entries** (from Step 0 signals).
+
+### Fixed entries — always written
+
+| Entry | Why always |
+|---|---|
+| `markdown` | Every scaffolded project has `docs/` and `.md` files (this workflow's own documentation is Markdown) |
+| `json` | Manifests and tool config (`package.json`, `tsconfig.json`, settings) exist in nearly every stack |
+
+### Never auto-detected rule
+
+**`markdown`, `yaml`, and `json` are never auto-detected by Serena — they must
+appear in `language_servers` explicitly, or requests for those file types fall
+back to another server and produce false positives** (e.g. TypeScript diagnostics
+on a `.yml`). Every server listed above (and `yaml` when `.yml`/`.yaml` files
+are present) is explicit-only.
+
+### Detected entries — append when present
+
+| Detected | Entry |
+|---|---|
+| `.yml` / `.yaml` files present (CI workflows, config) | `yaml` |
+| `package.json` / `tsconfig.json` (TypeScript or JavaScript) | `typescript` |
+| `pyproject.toml` / `requirements.txt` | `python` |
+| `go.mod` | `go` |
+| `Cargo.toml` | `rust` |
+| `pom.xml` / `build.gradle` | `java` |
+| `Gemfile` | `ruby` |
+| `composer.json` | `php` |
+| `CMakeLists.txt` / `Makefile` (C/C++) | `cpp` |
+| `.csproj` / `.sln` | `csharp` |
+| shell-dominant repo (`*.sh` prevalent) | `bash` |
+
+The authoritative list of valid values is Serena's own `ls_config.py`
+(`LanguageServerId`). An id Serena does not know about is silently ignored by
+Serena — **the health check below is what proves the list is correct.**
+
+## Ask first
+
+Never write `.serena/` or `.gitignore` without an explicit yes, and report
+exactly what was written. (This matches the skill's existing installation-consent
+rule.)
+
+## Health check — fail closed at the claim
+
+After activation, confirm **each listed server** initialised by asking Serena
+for the project status and verifying `Language server status: initialized` for
+every language in `language_servers`. If a server did not initialise, the
+check names the offending entry. Removing a failing entry (per the startup
+rule below) is the correct remediation — never leave a dead entry in the file.
+**Never claim LSP evidence for a run whose server never started.**
+
+### Startup rule (critical)
+
+> **A server that fails to start must not stay listed.** One failing entry
+> disables the whole language-server manager — every symbol call for the
+> project then fails with `Language server manager is not initialized`.
+> After writing the config, the health check must confirm **every** listed
+> server started; any entry that fails is removed from `language_servers`
+> and recorded as a residual with its exact error (e.g. `markdown`: marksman
+> needs the system `libicu` package).
+
+## When a server is missing or fails
+
+`markdown`, `yaml`, and `json` servers exist but are explicit-only and
+experimental: they must be listed by hand or requests fall back and produce
+false positives.
+
+- **Missing (not listed)** → fallback server answers → false positives for that
+  file type (e.g. TypeScript diagnostics on a `.yml`).
+- **Failing (listed but broken)** → whole manager down → every symbol call
+  fails with `Language server manager is not initialized`. Remediation: remove
+  the entry from `language_servers` and record the residual (e.g. `markdown`:
+  marksman needs the system `libicu` package).
+
+Document verification (schema rules like required sections/columns) stays a
+deterministic script's job regardless — LSP serves navigation and diagnostics,
+not our document grammar. `node`+`npm` are required for json/yaml; `libicu` is
+required for marksman.
+
+## Tool install is a different step
+
+This file owns the **project config**, not the tool. If Serena is not installed,
+offer the install (ask-first; `uv`/`uvx` preferred, `pipx` fallback) or record
+it as a residual. The install half is tracked by #219.
+
+## Degraded path
+
+Serena unavailable → warn once, continue, and record the absence in the unit's
+evidence. **Never block a run on it.**

package/skills/init-workspace/references/UPGRADE.md

@@ -4,7 +4,7 @@ Entered when Step 0 finds an existing **agentic-workflow scaffold** (not a
 bare or foreign repo). Bootstrap mode (the Process section above) never
 engages here — upgrade mode reuses the same discovery + interview machinery,
 scoped to **only the blocks the current template has that this project
-lacks**. Eight ordered steps:
+lacks**. Nine ordered steps:
 
 1. **Locate the current template.** Fetch the current `template/` the same
    way bootstrap does — `npx degit gtrabanco/agentic-workflow/template <temp-dir>`
@@ -91,7 +91,15 @@ lacks**. Eight ordered steps:
    never touch a label that already exists (additive-only, same never-clobber
    rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
    project recolored or redescribed is left exactly as-is).
-8. **Report + hand off.** Summarize blocks added, filled, and skipped
+
+8. **Provision the Serena project config, additively only (Refs #219).** Load
+   [SERENA](SERENA.md). Append the `.gitignore` block only if the target
+   does not already contain it. Write `.serena/project.yml` only if it is
+   absent — never touch an existing one. Report what was skipped and why.
+   Run the health check and record the result. If Serena is not installed,
+   offer install or record as a residual. This step is additive-only; it
+   never rewrites or deletes, consistent with upgrade mode's rule.
+9. **Report + hand off.** Summarize blocks added, filled, and skipped
    (residuals), the legacy `CLAUDE.md` outcome (folded items and removed, or kept
    with the reason), the urgency labels seeded (or already present), then print the
    recommendation to run `product-audit` next to see which newly-available

package/skills/log-session/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: log-session
 user-invocable: true
-version: 2.2.1
+version: 2.3.0
 argument-hint: "[note to prepend to the entry]"
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -23,8 +23,10 @@ Capture the *why* and the *what-next* of a working session — the context that
 git history alone never records. A commit says what changed; a session log says
 what you were trying to do, what you decided, and where to resume.
 
-Deliberately cheap (`sonnet`/`medium`): this is structured summarization, not
-judgment. It must never reach for an expensive model.
+Deliberately cheap (`qwen3.6`/`reasoning_config: none` — unlimited; the NaN
+cluster models carry **no token counter**, so this skill pays in bytes, not
+quota): structured summarization, not judgment. It must never reach for an
+expensive model.
 
 ## Turn contract — verify before ending the turn
 
@@ -124,8 +126,9 @@ the HEAD sha and start time at session open.
 
 ## Guardrails
 
-- **Never use an expensive model for this.** It's summarization; `sonnet` is the
-  ceiling, and the hooks do the free mechanical version.
+- **Never use an expensive model for this.** It's summarization; `qwen3.6`
+  (`reasoning_config: none` → zero thinking tokens) is the natural ceiling on
+  the cluster plan, and the hooks do the free mechanical version.
 - **Don't invent facts.** Decisions and next steps come from the actual session
   (your context + git), not plausible-sounding filler. If a section has nothing
   real, omit its line rather than padding.
@@ -147,8 +150,10 @@ enables:
   (Process step 1's no-marker path).
 - **No `/clear`** — read it as your agent's context-reset / new-conversation
   equivalent, in the triggers and in the closing block alike.
-- **No per-skill `model:`/`effort:`** — the intent stands: use a **cheap**
-  model for this. It's summarization, never judgment.
+- **No per-skill `model:`/`effort:`** — the intent stands: use the cheapest
+  available model for this. It's summarization, never judgment. On NaN the
+  cluster models (qwen3.6, gemma4) carry no token counter — set
+  `reasoning_config: none` so the append pays zero thinking tokens.
 
 ## Relationship to other skills