@caupulican/pi-adaptative 0.84.1 → 0.85.3

package/dist/bundled-resources/runtimes/pi-shell-engine/exec.py

@@ -10,17 +10,20 @@ import io
 import os
 import subprocess
 import threading
+import time
 from typing import BinaryIO
 
+from arithmetic import ArithmeticError, compile_arithmetic, evaluate_arithmetic
 import nodes
 import parser as parser_module
 import proc
 import tokens as tokens_module
 from context import RUNNER_BUILTINS, STATE_BUILTINS, BuiltinContext, ExecContext
-from errors import ShellExit, UnsupportedConstruct
+from errors import LoopBreak, LoopContinue, LoopControl, ShellExit, UnsupportedConstruct
 from state import ShellState
 
 DEVNULL = os.devnull
+MAX_LOOP_ITERATIONS = 1_000_000
 
 
 class _Redirected:
@@ -344,7 +347,7 @@ def _run_pipeline_elements(elements: list, ctx: ExecContext) -> int:
                 try:
                     # Pipeline stages are subshell-like: state mutations belong to the stage,
                     # never to the parent command context or a sibling stage.
-                    stage_ctx = _sub_ctx(ctx, ctx.state.copy(), sin, sout, stderr_base)
+                    stage_ctx = _sub_ctx(ctx, ctx.state.copy(), sin, sout, stderr_base, loop_depth=0)
                     results[idx] = _dispatch_element(elements[idx], stage_ctx, sin, sout, stderr_base, is_pipeline=True)
                 except UnsupportedConstruct as exc:
                     # A structured refusal from an inline stage means the WHOLE command
@@ -356,6 +359,10 @@ def _run_pipeline_elements(elements: list, ctx: ExecContext) -> int:
                     results[idx] = 1
                 except ShellExit as exc:
                     results[idx] = exc.exit_code
+                except LoopControl:
+                    # A pipeline stage is a subshell boundary. Loop control in that
+                    # stage cannot alter an enclosing loop in the parent context.
+                    results[idx] = 0
                 except BaseException as exc:  # noqa: BLE001 - any other stage failure must not crash the engine
                     # Any OTHER exception is a real per-stage failure, not a refusal: it
                     # gets a named, actionable one-line message on the merged sink (never
@@ -487,6 +494,8 @@ def _dispatch_element(
         return _execute_subshell(element, ctx, stdin_stream, stdout_stream, stderr_stream)
     if isinstance(element, nodes.BraceGroup):
         return _execute_brace_group(element, ctx, stdin_stream, stdout_stream, stderr_stream)
+    if isinstance(element, (nodes.ForCommand, nodes.ArithmeticForCommand)):
+        return _execute_for_command(element, ctx, stdin_stream, stdout_stream, stderr_stream)
     if isinstance(element, nodes.SimpleCommand):
         return _dispatch_simple_command(element, ctx, stdin_stream, stdout_stream, stderr_stream)
     raise UnsupportedConstruct("malformed-syntax", f"unrecognized pipeline element {type(element)!r}")
@@ -498,6 +507,8 @@ def _sub_ctx(
     stdin_stream: BinaryIO | int,
     stdout_stream: BinaryIO | int,
     stderr_stream: BinaryIO | int,
+    *,
+    loop_depth: int | None = None,
 ) -> ExecContext:
     return ExecContext(
         state=state,
@@ -508,11 +519,12 @@ def _sub_ctx(
         builtins=ctx.builtins,
         deadline=ctx.deadline,
         stderr=stderr_stream,
+        loop_depth=ctx.loop_depth if loop_depth is None else loop_depth,
     )
 
 
-def _execute_redirected_group(
-    node: nodes.Subshell | nodes.BraceGroup,
+def _execute_redirected_compound(
+    node: nodes.Subshell | nodes.BraceGroup | nodes.ForCommand | nodes.ArithmeticForCommand,
     ctx: ExecContext,
     stdin_stream,
     stdout_stream,
@@ -526,8 +538,18 @@ def _execute_redirected_group(
             node.redirects, ctx, stdin_stream, stdout_stream, stderr_stream, tracker
         )
         state = ctx.state.copy() if isolated else ctx.state
-        inner_ctx = _sub_ctx(ctx, state, r_in, r_out, r_err)
+        inner_ctx = _sub_ctx(
+            ctx,
+            state,
+            r_in,
+            r_out,
+            r_err,
+            loop_depth=0 if isolated else ctx.loop_depth,
+        )
         try:
+            if isinstance(node, (nodes.ForCommand, nodes.ArithmeticForCommand)):
+                inner_ctx.loop_depth += 1
+                return _execute_loop(node, inner_ctx)
             return execute(node.body, inner_ctx)
         except ShellExit as exc:
             if isolated:
@@ -538,17 +560,89 @@ def _execute_redirected_group(
 
 
 def _execute_subshell(node: nodes.Subshell, ctx: ExecContext, stdin_stream, stdout_stream, stderr_stream) -> int:
-    return _execute_redirected_group(
+    return _execute_redirected_compound(
         node, ctx, stdin_stream, stdout_stream, stderr_stream, isolated=True
     )
 
 
 def _execute_brace_group(node: nodes.BraceGroup, ctx: ExecContext, stdin_stream, stdout_stream, stderr_stream) -> int:
-    return _execute_redirected_group(
+    return _execute_redirected_compound(
+        node, ctx, stdin_stream, stdout_stream, stderr_stream, isolated=False
+    )
+
+
+def _execute_for_command(
+    node: nodes.ForCommand | nodes.ArithmeticForCommand,
+    ctx: ExecContext,
+    stdin_stream,
+    stdout_stream,
+    stderr_stream,
+) -> int:
+    return _execute_redirected_compound(
         node, ctx, stdin_stream, stdout_stream, stderr_stream, isolated=False
     )
 
 
+def _check_loop_budget(ctx: ExecContext, iteration: int) -> None:
+    if ctx.deadline is not None and time.monotonic() >= ctx.deadline:
+        raise ShellExit(124)
+    if iteration >= MAX_LOOP_ITERATIONS:
+        _write_merged(
+            _merged_sink(ctx),
+            f"for: iteration limit ({MAX_LOOP_ITERATIONS}) exceeded\n".encode("utf-8"),
+            ctx,
+        )
+        raise ShellExit(124)
+
+
+def _execute_loop_body(body: nodes.CommandList, ctx: ExecContext) -> tuple[int, str | None]:
+    try:
+        return execute(body, ctx), None
+    except LoopBreak as exc:
+        if exc.levels > 1:
+            raise LoopBreak(exc.levels - 1) from None
+        return 0, "break"
+    except LoopContinue as exc:
+        if exc.levels > 1:
+            raise LoopContinue(exc.levels - 1) from None
+        return 0, "continue"
+
+
+def _execute_loop(node: nodes.ForCommand | nodes.ArithmeticForCommand, ctx: ExecContext) -> int:
+    if isinstance(node, nodes.ForCommand):
+        values: list[str] = []
+        for item in node.items:
+            values.extend(ctx.expand_word(item, ctx))
+
+        exit_code = 0
+        for iteration, value in enumerate(values):
+            _check_loop_budget(ctx, iteration)
+            ctx.state.setenv(node.name, value)
+            exit_code, action = _execute_loop_body(node.body, ctx)
+            if action == "break":
+                return exit_code
+        return exit_code
+
+    try:
+        initializer = compile_arithmetic(node.initializer)
+        condition = compile_arithmetic(node.condition)
+        update = compile_arithmetic(node.update)
+        evaluate_arithmetic(initializer, ctx.state)
+        exit_code = 0
+        iteration = 0
+        while condition is None or evaluate_arithmetic(condition, ctx.state) != 0:
+            _check_loop_budget(ctx, iteration)
+            iteration += 1
+            exit_code, action = _execute_loop_body(node.body, ctx)
+            if action == "break":
+                return exit_code
+            evaluate_arithmetic(update, ctx.state)
+        return exit_code
+    except ArithmeticError as exc:
+        _write_merged(_merged_sink(ctx), f"bash: arithmetic: {exc}\n".encode("utf-8"), ctx)
+        return 1
+
+
 def _dispatch_simple_command(
     command: nodes.SimpleCommand,
     ctx: ExecContext,
@@ -577,7 +671,7 @@ def _dispatch_simple_command(
         name = argv[0]
 
         if name in STATE_BUILTINS:
-            return _run_state_builtin(name, argv, ctx, r_out)
+            return _run_state_builtin(name, argv, ctx, r_out, r_err)
 
         if name in RUNNER_BUILTINS:
             return _run_xargs(argv, ctx, r_in, r_out)
@@ -621,17 +715,46 @@ def _as_stream(fd_or_stream: BinaryIO | int, mode: str) -> BinaryIO:
     return fd_or_stream
 
 
-def _run_state_builtin(name: str, argv: list[str], ctx: ExecContext, out_stream: BinaryIO | int) -> int:
+def _run_state_builtin(
+    name: str,
+    argv: list[str],
+    ctx: ExecContext,
+    out_stream: BinaryIO | int,
+    error_stream: BinaryIO | int | None = None,
+) -> int:
+    diagnostic_stream = error_stream if error_stream is not None else out_stream
+    if name in ("break", "continue"):
+        if len(argv) > 2:
+            _write_merged(diagnostic_stream, f"{name}: too many arguments\n".encode("utf-8"), ctx)
+            return 1
+        try:
+            levels = int(argv[1], 10) if len(argv) == 2 else 1
+        except ValueError:
+            _write_merged(diagnostic_stream, f"{name}: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
+            return 1
+        if levels <= 0:
+            _write_merged(diagnostic_stream, f"{name}: loop count must be positive\n".encode("utf-8"), ctx)
+            return 1
+        if ctx.loop_depth == 0:
+            _write_merged(
+                diagnostic_stream,
+                f"bash: {name}: only meaningful in a 'for', 'while', or 'until' loop\n".encode("utf-8"),
+                ctx,
+            )
+            return 0
+        control = LoopBreak if name == "break" else LoopContinue
+        raise control(min(levels, ctx.loop_depth))
+
     if name == "exit":
         if len(argv) > 2:
-            _write_merged(out_stream, b"exit: too many arguments\n", ctx)
+            _write_merged(diagnostic_stream, b"exit: too many arguments\n", ctx)
             raise ShellExit(1)
         if len(argv) == 1:
             raise ShellExit(ctx.state.last_exit_code)
         try:
             exit_code = int(argv[1], 10)
         except ValueError:
-            _write_merged(out_stream, f"exit: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
+            _write_merged(diagnostic_stream, f"exit: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
             raise ShellExit(2)
         raise ShellExit(exit_code & 0xFF)
 
@@ -641,16 +764,16 @@ def _run_state_builtin(name: str, argv: list[str], ctx: ExecContext, out_stream:
         if print_new_cwd:
             oldpwd = ctx.state.env.get("OLDPWD")
             if not oldpwd:
-                _write_merged(out_stream, b"cd: OLDPWD not set\n", ctx)
+                _write_merged(diagnostic_stream, b"cd: OLDPWD not set\n", ctx)
                 return 1
             target = oldpwd
         if target is None:
-            _write_merged(out_stream, b"cd: HOME not set\n", ctx)
+            _write_merged(diagnostic_stream, b"cd: HOME not set\n", ctx)
             return 1
         try:
             ctx.state.chdir(target)
         except FileNotFoundError:
-            _write_merged(out_stream, f"cd: {target}: No such file or directory\n".encode("utf-8"), ctx)
+            _write_merged(diagnostic_stream, f"cd: {target}: No such file or directory\n".encode("utf-8"), ctx)
             return 1
         if print_new_cwd:
             _write_merged(out_stream, f"{ctx.state.cwd}\n".encode("utf-8"), ctx)

package/dist/bundled-resources/runtimes/pi-shell-engine/nodes.py

@@ -1,4 +1,4 @@
-"""Frozen AST dataclasses for the pi shell engine: word segments + command structure.
+"""AST dataclasses for the pi shell engine: word segments + command structure.
 
 Transcribed verbatim from windows-shell-workpackages-2026-07-19.md §1.4. Type tags for
 tests come from `type(node).__name__`; do NOT add a `kind` field to any node.
@@ -95,7 +95,28 @@ class BraceGroup:
     redirects: list["Redirect"]
 
 
-PipelineElement = SimpleCommand | Subshell | BraceGroup
+@dataclass
+class ForCommand:
+    """POSIX word-list loop, including the omitted-``in`` positional form."""
+
+    name: str
+    items: list["Word"]
+    body: "CommandList"
+    redirects: list["Redirect"]
+
+
+@dataclass
+class ArithmeticForCommand:
+    """Bash arithmetic loop: ``for ((init; condition; update)); do ...; done``."""
+
+    initializer: str
+    condition: str
+    update: str
+    body: "CommandList"
+    redirects: list["Redirect"]
+
+
+PipelineElement = SimpleCommand | Subshell | BraceGroup | ForCommand | ArithmeticForCommand
 
 
 @dataclass

package/dist/bundled-resources/runtimes/pi-shell-engine/parser.py

@@ -13,9 +13,11 @@ import re
 from errors import UnsupportedConstruct
 from nodes import (
     AndOr,
+    ArithmeticForCommand,
     BraceGroup,
     CommandList,
     DQ,
+    ForCommand,
     Lit,
     Pipeline,
     PipelineElement,
@@ -28,11 +30,12 @@ from nodes import (
 from tokens import Token
 
 _ASSIGNMENT_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.DOTALL)
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 _EXTGLOB_RE = re.compile(r"[@!?*+]\(")
 _BRACE_EXPANSION_RE = re.compile(r"\{[^{}]*,[^{}]*\}")
 
 _JOB_CONTROL_WORDS = {"fg", "bg", "jobs", "wait", "disown"}
-_CONTROL_FLOW_WORDS = {"if", "for", "while", "until", "case", "select"}
+_CONTROL_FLOW_WORDS = {"if", "while", "until", "case", "select"}
 _ARITHMETIC_WORDS = {"let"}
 _UNSUPPORTED_BUILTIN_WORDS = {"eval", "source", ".", "alias", "trap", "set", "shopt", "read", "declare", "local"}
 _NESTED_SHELL_WORDS = {"bash", "sh", "zsh", "fish", "cmd", "powershell", "pwsh", "wsl"}
@@ -124,26 +127,47 @@ class _Parser:
         tok = self.peek()
         return tok is not None and tok.kind == "OP" and tok.text == text
 
+    def at_unquoted_word(self, text: str) -> bool:
+        tok = self.peek()
+        return (
+            tok is not None
+            and tok.kind == "WORD"
+            and tok.segments is not None
+            and len(tok.segments) == 1
+            and isinstance(tok.segments[0], Raw)
+            and tok.segments[0].text == text
+        )
+
+    def _at_stop(self, stop_texts: frozenset[str], stop_words: frozenset[str]) -> bool:
+        tok = self.peek()
+        if tok is None:
+            return True
+        if tok.kind == "OP":
+            return tok.text in stop_texts
+        return any(self.at_unquoted_word(word) for word in stop_words)
+
     def _skip_seps(self) -> None:
         while self.at_op(";") or self.at_op("\n"):
             self.advance()
 
-    def parse_command_list(self, stop_texts: frozenset[str]) -> CommandList:
+    def parse_command_list(
+        self, stop_texts: frozenset[str], stop_words: frozenset[str] = frozenset()
+    ) -> CommandList:
         entries = []
         separators: list[str] = []
         self._skip_seps()
         while True:
-            tok = self.peek()
-            if tok is None or (tok.kind == "OP" and tok.text in stop_texts):
+            if self._at_stop(stop_texts, stop_words):
                 break
             entries.append(self.parse_and_or())
             if self.at_op("&"):
                 raise UnsupportedConstruct(
                     "job-control", "Background execution ('&') is not supported; run commands synchronously."
                 )
-            tok = self.peek()
-            if tok is None or (tok.kind == "OP" and tok.text in stop_texts):
+            if self._at_stop(stop_texts, stop_words):
                 break
+            tok = self.peek()
+            assert tok is not None
             if tok.kind == "OP" and tok.text in (";", "\n"):
                 separators.append(self.advance().text)  # type: ignore[arg-type]
                 self._skip_seps()
@@ -194,6 +218,13 @@ class _Parser:
             self.advance()
             redirects = self._parse_redirects()
             return BraceGroup(body=body, redirects=redirects)
+        if self.at_unquoted_word("for"):
+            return self.parse_for_command()
+        if self.peek() is not None and self.peek().kind == "ARITH":
+            raise UnsupportedConstruct(
+                "arithmetic-expansion",
+                "Arithmetic commands '((...))' are supported only as a for-loop header.",
+            )
         command = self.parse_simple_command()
         if not command.assignments and not command.words and not command.redirects:
             # A fully empty SimpleCommand reached as a pipeline element means a missing
@@ -204,6 +235,103 @@ class _Parser:
             )
         return command
 
+    def _parse_for_body(self) -> CommandList:
+        if not (self.at_op(";") or self.at_op("\n")):
+            raise UnsupportedConstruct(
+                "malformed-syntax", "A for loop requires ';' or a newline before 'do'."
+            )
+        self._skip_seps()
+        if not self.at_unquoted_word("do"):
+            raise UnsupportedConstruct("malformed-syntax", "A for loop is missing its 'do' keyword.")
+        self.advance()
+
+        body = self.parse_command_list(frozenset(), frozenset({"done"}))
+        if not self.at_unquoted_word("done"):
+            raise UnsupportedConstruct("malformed-syntax", "A for loop is missing its closing 'done' keyword.")
+        if not body.entries:
+            raise UnsupportedConstruct("malformed-syntax", "A for loop requires at least one command in its body.")
+        self.advance()
+        return body
+
+    @staticmethod
+    def _split_arithmetic_header(header: str) -> tuple[str, str, str]:
+        parts: list[str] = []
+        start = 0
+        depth = 0
+        for index, char in enumerate(header):
+            if char == "(":
+                depth += 1
+            elif char == ")":
+                depth -= 1
+                if depth < 0:
+                    raise UnsupportedConstruct(
+                        "malformed-syntax", "Arithmetic for header contains an unmatched ')'."
+                    )
+            elif char == ";" and depth == 0:
+                parts.append(header[start:index].strip())
+                start = index + 1
+        if depth != 0:
+            raise UnsupportedConstruct(
+                "malformed-syntax", "Arithmetic for header contains unbalanced parentheses."
+            )
+        parts.append(header[start:].strip())
+        if len(parts) != 3:
+            raise UnsupportedConstruct(
+                "malformed-syntax",
+                "An arithmetic for loop requires exactly 'initializer; condition; update'.",
+            )
+        return parts[0], parts[1], parts[2]
+
+    def parse_for_command(self) -> ForCommand | ArithmeticForCommand:
+        self.advance()  # `for`
+        arithmetic = self.peek()
+        if arithmetic is not None and arithmetic.kind == "ARITH":
+            self.advance()
+            initializer, condition, update = self._split_arithmetic_header(arithmetic.text or "")
+            body = self._parse_for_body()
+            return ArithmeticForCommand(
+                initializer=initializer,
+                condition=condition,
+                update=update,
+                body=body,
+                redirects=self._parse_redirects(),
+            )
+
+        variable = self.peek()
+        variable_name = (
+            variable.segments[0].text
+            if variable is not None
+            and variable.kind == "WORD"
+            and variable.segments is not None
+            and len(variable.segments) == 1
+            and isinstance(variable.segments[0], Raw)
+            else ""
+        )
+        if not _IDENTIFIER_RE.fullmatch(variable_name):
+            raise UnsupportedConstruct(
+                "malformed-syntax", "A for loop requires an unquoted shell variable name after 'for'."
+            )
+        self.advance()
+        items: list[Word] = []
+        if self.at_unquoted_word("in"):
+            self.advance()
+            while True:
+                tok = self.peek()
+                if tok is None or tok.kind == "OP":
+                    break
+                if tok.kind != "WORD":
+                    raise UnsupportedConstruct(
+                        "malformed-syntax", "Unexpected token in a for loop word list."
+                    )
+                items.append(Word(segments=tok.segments or []))
+                self.advance()
+        elif not (self.at_op(";") or self.at_op("\n")):
+            raise UnsupportedConstruct(
+                "malformed-syntax", "A for loop requires 'in values' or ';' after its variable name."
+            )
+        body = self._parse_for_body()
+        return ForCommand(name=variable_name, items=items, body=body, redirects=self._parse_redirects())
+
     def _parse_redirects(self) -> list[Redirect]:
         redirects: list[Redirect] = []
         while True:

package/dist/bundled-resources/runtimes/pi-shell-engine/tokens.py

@@ -20,7 +20,7 @@ _IDENT_START_RE = re.compile(r"[A-Za-z_]")
 _IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
 @dataclass
 class Token:
-    kind: str  # "WORD" | "OP"
+    kind: str  # "WORD" | "OP" | "ARITH"
     text: str | None = None  # OP: exact operator text (e.g. ">>", "2>&1", "\n")
     segments: list[Segment] | None = None  # WORD: ordered segments
 
@@ -402,6 +402,26 @@ def _scan_operator(src: str, pos: int) -> tuple[str, int]:
     raise AssertionError(f"unreachable operator dispatch at {pos!r}")
 
 
+def _scan_arithmetic_group(src: str, pos: int) -> tuple[str, int]:
+    """Scan ``((...))`` as one token while allowing balanced inner parentheses."""
+    depth = 0
+    cursor = pos + 2
+    while cursor < len(src):
+        if src[cursor : cursor + 2] == "))" and depth == 0:
+            return src[pos + 2 : cursor], cursor + 2
+        char = src[cursor]
+        if char == "(":
+            depth += 1
+        elif char == ")":
+            if depth == 0:
+                raise UnsupportedConstruct(
+                    "malformed-syntax", "Arithmetic loop header contains an unmatched ')'."
+                )
+            depth -= 1
+        cursor += 1
+    raise _unterminated("arithmetic loop header")
+
+
 def tokenize(src: str) -> list[Token]:
     n = len(src)
     tokens: list[Token] = []
@@ -425,7 +445,10 @@ def tokenize(src: str) -> list[Token]:
             pos = n if newline == -1 else newline
             continue
         if src[pos : pos + 2] == "((":
-            raise UnsupportedConstruct("arithmetic-expansion", "Arithmetic command '((...))' is not supported.")
+            arithmetic, newpos = _scan_arithmetic_group(src, pos)
+            tokens.append(Token(kind="ARITH", text=arithmetic))
+            pos = newpos
+            continue
         if c.isdigit():
             j = pos
             while j < n and src[j].isdigit():

package/dist/bundled-resources/skills/deduplicate-by-evidence/SKILL.md

@@ -49,11 +49,13 @@ Inspect the scanner, wrapper, package scripts, and CI command before trusting a
 For jscpd:
 
 1. Prefer an existing repository wrapper such as `npm run check:clones`.
-2. Require pinned jscpd v5 and verify the major version before relying on its Rust-native CLI. Do not silently fall back to the v4 Node engine.
-3. Explicitly configure `maxLines` and `maxSize`; defaults can omit god units. Keep both far above the largest legitimate owned file.
-4. Pin `minLines`, `minTokens`, `mode`, formats, cross-format policy, exact ignores, JSON reporter, and zero threshold in a regression test.
-5. Reconcile every owned candidate with the analyzed count. Account for below-minimum files by exact path and proof that they cannot contain the configured block size.
-6. Keep console projection bounded and retain the complete JSON report out of model context for explicit inspection.
+2. Use the Pi-managed jscpd v5 binary; never install jscpd into the project with npm, npx, Bun, or another package manager. If it is unavailable, run `pi doctor` and block or change approach rather than creating project metadata or dependencies.
+3. Write ad-hoc configs and full reports only under Pi-managed work storage or the OS temporary directory. Do not create repository reports, configs, lockfiles, manifests, or `node_modules` without an explicit request.
+4. Verify the pinned major version before relying on its Rust-native CLI. Do not silently fall back to the v4 Node engine.
+5. Explicitly configure `maxLines` and `maxSize`; defaults can omit god units. Keep both far above the largest legitimate owned file.
+6. Pin `minLines`, `minTokens`, `mode`, formats, cross-format policy, exact ignores, JSON reporter, and zero threshold in a regression test.
+7. Reconcile every owned candidate with the analyzed count. Account for below-minimum files by exact path and proof that they cannot contain the configured block size.
+8. Keep console projection bounded and retain the complete JSON report out of model context for explicit inspection.
 
 Never make the gate green by raising thresholds, increasing minimum clone size, adding broad ignores, renaming identifiers, or reformatting clone blocks.
 

package/dist/bundled-resources/skills/worker-profile-writer/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: worker-profile-writer
+description: "Use when an orchestrator needs a task-scoped worker profile with a selected model, thinking level, tools, resources, or tighter budget before delegation."
+---
+
+# Worker Profile Writer
+
+## How to use the skill
+
+Use this skill before `delegate` when no owner-authored worker profile is a precise fit.
+
+Freedom Dial: high freedom for describing and composing the bounded task; low freedom for authority, persistence, model availability, and budget checks. Pi's core engineering and evidence rules remain mandatory.
+
+## North Star
+
+Create the smallest immutable profile that can complete one explicit task, then delegate with the exact harness-issued profile ID. The session log owns task profiles; project and user profile directories remain untouched.
+
+## Core Sections
+
+### 1. Establish the contract
+
+1. State the worker's single outcome, required evidence, intended files, and completion boundary.
+2. Call `profile_writer` with `action: "inspect"` when authorized bases or configured model/thinking combinations are unknown.
+3. Choose an owner-authored base whose role and authority already cover the task. Never derive from another generated task profile.
+4. Prefer the fastest model with demonstrated ability to satisfy the task contract. Configuration and authentication prove availability, not fitness; use existing fitness evidence or `model_fitness` when the risk justifies its token cost.
+5. Request only the tools and resource profiles the task needs. Omitted fields inherit the base; supplied fields must be exact subsets. Budgets may only tighten.
+
+Human edge: if the task requires an unlisted base, unavailable credentials, broader tools/resources, or a looser budget, stop and ask the user to authorize a durable owner-profile change. Do not route around a rejection.
+
+### 2. Execute and verify
+
+1. Call `profile_writer` with `action: "create"`; never supply or invent a profile ID.
+2. Confirm `created: true`, the expected base, and the reported changed fields.
+3. Pass the returned `profileId` unchanged to one bounded `delegate` task with explicit acceptance criteria.
+4. Wait for the event-driven terminal handoff, retrieve once with `delegate_status`, and independently verify worker claims.
+5. Treat rejection before persistence as a successful safety boundary. Change the approach or request authority; do not retry the same expansion with different wording.
+
+## Anti-Patterns
+
+- Writing one-off profile JSON, settings, reports, or dependencies into the repository.
+- Selecting a model or thinking level that `inspect` did not report as available.
+- Giving a worker extra tools "just in case" or loosening the base budget.
+- Inventing, guessing, editing, or reusing a generated profile ID across sessions or branches.
+- Treating a fast model as fit without task-shaped evidence.
+
+## Examples
+
+Positive: inspect, derive from a read/write implementer, select an authenticated fast model at `low`, narrow tools to `read`, `grep`, and `edit`, tighten token/tool-call limits, then delegate with the returned `task-...` ID.
+
+Negative: a base exposes only `read` and `grep`, but the task requires `edit`. Do not request `edit` from `profile_writer`; select an authorized write-capable base or ask the user for an owner-profile change.
+
+## Self-Check
+
+- The task has one bounded outcome and explicit acceptance evidence.
+- The base is owner-authored and authorized for this orchestrator.
+- Model and thinking level were reported available or otherwise resolved by the harness.
+- Tools/resources are subsets and the budget is unchanged or tighter.
+- The returned ID is passed unchanged; no project/user profile file was created.
+
+## Known Gaps
+
+- Availability does not prove model quality; use task-shaped fitness evidence where failure risk is material.
+- Generated profiles cannot expand authority or survive outside their owning session branch.