pi-dev-team 0.2.0

package/skills/property-based-testing/fixtures/js-roundtrip/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "pbt-js-roundtrip-fixture",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Fixture project for /property-based-testing's fast-check (JS/TS) path (#2190) — see ../../references/languages/javascript.md",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "fast-check": "^4.10.2",
+    "vitest": "^5.0.1"
+  }
+}

package/skills/property-based-testing/fixtures/js-roundtrip/roundtrip.js

@@ -0,0 +1,29 @@
+/**
+ * Fixture module for the fast-check round-trip property path (#2190).
+ *
+ * Exposes `encode`/`decode` as named exports — the same literal-name
+ * round-trip heuristic `hypothesis_scaffold.py`'s Python path looks for
+ * (see `../roundtrip_fixture.py`), mirrored here for the JS/TS path
+ * documented in `../../references/languages/javascript.md`.
+ *
+ * `decode(encode(value)) === value` holds for any string because reversal
+ * is its own inverse.
+ */
+
+/**
+ * Encode a string by reversing it.
+ * @param {string} value
+ * @returns {string}
+ */
+export function encode(value) {
+  return [...value].reverse().join('');
+}
+
+/**
+ * Decode a string produced by encode() by reversing it back.
+ * @param {string} value
+ * @returns {string}
+ */
+export function decode(value) {
+  return [...value].reverse().join('');
+}

package/skills/property-based-testing/fixtures/js-roundtrip/roundtrip.properties.test.js

@@ -0,0 +1,16 @@
+/**
+ * Generated fast-check property test — round-trip property for
+ * encode/decode. Shape documented in
+ * ../../references/languages/javascript.md; do not hand-edit, regenerate if
+ * roundtrip.js changes.
+ */
+import { describe, it } from 'vitest';
+import fc from 'fast-check';
+
+import { encode, decode } from './roundtrip.js';
+
+describe('encode/decode round-trip property', () => {
+  it('decode(encode(x)) === x for any string', () => {
+    fc.assert(fc.property(fc.string(), (x) => decode(encode(x)) === x));
+  });
+});

package/skills/property-based-testing/fixtures/no_property_fixture.py

@@ -0,0 +1,10 @@
+"""Fixture module for hypothesis_scaffold.py's negative case (#2190).
+
+`add_one` has no round-trip counterpart and no documented postcondition, so
+neither heuristic matches — the scaffold should derive no property for it.
+"""
+
+
+def add_one(value: int) -> int:
+    """Add one to a value."""
+    return value + 1

package/skills/property-based-testing/fixtures/roundtrip_fixture.py

@@ -0,0 +1,16 @@
+"""Fixture module for hypothesis_scaffold.py's round-trip heuristic (#2190).
+
+Exposes a module-level `encode`/`decode` pair by name — the exact literal
+names the scaffold's heuristic looks for. `decode(encode(x)) == x` holds for
+any string because reversal is its own inverse.
+"""
+
+
+def encode(value: str) -> str:
+    """Encode a string by reversing it."""
+    return value[::-1]
+
+
+def decode(value: str) -> str:
+    """Decode a string produced by encode() by reversing it back."""
+    return value[::-1]

package/skills/property-based-testing/references/languages/javascript.md

@@ -0,0 +1,54 @@
+# Property-Based Testing — JavaScript / TypeScript (fast-check)
+
+Tool: [fast-check](https://fast-check.dev/). Detection: `package.json`/`tsconfig.json` present — project-init's own JS/TS stack-detection signal (see [`SKILL.md` → Step 1](../../SKILL.md#step-1-detect-the-target-language-reuse-project-init-never-re-derive); this doc never re-derives it).
+
+This is the JS/TS equivalent of [Step 4.1's Python scaffold](../../scripts/hypothesis_scaffold.py) (`hypothesis` → `fast-check`). Same narrow, explicit heuristic — do not extend without updating this doc:
+
+1. **Round-trip** — the target module exports both a function literally named `encode` and one literally named `decode` (named exports, or both methods on the same exported class/object) and the requested function is one of that pair. Generates a test asserting `decode(encode(x)) === x`.
+2. **Invariant** — the target function's JSDoc contains a recognized postcondition phrase (the same phrase list as the Python path — `returns sorted`, `is idempotent`) documented near a type signature (a `@param`/`@returns` JSDoc tag, or a TypeScript type annotation on the function). Generates a test asserting that invariant.
+3. **Neither matches** — no file is written; report the exact same "No property derived" message [Step 4.1](../../scripts/hypothesis_scaffold.py) defines (`NO_PROPERTY_MESSAGE`), substituting the target function name — this doc does not define a second copy of that message.
+
+This is deliberately narrow, matching the Python path's own stated scope — not a general contract-inference engine.
+
+## Install / detect
+
+Per [`SKILL.md` → Step 3](../../SKILL.md#step-3-install-the-property-testing-tool-if-missing): `npm install --save-dev fast-check`, mirroring project-init's existing `npm` devDependency install shape for `oxlint`/`@playwright/test` — never a global/user-level install. Confirm it resolved:
+
+```bash
+npm ls fast-check
+```
+
+## Generation approach
+
+Emit a runnable `<name>.properties.test.js` using `fc.assert(fc.property(...))`, run via this repo's JS test runner convention (`npx vitest run`, per [project-init's own generated `vitest.config.js`](../../../project-init/SKILL.md) — see [`fixtures/js-roundtrip/`](../../fixtures/js-roundtrip/) for a working example project):
+
+```js
+import { describe, it } from 'vitest';
+import fc from 'fast-check';
+
+import { encode, decode } from './roundtrip.js';
+
+describe('encode/decode round-trip property', () => {
+  it('decode(encode(x)) === x for any string', () => {
+    fc.assert(fc.property(fc.string(), (x) => decode(encode(x)) === x));
+  });
+});
+```
+
+An invariant test follows the same `fc.assert(fc.property(<arbitrary>, (value) => <assertion>))` shape, with the arbitrary chosen from the target's parameter type the same narrow way Step 4.1's `_STRATEGY_BY_ANNOTATION` map picks a Hypothesis strategy (e.g. a `number[]` parameter → `fc.array(fc.integer())`; no recognized annotation → `fc.string()`).
+
+## Test determinism & the vendoring boundary
+
+`fast-check` (and its own only dependency, `pure-rand`) is **vendored into this fixture's checked-in `node_modules`** rather than installed live during a test run — this repo's deterministic-tooling standard, the same posture `chk_python_ceiling` takes as `exempt`-but-still-treated-as-blocking in [`.github/required-status-checks.json`](../../../../../../.github/required-status-checks.json). Both packages are pure JS with no native/platform-specific binaries (~1.8M total), so the vendored copy is byte-identical on every dev machine and CI runner. See [`fixtures/js-roundtrip/README.md`](../../fixtures/js-roundtrip/README.md) for the exact `git add -f` mechanics (the repo-root `.gitignore`'s blanket `node_modules/` rule otherwise excludes it, and a nested `.gitignore` cannot un-ignore a directory a parent `.gitignore` already excludes).
+
+`vitest` itself is **not** vendored — newer vitest pulls in platform-native binaries (`@rolldown/binding-<platform>`, `lightningcss-<platform>`) that would silently break on a different host OS/arch than whatever built the vendored copy (this repo's CI is `ubuntu-*`, but maintainers develop on macOS). Resolving `vitest` via `npx vitest run` is project-init's own normal live-install path for the project's test runner, unaffected by this skill's own vendoring requirement — that requirement is scoped to `fast-check`, the property library this skill is actually generating tests against.
+
+## Fixture
+
+[`fixtures/js-roundtrip/`](../../fixtures/js-roundtrip/) — a minimal project with `roundtrip.js` (an `encode`/`decode` pair, string reversal) and the fast-check test a scaffold targeting it would generate (`roundtrip.properties.test.js`). Runs green via:
+
+```bash
+cd fixtures/js-roundtrip
+npm install   # fetches vitest; fast-check/pure-rand are already vendored
+npx vitest run
+```

package/skills/property-based-testing/scripts/detect_and_dispatch.py

@@ -0,0 +1,80 @@
+"""Thin dispatch helper for /property-based-testing's SKILL.md procedure
+(#2190, Step 4.2).
+
+Language detection itself is NOT implemented here. `SKILL.md` runs
+project-init's own stack-detection step first —
+`${CLAUDE_PLUGIN_ROOT}/skills/project-init/SKILL.md` § "Step 1: Detect the
+stack" — and passes its result into this module via `--language`. This
+module only decides, from that already-detected value, whether the skill
+can proceed: it never re-derives a language from project-init's own
+manifest-file detection signals itself.
+
+On an unsupported or missing language it prints the exact message the
+Gherkin "Unsupported or undetected language" scenario requires and returns
+a non-zero exit code, so `SKILL.md`'s procedure can stop with no partial
+run. On a supported language it prints which generator the procedure
+should dispatch to next and returns 0.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+# The only two languages this skill scaffolds properties for today. `JS/TS`
+# is project-init's own stack-detection display name (SKILL.md § "Step 1:
+# Detect the stack") — this module matches it verbatim, never a spelled-out
+# "JavaScript/TypeScript", since that is the actual value Step 1 hands this
+# script. Python dispatches to Step 4.1's hypothesis_scaffold.py; JS/TS
+# dispatches to the fast-check path (references/languages/javascript.md).
+SUPPORTED_LANGUAGES = ("Python", "JS/TS")
+
+UNSUPPORTED_MESSAGE = "Unsupported language: {language} — supported: Python, JS/TS."
+
+_DISPATCH = {
+    "Python": "Hypothesis (scripts/hypothesis_scaffold.py)",
+    "JS/TS": "fast-check (references/languages/javascript.md)",
+}
+
+
+def is_supported(language: str | None) -> bool:
+    """True when `language` is one of the two languages this skill supports."""
+    return language in SUPPORTED_LANGUAGES
+
+
+def unsupported_language_message(language: str | None) -> str:
+    """Render the exact unsupported-language message. `language` is the
+    value project-init's stack detection (see module docstring) returned —
+    `None`/empty when detection failed or returned nothing, in which case
+    the message interpolates the literal word "unknown"."""
+    return UNSUPPORTED_MESSAGE.format(language=language or "unknown")
+
+
+def main(argv: list | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Decide whether /property-based-testing can proceed for an "
+            "already-detected language (from project-init's stack "
+            "detection) and print the unsupported-language message when it "
+            "can't."
+        )
+    )
+    parser.add_argument(
+        "--language",
+        default=None,
+        help=(
+            "the language project-init's stack detection returned; omit "
+            "when detection failed or returned nothing"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    if not is_supported(args.language):
+        print(unsupported_language_message(args.language))
+        return 1
+
+    print(f"Detected {args.language} — dispatching to {_DISPATCH[args.language]}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/property-based-testing/scripts/hypothesis_scaffold.py

@@ -0,0 +1,276 @@
+"""Hypothesis property-test scaffold for a single target Python function (#2190).
+
+This module's own analysis is stdlib-only (`ast`), per ADR 0014 — no
+third-party imports here. The *generated* test file it writes imports the
+third-party `hypothesis` library; that import lives only in the emitted
+file, never in this script.
+
+Narrow, explicit heuristic (do not extend without updating this docstring):
+
+1. Round-trip: the target module defines a function literally named
+   `encode` and a function literally named `decode` — either both at module
+   level, or both as methods of the same class — and the requested function
+   is one of that pair. Generates a test asserting
+   `decode(encode(x)) == x`.
+2. Invariant: the target function's docstring contains a recognized
+   postcondition phrase (see `INVARIANT_PHRASES`) and the function carries
+   at least one type annotation (parameter or return) — the "near a type
+   hint" signal. Generates a test asserting that invariant.
+3. Neither matches: no file is written; the exact negative message is
+   printed to stdout.
+
+This is deliberately narrow — it is not a general contract-inference
+engine. Extending the phrase list or the type-annotation proximity check is
+in scope; inferring arbitrary contracts from prose is not.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import os
+from dataclasses import dataclass
+
+# Postcondition phrase -> human label used only for readability; the phrase
+# itself is the literal substring matched (case-insensitively) against the
+# target function's docstring.
+INVARIANT_PHRASES = ("returns sorted", "is idempotent")
+
+NO_PROPERTY_MESSAGE = (
+    "No property derived for {function} — no round-trip pair or documented "
+    "invariant found nearby. Add a docstring postcondition (e.g. a 'returns "
+    "sorted'/'is idempotent'-style phrase) to make one derivable."
+)
+
+# Narrow annotation -> Hypothesis strategy expression map. Anything not
+# listed here falls back to st.text() — this is not general type inference.
+_STRATEGY_BY_ANNOTATION = {
+    "str": "st.text()",
+    "int": "st.integers()",
+    "float": "st.floats(allow_nan=False, allow_infinity=False)",
+    "bool": "st.booleans()",
+    "list[int]": "st.lists(st.integers())",
+    "List[int]": "st.lists(st.integers())",
+}
+
+
+@dataclass
+class RoundTripProperty:
+    encode_name: str
+    decode_name: str
+    class_name: str | None = None
+
+
+@dataclass
+class InvariantProperty:
+    function_name: str
+    phrase: str
+
+
+def _module_name(module_path: str) -> str:
+    """Derive the importable module name a generated test's `from {module}
+    import ...` line will use.
+
+    Raises `ValueError` when the basename isn't a valid Python identifier —
+    this value is interpolated unescaped into a generated test file's import
+    statement (`_render_roundtrip_test`/`_render_invariant_test`), so a
+    filename engineered to contain e.g. a newline could otherwise inject
+    arbitrary statements into a file pytest later collects and executes
+    (security-review finding). Every other interpolated value on that path
+    is already constrained to a safe shape: `encode`/`decode` are literals,
+    `class_name`/`function_name` are `ast.FunctionDef`/`ClassDef.name`
+    values (valid identifiers by construction), and `module_dir` is
+    `repr()`-escaped at render time.
+    """
+    base = os.path.basename(module_path)
+    name = base.removesuffix(".py")
+    if not name.isidentifier():
+        raise ValueError(
+            f"unsupported module filename {module_path!r}: {name!r} is not a "
+            "valid Python identifier, so it can't be used in a generated "
+            "test's import statement"
+        )
+    return name
+
+
+def _parse_module(module_path: str) -> ast.Module:
+    with open(module_path, "r", encoding="utf-8") as handle:
+        source = handle.read()
+    return ast.parse(source, filename=module_path)
+
+
+def _find_function(tree: ast.Module, name: str) -> ast.FunctionDef | None:
+    """Module-level functions only — deliberately not `ast.walk`, which
+    would also match a same-named method inside a class body. The invariant
+    render path assumes a module-level import (`from {module} import
+    {function_name}`), which is wrong for a method (no `self`/receiver, no
+    class import/instantiation) — see `find_roundtrip_pair` for the
+    separate, already class-aware handling the round-trip path has."""
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef) and node.name == name:
+            return node
+    return None
+
+
+def find_roundtrip_pair(tree: ast.Module) -> RoundTripProperty | None:
+    """Locate a literal `encode`/`decode` pair at module level or as methods
+    of one class. Returns None when no such pair exists."""
+    module_level = {n.name for n in tree.body if isinstance(n, ast.FunctionDef)}
+    if "encode" in module_level and "decode" in module_level:
+        return RoundTripProperty(encode_name="encode", decode_name="decode")
+
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            methods = {n.name for n in node.body if isinstance(n, ast.FunctionDef)}
+            if "encode" in methods and "decode" in methods:
+                return RoundTripProperty(
+                    encode_name="encode", decode_name="decode", class_name=node.name
+                )
+    return None
+
+
+def _has_nearby_type_hint(func: ast.FunctionDef) -> bool:
+    """Narrow proximity check: the function carries at least one type
+    annotation (a parameter or its return type)."""
+    if func.returns is not None:
+        return True
+    return any(arg.annotation is not None for arg in func.args.args)
+
+
+def find_invariant(func: ast.FunctionDef) -> InvariantProperty | None:
+    docstring = ast.get_docstring(func) or ""
+    if not docstring or not _has_nearby_type_hint(func):
+        return None
+    lowered = docstring.lower()
+    for phrase in INVARIANT_PHRASES:
+        if phrase in lowered:
+            return InvariantProperty(function_name=func.name, phrase=phrase)
+    return None
+
+
+def _first_arg_strategy(func: ast.FunctionDef) -> str:
+    args = func.args.args
+    if not args or args[0].annotation is None:
+        return "st.text()"
+    annotation_text = ast.unparse(args[0].annotation)
+    return _STRATEGY_BY_ANNOTATION.get(annotation_text, "st.text()")
+
+
+def _render_roundtrip_test(
+    prop: RoundTripProperty, module_path: str, module_name: str
+) -> str:
+    module_dir = os.path.dirname(os.path.abspath(module_path))
+    if prop.class_name:
+        import_line = f"from {module_name} import {prop.class_name}"
+        setup = f"    obj = {prop.class_name}()\n"
+        call_encode = f"obj.{prop.encode_name}(x)"
+        call_decode = "obj.{}({})".format(prop.decode_name, "encoded")
+    else:
+        import_line = f"from {module_name} import {prop.encode_name}, {prop.decode_name}"
+        setup = ""
+        call_encode = f"{prop.encode_name}(x)"
+        call_decode = f"{prop.decode_name}(encoded)"
+
+    return (
+        f'"""Generated by hypothesis_scaffold.py — round-trip property test\n'
+        f"for {prop.encode_name}/{prop.decode_name}. Do not hand-edit;\n"
+        f'regenerate via /property-based-testing if the source module changes.\n"""\n\n'
+        "import os\n"
+        "import sys\n\n"
+        f"sys.path.insert(0, {module_dir!r})\n\n"
+        "from hypothesis import given\n"
+        "from hypothesis import strategies as st\n\n"
+        f"{import_line}\n\n\n"
+        "@given(st.text())\n"
+        f"def test_{prop.encode_name}_{prop.decode_name}_roundtrip(x):\n"
+        f"{setup}"
+        f"    encoded = {call_encode}\n"
+        f"    assert {call_decode} == x\n"
+    )
+
+
+def _render_invariant_test(
+    prop: InvariantProperty, func: ast.FunctionDef, module_path: str, module_name: str
+) -> str:
+    module_dir = os.path.dirname(os.path.abspath(module_path))
+    strategy_expr = _first_arg_strategy(func)
+    if prop.phrase == "returns sorted":
+        assertion = (
+            f"    result = {prop.function_name}(value)\n"
+            "    assert result == sorted(result)\n"
+        )
+    elif prop.phrase == "is idempotent":
+        assertion = (
+            f"    once = {prop.function_name}(value)\n"
+            f"    twice = {prop.function_name}(once)\n"
+            "    assert twice == once\n"
+        )
+    else:  # pragma: no cover - defensive, INVARIANT_PHRASES is exhaustive above
+        assertion = f"    {prop.function_name}(value)\n"
+
+    return (
+        f'"""Generated by hypothesis_scaffold.py — invariant property test\n'
+        f'for {prop.function_name} ("{prop.phrase}"). Do not hand-edit;\n'
+        f'regenerate via /property-based-testing if the source module changes.\n"""\n\n'
+        "import sys\n\n"
+        f"sys.path.insert(0, {module_dir!r})\n\n"
+        "from hypothesis import given\n"
+        "from hypothesis import strategies as st\n\n"
+        f"from {module_name} import {prop.function_name}\n\n\n"
+        f"@given({strategy_expr})\n"
+        f"def test_{prop.function_name}_invariant(value):\n"
+        f"{assertion}"
+    )
+
+
+def scaffold(module_path: str, function_name: str, out_dir: str) -> str | None:
+    """Analyze `module_path` for a property involving `function_name`.
+
+    On a match, writes `test_<function_name>_properties.py` into `out_dir`
+    and returns its path. On no match, prints the exact negative message to
+    stdout and returns None without writing any file.
+    """
+    tree = _parse_module(module_path)
+    module_name = _module_name(module_path)
+
+    roundtrip = find_roundtrip_pair(tree)
+    if roundtrip and function_name in (roundtrip.encode_name, roundtrip.decode_name):
+        content = _render_roundtrip_test(roundtrip, module_path, module_name)
+    else:
+        func = _find_function(tree, function_name)
+        invariant = find_invariant(func) if func is not None else None
+        if func is not None and invariant:
+            content = _render_invariant_test(invariant, func, module_path, module_name)
+        else:
+            print(NO_PROPERTY_MESSAGE.format(function=function_name))
+            return None
+
+    os.makedirs(out_dir, exist_ok=True)
+    out_path = os.path.join(out_dir, f"test_{function_name}_properties.py")
+    with open(out_path, "w", encoding="utf-8") as handle:
+        handle.write(content)
+    return out_path
+
+
+def main(argv: list | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Scaffold a Hypothesis property test for a Python function."
+    )
+    parser.add_argument("module_path", help="path to the target module")
+    parser.add_argument("function_name", help="name of the function to target")
+    parser.add_argument(
+        "--out-dir",
+        default=None,
+        help="directory to write the generated test into (default: module's directory)",
+    )
+    args = parser.parse_args(argv)
+    out_dir = args.out_dir or os.path.dirname(os.path.abspath(args.module_path))
+    result = scaffold(args.module_path, args.function_name, out_dir)
+    if result:
+        print(f"Wrote {result}")
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/proxy-resilience/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: proxy-resilience
+description: Bounded backoff, retry ceiling, and escalation convention for repeated failures against a corporate Anthropic proxy. Use when you observe repeated HTTP 429 rate-limit responses or connection-refused errors that reference a proxy host, or the user says "proxy is rate-limiting", "429 from the proxy", "proxy connection refused", or "corporate proxy is flaky".
+role: worker
+user-invocable: true
+---
+
+# Proxy Resilience
+
+## Overview
+
+A corporate proxy fronting Anthropic API traffic enforces its own rate
+limits and allowlist behavior, independent of the underlying account's tier
+— a 429 or connection-refused error in a proxy-fronted session is a
+different failure class than a direct-API rate limit (already retried
+natively by the harness; do not apply this convention to those).
+
+Covers two related failure modes sharing one root cause (transient
+corporate-proxy unavailability) and one remedy shape (bounded backoff, a
+hard retry ceiling, then escalate): rate-limit errors (issue #723, this
+file) and connection-refused errors (issue #724). Documented together so
+either failure mode is found in one place.
+
+## Detection Signals
+
+Treat an error as **proxy rate-limiting** when it shows *all* of:
+
+1. The session is known to run against a corporate proxy (e.g. the
+   `anthropic-proxy` operating note, a proxy env var/base URL, or a
+   previously observed proxy hostname in error text).
+2. The error text contains HTTP 429, "rate limit", "too many requests", or
+   "quota exceeded".
+3. The error references the proxy host, not `api.anthropic.com` directly.
+
+Treat an error as **proxy connection-refused** (#724) when it shows (1)
+above plus a connection-level failure (`ECONNREFUSED`, "connection
+refused", "could not connect", timeout connecting to the proxy host).
+
+## Backoff Schedule
+
+Apply exponential backoff **per call site** (one place repeatedly issuing
+the same request — e.g. one subagent retrying one API call, not the whole
+session): **initial delay 1s, ×2 multiplier, 60s cap, max 5 attempts.**
+
+| Attempt | 1 | 2 | 3 | 4 | 5 (last) |
+|---------|---|---|---|---|---|
+| Delay | 1s | 2s | 4s | 8s | 16s |
+
+After 5 retries at the same call site still fail with a proxy rate-limit
+error, stop retrying and escalate (below) rather than looping further. Five
+is deliberately far below any plausible recurrence of "28 rate-limit errors
+in one session" — that scale breaches this ceiling on the first call site
+alone, well before reaching 28.
+
+## Escalation Rule
+
+Once the retry budget (5 attempts) is exhausted at a call site:
+
+1. **Stop retrying that call site** — no indefinite loop, no silent failure.
+2. Surface one plain-language line naming the proxy as the suspected cause,
+   e.g.: "Repeated rate-limit errors from the corporate Anthropic proxy —
+   pausing retries here; consider reducing concurrent requests or retrying
+   later."
+3. Let the user decide whether to continue, reduce concurrency, or pause.
+   Escalate and wait for direction rather than unilaterally abandoning the
+   task.
+
+## Concurrency Guidance
+
+Parallel subagent/Task fan-out against a shared proxy allowlist is a likely
+amplifier of rate-limit bursts — concurrent requests can exhaust the
+proxy's rate window faster than a serial stream would. If repeated 429s are
+observed, reduce concurrent dispatch (e.g. lower
+`DEV_TEAM_MAX_PARALLEL_BUILDS`, or serialize the specific failing call site)
+before increasing backoff further; prefer narrow serialization over
+session-wide serialization.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it's wrong | What to do instead |
+| ------------- | --------------- | ------------------- |
+| Retrying immediately with no delay | Compounds the burst that triggered the 429 | Apply the backoff schedule above |
+| Treating a direct Anthropic 429 the same as a proxy 429 | The harness already retries direct API limits; double-retrying wastes time | Confirm proxy involvement (Detection Signals) first |
+| Increasing concurrency to "push through" a rate limit | Makes proxy throttling worse | Reduce concurrent dispatch instead |