@poetic-ai/poetic 1.42.0

package/templates/.poetic/task-types/security.yaml

@@ -0,0 +1,39 @@
+id: security
+version: 1
+extends: general
+match:
+  priority: 20
+  keywords:
+    - security
+    - auth
+    - authentication
+    - authorization
+    - token
+    - jwt
+    - oauth
+    - csrf
+    - xss
+    - vuln
+    - vulnerability
+policy:
+  routing:
+    defaultStrategy: conservative
+    preferCompetition: true
+  decomposition:
+    requiredStageTypes:
+      - verify
+    maxParallelGroups: 1
+    guidance:
+      hints:
+        - Keep allowlists tight and explicit
+        - Add deterministic verify commands (tests/typecheck)
+      antiPatterns:
+        - Do not broaden allowlists to "make it work"
+        - Avoid parallel changes to auth/security surfaces
+  judging:
+    framework: hybrid
+    defaultScore: 80
+    minimumScore: 70
+  allowlist:
+    requireNonEmpty: true
+    mode: strict

package/templates/AGENTS.template.md

@@ -0,0 +1,99 @@
+# {{PROJECT_NAME}} - AI Agent Guide
+
+> Poetic config: `.poetic/` | Language: {{LANGUAGE}} | Framework: {{FRAMEWORK}}
+
+## Poetic Commands
+
+```bash
+poetic plan next                      # Show actionable work items
+poetic plan sprint status             # Current sprint progress
+poetic plan task list                 # Tasks in the active sprint
+poetic run "task description"         # Run a task with the default provider
+poetic compete "task description"     # Run across providers with AI judge
+```
+
+## Managed Directories
+
+Never edit these directly. They are owned by the Poetic CLI.
+
+| Directory  | Purpose                   |
+|------------|---------------------------|
+| `backlog/` | Prioritized work items    |
+| `sprint/`  | Sprint plans and capacity |
+| `task/`    | Task execution artifacts  |
+
+For any operation in a managed directory:
+
+1. Run `poetic <subcommand> --help` to see available operations.
+2. If a CLI command covers the operation, use it.
+3. If no CLI command covers it, stop and ask. Do not edit the file directly.
+
+```bash
+poetic plan backlog add "description"
+poetic plan backlog list
+poetic plan sprint status
+poetic plan task list
+```
+
+When `poetic plan backlog add` reports completeness warnings or leaves
+`<<<FILL>>>` markers, finish the item with
+`poetic plan backlog refine <id>` (or `poetic plan backlog update <id>`) before
+moving on, unless you intend to defer it.
+
+## Running Work Through Poetic
+
+When the task is to execute work, invoke the Poetic pipeline rather than
+hand-editing managed files or simulating a run yourself:
+
+```bash
+poetic run "task description"                    # single provider
+poetic compete "task description"                # multiple providers + AI judge
+poetic build --planned "intent"                     # plan -> sprint -> execution
+poetic plan backlog execute <id>                 # canonical ship path for a backlog item
+poetic plan backlog finalize <id> --pr <n> --commit <sha>
+```
+
+`poetic build --planned` and `poetic sprint run` refuse to run on a protected
+branch (`main`/`master`) without `--allow-main`. Create a run branch first:
+
+```bash
+git checkout -b run/<short-slug>
+poetic build --planned "intent"
+```
+
+## Model Selection
+
+Trust the defaults. Prefer logical variants such as `claude:conservative` over
+pinned model versions; the resolved defaults are maintained for you.
+
+```bash
+poetic config resolved        # show the provider/model defaults in effect
+```
+
+## Project Context
+
+**Language**: {{LANGUAGE}}
+**Framework**: {{FRAMEWORK}}
+
+Record the target project's real build, test, and contribution instructions
+below. Keep examples specific to this repository rather than copying Poetic's
+maintainer rules into the consumer project.
+
+Add project-specific guidance below this line.
+
+### Test Commands
+
+```bash
+{{TEST_COMMAND}}
+```
+
+### Build Commands
+
+```bash
+{{BUILD_COMMAND}}
+```
+
+## References
+
+- `.poetic/config/providers.yaml` - AI provider configuration
+- `.poetic/config/poetic.config.jsonc` - Project-specific Poetic config

package/templates/CLAUDE.template.md

@@ -0,0 +1 @@
+@./AGENTS.md

package/templates/GEMINI.template.md

@@ -0,0 +1 @@
+@./AGENTS.md

package/templates/builtin-workflows/code-review.yaml

@@ -0,0 +1,73 @@
+name: code-review
+description: Cross-provider read-only review — collects diff, runs analysis stage, verifies findings JSON
+# Template variable: baseRef (default HEAD~1).
+# When invoking via 'poetic review --flywheel', the CLI generates a per-run YAML with the
+# resolved base SHA substituted into the collect-diff command before flywheel run.
+#
+# LOAD-BEARING LITERALS — two exact strings in this file are matched by regexes in
+# src/cli/commands/review.ts. Changing their text or indentation shape breaks the
+# per-run YAML generation for 'poetic review --flywheel':
+#   1. the collect-diff git diff command  -> substituteCodeReviewCollectDiff
+#   2. the reviewer modelRole line, text AND leading whitespace shape
+#      -> injectReviewerProviderAndModel
+# Both are marked with a LOAD-BEARING comment at their site. Those regexes match the
+# FIRST occurrence in the file, so never repeat either literal in a comment either.
+stages:
+  - id: collect-diff
+    name: Collect Diff
+    type: verify
+    deps: []
+    outputs:
+      "verify-stdout": text
+    verify:
+      commands:
+        # LOAD-BEARING: exact text matched by substituteCodeReviewCollectDiff
+        # (src/cli/commands/review.ts). Do not reword.
+        - git diff --unified=3 HEAD~1...HEAD
+
+  - id: review
+    name: Code Review
+    type: standard
+    deps: [collect-diff]
+    inputs:
+      - collect-diff.verify-stdout
+    promptRef:
+      id: code-review
+    capabilities:
+      modifiesFiles: false
+      executionIntent: analysis
+    # LOAD-BEARING: injectReviewerProviderAndModel (src/cli/commands/review.ts)
+    # matches this line's exact text and leading-whitespace shape to insert
+    # provider/model above it. Do not reword or reindent.
+    modelRole: reviewer
+    outputs:
+      findings: text
+
+  - id: verify-findings
+    name: Verify Findings JSON
+    type: verify
+    deps: [review]
+    inputs:
+      - review.findings
+    # This gate is this workflow's ONLY validation when it runs via
+    # 'poetic flywheel run code-review' (nothing downstream parses the artifact),
+    # so it validates against the authoritative contract directly rather than
+    # approximating it: 'internal findings-schema' runs agentOutputSchema from
+    # src/planning/agent-ingest.ts over the artifact, per finding.
+    #
+    # This replaced seven independent 'grep -qzE' whole-buffer scans. Because each
+    # scan was separate, together they proved only that every required field
+    # appeared SOMEWHERE in the artifact — a payload whose fields were spread
+    # across two individually invalid findings passed while agentOutputSchema
+    # rejected both. Being the same schema, this gate cannot drift from
+    # 'poetic review --flywheel', which Zod-validates the same shape downstream.
+    #
+    # An empty findings array is valid: a clean review must pass.
+    #
+    # 'poetic' resolved from PATH, NOT 'node dist/entry.js': verify commands run
+    # with the STAGE WORKTREE as cwd, where a repo-relative dist/ path does not
+    # resolve. This mirrors 'poetic internal review-gate', the existing generated
+    # gate, and is allowlisted by the same validatePoeticInternalArgv path.
+    verify:
+      commands:
+        - poetic internal findings-schema --findings .poetic-stage-inputs/review.findings.txt

package/templates/builtin-workflows/compete-streak.yaml

@@ -0,0 +1,78 @@
+name: compete-streak
+description: Built-in proof — multi-judge + matrix advisory validation; verify asserts candidates evidence block
+stages:
+  - id: compete-streak-competition
+    name: Compete Streak Competition
+    type: competition
+    deps: []
+    prompt: |
+      Analyze this repository for one concrete low-risk improvement. Do not edit files; return a concise evidence-backed recommendation grounded in files that actually exist in the current repository.
+    capabilities:
+      modifiesFiles: false
+      executionIntent: analysis
+    validation:
+      enabled: true
+      requireChanges: false
+    outputs:
+      candidates: json
+    competition:
+      # KNOWN [B7] DEVIATION (unresolved): these provider ids are hardcoded literals
+      # and are NOT config-overridable. The proof only needs TWO DISTINCT enabled
+      # providers — any two would do — but StageConfig.competition.variants[].provider
+      # (VariantSpec in src/automation/flywheel-types.ts) is a required literal string
+      # with no resolver indirection: unlike a standard stage's `provider`, it is never
+      # routed through the config resolution engine or ProviderRegistry, and no config
+      # layer can redirect it. De-pinning requires a schema change (a way to request
+      # "any N distinct enabled providers"). Same deviation as judge-regression.yaml.
+      variants:
+        - provider: opencode
+          strategy: conservative
+        - provider: claude
+          strategy: conservative
+      judgeConfig:
+        judgeRun: [ai, multi-lens]
+        judgePrimary: ai
+        matrixAuthority: advisory
+        type: ai
+      applyWinner: false
+      preserveCandidates: true
+      tieBreaker:
+        mode: prefer-first-ranked
+
+  - id: verify-compete-streak-evidence
+    name: Verify multi-judge evidence
+    type: verify
+    deps: [compete-streak-competition]
+    inputs:
+      - compete-streak-competition.candidates
+    # Assert the evidence VALUES, and do it without coupling to the serializer's
+    # pretty-print spacing. Every pattern uses -z (whole file as one buffer) plus
+    # [[:space:]]* around the colon, so a compact-JSON or indent-width change cannot
+    # turn this proof red; values are delimited so an incidental substring cannot make
+    # it pass. Previously '"variantCount": 2' hardcoded one space after the colon and
+    # would also have accepted variantCount 20, 21, ...
+    # Artifact shape: src/automation/flywheel-competition-executor.ts (candidates save).
+    #
+    # NO BACKSLASHES in these patterns: parseVerifyCommand strips backslash escapes, so
+    # a `\[` would reach grep as a bare `[` and fail with "brackets not balanced".
+    # Metacharacters use bracket expressions instead: [[] for '[', [{] for '{', [}] for '}'.
+    verify:
+      commands:
+        - 'grep -qzE ''"winner"[[:space:]]*:'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        # rankings is a non-empty array of objects.
+        - 'grep -qzE ''"rankings"[[:space:]]*:[[:space:]]*[[][[:space:]]*[{]'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        # Exactly the two configured variants ran — the trailing delimiter stops
+        # variantCount 20+ from satisfying a "2" match.
+        - 'grep -qzE ''"variantCount"[[:space:]]*:[[:space:]]*2[[:space:]]*(,|[}]|$)'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        - 'grep -qzE ''"multiJudgeEvidence"[[:space:]]*:'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        # Multi-judge evidence carries real values, not just the keys.
+        - 'grep -qzE ''"selectedJudge"[[:space:]]*:[[:space:]]*"[^"]+"'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        - 'grep -qzE ''"judgeRunRequested"[[:space:]]*:[[:space:]]*[[]'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        - 'grep -qzE ''"allJudgesAgree"[[:space:]]*:[[:space:]]*(true|false)'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+        # matrixAuthority stayed advisory (this workflow's whole point).
+        - 'grep -qzE ''"matrixAuthority"[[:space:]]*:[[:space:]]*"advisory"'' .poetic-stage-inputs/compete-streak-competition.candidates.json'
+
+git:
+  historyCleanup: keep-all
+  commitStrategy: each-attempt
+  skipHooksOnIntermediate: true

package/templates/builtin-workflows/hello-verify.yaml

@@ -0,0 +1,10 @@
+name: hello-verify
+description: Built-in smoke workflow — verify stage confirms execution inside a Git worktree
+stages:
+  - id: verify-ok
+    name: Verify OK
+    deps: []
+    type: verify
+    verify:
+      commands:
+        - git rev-parse --is-inside-work-tree

package/templates/builtin-workflows/judge-regression.yaml

@@ -0,0 +1,114 @@
+# TypeScript-target demo: this built-in proof workflow writes a TypeScript file
+# (tests/flywheel-demo/judge-regression-retry.ts) into the repo it runs in.
+# Run it only against a JavaScript/TypeScript target (or a disposable repo).
+#
+# Scope: this is a self-contained JUDGE proof, not target-facing verification logic.
+# What it proves is that the default AI judge is invoked and emits the candidates
+# evidence contract asserted below; the TypeScript file it asks for is only the
+# workload that gives the judge two candidates to rank. It runs no target-project
+# toolchain command (no package manager, compiler, or test runner), so it does not
+# infer or hardcode the target's tooling. The .ts path is intentionally fixed —
+# parameterizing the language would make the workload, and therefore the judge
+# comparison, non-reproducible across runs without making the proof any broader.
+# Prefer a disposable repo; the single file it writes is confined to the allowlist.
+name: judge-regression
+description: Built-in proof — default AI judge invocation; verify asserts candidates artifact contract
+stages:
+  - id: competition-judge-regression
+    name: Judge Regression Competition
+    type: competition
+    deps: []
+    prompt: |
+      Implement an exponential backoff retry utility with the following requirements:
+
+      FILE: tests/flywheel-demo/judge-regression-retry.ts (new)
+
+      Requirements:
+      1. Export a function `retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>`
+      2. Export interface `RetryOptions` with:
+         - maxAttempts: number (default: 3)
+         - initialDelayMs: number (default: 100)
+         - maxDelayMs: number (default: 5000)
+         - backoffMultiplier: number (default: 2)
+         - jitter: boolean (default: true)
+      3. Implement exponential backoff: delay = min(initialDelay * (multiplier ^ attempt), maxDelay)
+      4. Add jitter: when enabled, randomize delay ±25%
+      5. Include in-code comments explaining the backoff formula
+      6. Handle edge cases:
+         - maxAttempts = 0 should throw immediately without retrying
+         - Negative delays should be treated as 0
+         - Should preserve the original error if all retries fail
+    capabilities:
+      modifiesFiles: true
+      executionIntent: edit
+    validation:
+      enabled: true
+      requireChanges: true
+      checks:
+        - type: file-exists
+          path: tests/flywheel-demo/judge-regression-retry.ts
+        - type: file-contains
+          path: tests/flywheel-demo/judge-regression-retry.ts
+          content: export function retry
+        - type: file-contains
+          path: tests/flywheel-demo/judge-regression-retry.ts
+          content: RetryOptions
+    allowlist:
+      - tests/flywheel-demo/judge-regression-retry.ts
+    outputs:
+      candidates: json
+    competition:
+      # KNOWN [B7] DEVIATION (unresolved): these provider ids are hardcoded literals
+      # and are NOT config-overridable. The proof only needs TWO DISTINCT enabled
+      # providers — any two would do — but StageConfig.competition.variants[].provider
+      # (VariantSpec in src/automation/flywheel-types.ts) is a required literal string
+      # with no resolver indirection: unlike a standard stage's `provider`, it is never
+      # routed through the config resolution engine or ProviderRegistry, and no config
+      # layer can redirect it. Omitting or emptying it passes validateWorkflowConfig
+      # and then fails deeper with an unhelpful error, so the literals are the only
+      # currently expressible form. De-pinning requires a schema change (a way to
+      # request "any N distinct enabled providers"); until then this is disclosed
+      # rather than hidden.
+      variants:
+        - provider: claude
+          strategy: conservative
+        - provider: gemini
+          strategy: innovative
+      judgeConfig:
+        type: multi-lens
+      applyWinner: true
+      preserveCandidates: true
+      tieBreaker:
+        mode: prefer-first-ranked
+
+  - id: verify-judge-evidence
+    name: Verify judge evidence artifact
+    type: verify
+    deps: [competition-judge-regression]
+    inputs:
+      - competition-judge-regression.candidates
+    # Assert the judge evidence VALUES, not just that the keys exist. Each pattern is
+    # whitespace-tolerant (-z reads the file as one buffer, [[:space:]]* absorbs the
+    # serializer's indent) so a JSON formatting change cannot turn this proof red, and
+    # each value is delimited so an incidental substring cannot make it pass —
+    # 'grep -q ai-judge' used to match "not-ai-judge" and any other occurrence.
+    # Artifact shape: src/automation/flywheel-competition-executor.ts (candidates save).
+    #
+    # NO BACKSLASHES in these patterns: parseVerifyCommand strips backslash escapes, so
+    # a `\[` would reach grep as a bare `[` and fail with "brackets not balanced".
+    # Metacharacters use bracket expressions instead: [[] for '[', [{] for '{', [}] for '}'.
+    verify:
+      commands:
+        # The AI judge actually ran (not merely that the key is present).
+        - 'grep -qzE ''"aiJudgeInvoked"[[:space:]]*:[[:space:]]*true'' .poetic-stage-inputs/competition-judge-regression.candidates.json'
+        # ...and it, not the deterministic path, decided the ranking.
+        - 'grep -qzE ''"scoringMode"[[:space:]]*:[[:space:]]*"ai-judge"'' .poetic-stage-inputs/competition-judge-regression.candidates.json'
+        # rankings is a non-empty array of objects.
+        - 'grep -qzE ''"rankings"[[:space:]]*:[[:space:]]*[[][[:space:]]*[{]'' .poetic-stage-inputs/competition-judge-regression.candidates.json'
+        # Both variants succeeded, so the judge had a real comparison to make.
+        - 'grep -qzE ''"successCount"[[:space:]]*:[[:space:]]*[2-9][0-9]*'' .poetic-stage-inputs/competition-judge-regression.candidates.json'
+
+git:
+  historyCleanup: keep-all
+  commitStrategy: each-attempt
+  skipHooksOnIntermediate: true

package/templates/builtin-workflows/skills/code-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: code-review
+description: Cross-provider read-only code review — emit structured findings in the agent finding schema
+---
+
+You are performing a read-only code review. You have been given a unified diff artifact to analyze.
+
+## Instructions
+
+1. Read the unified diff provided in the **Input Artifacts** section of your prompt (artifact `collect-diff.verify-stdout` from the collect-diff stage).
+2. Analyze the changes for the following categories:
+   - **correctness** — logic errors, off-by-one errors, incorrect assumptions, broken contracts
+   - **security** — injection, path traversal, credential leakage, unsafe deserialization, privilege escalation
+   - **performance** — unnecessary allocation, N+1 patterns, blocking calls, algorithmic regressions
+   - **bug** — null/undefined dereferences, race conditions, missing error handling, exception swallowing
+3. Only report findings with confidence ≥ 0.6. Do not invent issues.
+4. You MUST NOT modify any files. This is a read-only analysis.
+
+## Output Format
+
+After your analysis, emit a single ```json code block containing a JSON object that matches the agent finding schema exactly.
+
+Required schema for each finding:
+- `title` (string, ≤200 chars) — short description of the issue
+- `category` (one of: `"bug"`, `"performance"`, `"security"`, `"correctness"`, `"style"`)
+- `severity` (one of: `"critical"`, `"high"`, `"medium"`, `"low"`, or omit/null if unknown)
+- `confidence` (number 0.0–1.0)
+- `ruleId` (string) — stable identifier for this class of issue, e.g. `"null-deref"`, `"sql-injection"`
+- `file` (string) — repo-relative file path
+- `startLine` (integer > 0, or omit/null) — first affected line
+- `endLine` (integer > 0, or omit/null) — last affected line
+- `snippet` (string, or omit/null) — relevant code snippet (≤200 chars)
+- `symbolName` (string, or omit/null) — affected function or variable name
+- `reasoning` (string) — explanation of the issue and its impact
+
+The output object must have a top-level `findings` array. If no issues are found, emit an empty array.
+
+Example output:
+
+```json
+{
+  "findings": [
+    {
+      "title": "Unhandled promise rejection in retry loop",
+      "category": "bug",
+      "severity": "high",
+      "confidence": 0.85,
+      "ruleId": "unhandled-rejection",
+      "file": "src/utils/retry.ts",
+      "startLine": 42,
+      "endLine": 44,
+      "snippet": "await doWork().catch(() => {})",
+      "symbolName": "retryWithBackoff",
+      "reasoning": "The catch handler silently discards errors, making failures invisible to callers."
+    }
+  ]
+}
+```
+
+Emit ONLY findings from code that appears in the diff. Do not report pre-existing issues in unchanged context lines.

package/templates/builtin-workflows/skills/hello-verify/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: hello-verify
+description: Minimal built-in skill packaged with hello-verify for prompt-store seeding proof
+---
+
+You are running the hello-verify built-in skill. Respond with a single line: OK