@bastani/atomic 0.9.16-alpha.6 → 0.9.16-alpha.7

package/dist/builtin/subagents/skills/qlty/references/plugins-and-extensions.md

@@ -0,0 +1,228 @@
+# Plugins and Linter Extensions
+
+> **Sources** (retrieved 2026-08-26): <https://docs.qlty.sh/cli/concepts/plugins.md> and
+> <https://docs.qlty.sh/cli/linter-extensions.md>.
+> Copied from those pages. Text and TOML examples are unchanged; MDX `<Note>`, `<Warning>`, and
+> `<CodeGroup>` wrappers are rendered as Markdown blockquotes and separate code blocks, and
+> relative links are expanded to absolute URLs. Full `qlty.toml` reference:
+> <https://docs.qlty.sh/cli/qlty-toml.md>.
+
+---
+
+## Plugins
+
+Qlty integrates with linters, auto-formatters, security scanners, and other static analysis tools as plugins.
+
+> **Note:** Looking for plugin-specific configuration options, supported versions, or invocation
+> details? Each plugin lives in its own folder under
+> [qltysh/qlty/qlty-plugins](https://github.com/qltysh/qlty/tree/main/qlty-plugins) on GitHub —
+> check the plugin's `plugin.toml` and `README.md` for specifics.
+
+Each plugin consists of two components:
+
+1. A plugin definition in a TOML configuration file
+2. A results parser implemented in Rust
+
+Here is a simplified example plugin definition for [Ruff](https://github.com/astral-sh/ruff):
+
+```toml
+# plugin.toml for ruff
+config_version = "0"
+
+[plugins.definitions.ruff]
+runtime = "python"
+package = "ruff"
+file_types = ["python"]
+version_command = "ruff version"
+config_files = ["ruff.toml"]
+issue_url_format = "https://docs.astral.sh/ruff/rules/${rule}"
+
+[plugins.definitions.ruff.drivers.lint]
+script = "ruff check --exit-zero --output-format sarif --output-file ${tmpfile}  ${target}"
+success_codes = [0]
+output = "tmpfile"
+output_format = "sarif"
+batch = true
+```
+
+Gitleaks supports outputting results in the [SARIF](https://sarifweb.azurewebsites.net/) standard format, so a custom results parser is not needed. For tools which do not support SARIF, a results parser is implemented within the Qlty CLI and referenced by name.
+
+### Auto-Formatters
+
+Auto-formatters are a special type of plugin because they *rewrite* files rather than outputting findings. Therefore, they do not require results parsers.
+
+Here is an example of a plugin definition for the [shfmt](https://github.com/mvdan/sh) auto-formatter:
+
+```toml
+# plugin.toml for shfmt
+config_version = "0"
+
+[plugins.definitions.shfmt]
+package = "mvdan.cc/sh/v${major_version}/cmd/shfmt"
+runtime = "go"
+file_types = ["shell"]
+version_command = "shfmt --version"
+affects_cache = [".editorconfig"]
+
+[plugins.definitions.shfmt.drivers.format]
+script = "shfmt -w -s ${target}"
+success_codes = [0, 1]
+output = "rewrite"
+cache_results = true
+batch = true
+driver_type = "formatter"
+```
+
+Note the specification of `output = "rewrite"` and `driver_type = "formatter"`.
+
+---
+
+## Linter Extensions
+
+Linter extensions are additional packages or plugins that extend the functionality of base linter tools that Qlty uses. Depending on the linter, extensions can add:
+
+* Additional rule sets
+* Custom rules
+* Language support
+* Framework-specific checks
+* Additional parsers
+
+For example, ESLint has numerous plugins like `eslint-plugin-react`, `eslint-plugin-security`, and `eslint-plugin-jest` that add specialized rules for React development, security checks, and Jest testing, respectively.
+
+### Supported Package Managers
+
+Qlty supports linter extensions through the following package managers:
+
+* **NPM** (Node.js) - For JavaScript/TypeScript tools like ESLint, Stylelint, etc.
+* **RubyGems** (Ruby) - For Ruby tools like RuboCop, Standard, etc.
+* **PIP** (Python) - For Python tools like Ruff, Pylint, Bandit, etc.
+* **Composer** (PHP) - For PHP tools like PHP\_CodeSniffer, PHPStan, etc.
+
+### Managing linter extensions
+
+Qlty provides two mutually exclusive ways to configure linter extensions in your `qlty.toml` file: `extra_packages` and `package_file`.
+
+#### `extra_packages`
+
+The `extra_packages` property allows you to explicitly list additional packages that should be installed alongside the main linter package (including their versions).
+
+```toml
+# qlty.toml
+[[plugin]]
+name = "eslint"
+version = "8.57.0"
+extra_packages = [
+  "eslint-plugin-react@7.33.2",
+  "eslint-plugin-jest@27.6.0"
+]
+```
+
+This works best when your project contains a very limited set of extra packages (1-2), but does not scale well for moderate to complex projects.
+
+**Pros:**
+
+* Simple, direct specification
+* Version pinning
+* Works without existing package files
+
+**Cons:**
+
+* Duplicates existing dependency management (e.g. package.json)
+* May diverge from project dependencies
+* Supports external packages only (not, e.g. in Project packages)
+
+#### `package_file`
+
+The `package_file` property allows you to reference a package manager file (like `package.json` or `Gemfile`) to manage dependencies. Depending on your use case, you can point the `package_file` either at your project's main package file or at a specific file that contains the linter-related packages.
+
+```toml
+# Project package file
+[[plugin]]
+name = "eslint"
+version = "8.57.0"
+package_file = "package.json"
+```
+
+```toml
+# Linter package file
+[[plugin]]
+name = "eslint"
+version = "8.57.0"
+package_file = ".qlty/configs/package.json"
+```
+
+**Pros:**
+
+* Take advantage of package manager's dependency resolution
+* Consistent with project dependencies (if pointing to the main package file)
+
+**Cons:**
+
+* Project's main package file contains many dependencies
+
+##### `package_filters`
+
+When using `package_file`, you can use `package_filters` to selectively include only specific packages from the package file. This will cause Qlty to *filter* the packages in the package file and only install the ones that match the filters.
+
+This is most useful when you are pointing the `package_file` directive to your project's main package file, and you want to install only the linter-related packages. This can be used to speed up the installation of linters.
+
+> **Warning:** You can achieve the same goal as package\_filters by using a separate package file
+> which only contains linter dependencies. Because a separate package file's dependencies can be
+> fully resolved using a lock file, we prefer this option.
+
+```toml
+# qlty.toml
+[[plugin]]
+name = "eslint"
+version = "8.57.0"
+package_file = "package.json"
+package_filters = ["eslint"]
+```
+
+The `package_filters` option can offer a performance speed up or workaround issues installing the app dependencies at the tradeoff of additional complexity.
+
+### Lock files
+
+Package lock files (like `package-lock.json`, `Gemfile.lock`, `yarn.lock`) can impact how Qlty installs and manages linter extensions:
+
+* When using `package_file`, Qlty respects the locked versions for reliability
+* When using `package_file` with `package_filters`, the lock files are ignored
+* For `extra_packages`, lock files are not used and specific versions are installed directly
+
+### Limitations
+
+Qlty currently does not support:
+
+* **Private linter extensions** - Extensions from private Git repositories or private package registries that require authentication
+* **Git-based dependencies** - Extensions referenced directly as Git repositories
+* **Local file dependencies outside the repository** - Extensions referenced from paths outside the repository
+
+### Troubleshooting
+
+1. **Version conflicts**
+
+   If you see errors like "Dependency conflict" or "Incompatible versions", try:
+
+   * Aligning versions between your package file and extra\_packages
+   * Using `package_filters` to selectively include compatible packages
+
+2. **Missing extensions**
+
+   If a linter reports missing plugins or rules:
+
+   * Verify the extension is correctly specified in `extra_packages` or `package_file`.
+   * Check for typos in package names.
+   * Ensure compatible versions are specified.
+
+3. **Slow performance**
+
+   If linter installation becomes slow with extensions:
+
+   * Use either `package_filters` to filter installations, or create a separate package file for linter-related packages.
+
+4. **Configuration issues**
+
+   If the linter can't find the extension configuration:
+
+   * Ensure your configuration file correctly references the extensions.
+   * Check that the extension is properly installed.

package/dist/builtin/subagents/skills/qlty/references/quickstart.md

@@ -0,0 +1,110 @@
+# Getting Started with the Qlty CLI
+
+> **Source:** <https://docs.qlty.sh/cli/quickstart.md> (retrieved 2026-08-26).
+> Copied from the upstream page. Text is unchanged; the page's MDX wrappers (`<Steps>`,
+> `<CodeGroup>`, `<Accordion>`) and its embedded video iframes are rendered as plain Markdown
+> headings and code blocks. Fetch the live page via <https://docs.qlty.sh/llms.txt> when in doubt.
+
+## 1. Install the CLI
+
+First, install our CLI onto your local machine:
+
+```shell
+# macOS & Linux
+curl https://qlty.sh | sh
+```
+
+```shell
+# Windows
+powershell -c "iwr https://qlty.sh | iex"
+```
+
+Qlty CLI supports macOS and Linux on X64 and ARM64, with Windows support in development.
+
+### Alternative: Installing with verification
+
+We provide GitHub attestations powered by Sigstore that allow you to verify the authenticity of the Qlty CLI before installing it.
+
+**Prerequisites:** [GitHub CLI (`gh`)](https://cli.github.com/manual/installation) must be installed.
+
+**Example (macOS Apple Silicon):**
+
+```shell
+# Download the archive from https://github.com/qltysh/qlty/releases
+curl -LO https://github.com/qltysh/qlty/releases/latest/download/qlty-aarch64-apple-darwin.tar.xz
+
+# Verify the attestation
+gh attestation verify --owner qltysh qlty-aarch64-apple-darwin.tar.xz
+
+# Unpack and install
+tar -xJf qlty-aarch64-apple-darwin.tar.xz
+sudo mv qlty-aarch64-apple-darwin/qlty /usr/local/bin/
+```
+
+For other platforms, download the appropriate archive from [GitHub releases](https://github.com/qltysh/qlty/releases).
+
+Learn more: [GitHub artifact attestations documentation](https://docs.github.com/en/actions/concepts/security/artifact-attestations)
+
+## 2. Initialize your repository
+
+From your Git repository, run:
+
+```shell
+qlty init
+```
+
+This will generate a baseline configuration based on the file types within your project and store it as `.qlty/qlty.toml` in your repository.
+
+You can find more plugins with `qlty plugins list` and enable them with `qlty plugins enable [plugin]`.
+
+## 3. Identify code smells and review quality metrics
+
+Check the code quality (for [supported programming languages](https://docs.qlty.sh/languages.md)):
+
+```bash
+# Scan for code smells like duplication
+qlty smells --all
+```
+
+```bash
+# Review a summary of quality metrics
+qlty metrics --all --max-depth=2 --sort complexity --limit 10
+```
+
+## 4. Lint your project
+
+```bash
+# Run linters on changed files on your current branch
+qlty check
+```
+
+```bash
+# Run linters on all files
+qlty check --all
+```
+
+```bash
+# Run only the shellcheck linter on all files
+qlty check --all --filter=shellcheck
+```
+
+```bash
+# Run linters on the web/ folder
+qlty check web/
+```
+
+## 5. Auto-format your code
+
+```bash
+# Auto-format changed files on your current branch
+qlty fmt
+```
+
+## System requirements
+
+> **Source:** <https://docs.qlty.sh/cli/system-requirements.md> (retrieved 2026-08-26).
+
+The Qlty CLI runs on macOS and Linux on X64 and ARM64. Note that the quickstart page and the
+system-requirements page disagree about Windows: the quickstart says "Windows support is in
+development" while the system-requirements table lists Windows 11+ on X86 as supported. Verify
+Windows behavior against the live docs rather than relying on either statement.

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.16-alpha.6",
+  "version": "0.9.16-alpha.7",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.16-alpha.7] - 2026-08-26
+
+### Changed
+
+- Builtin `goal` and `ralph` stage prompts now carry a shared `code_quality_verification` section pointing stages at the `qlty` skill (or `skill: "qlty"` delegation) for linting, auto-formatting, complexity and duplication metrics, and code smells — weighted higher when the objective asks for verifiers or high code quality. It reaches the goal controller, goal orchestrator, goal reviewer, ralph orchestrator, and both ralph reviewers, alongside the existing end-to-end verification guidance. Repository-defined checks in AGENTS.md/CLAUDE.md, package scripts, and CI remain authoritative.
+- Builtin `goal` and `ralph` stage prompts now carry a shared `repository_intent` section instructing implementers and reviewers to infer maintainer and requesting-user conventions by mining repository behavior — git history (including `git log --show-signature`), merged PRs, issues and their comments, review comments, commit subjects and trailers, and CI/branch-protection config — for unwritten norms such as commit signing, message style and issue linking, changelog discipline, PR size and review etiquette. The dominant, recent, intentional pattern wins over accidental drift, the requesting user's own activity weighs highest, implementers match inferred conventions in delivered work, and reviewers report deviations as evidence-backed convention findings. Behavioral evidence fills contract gaps and never overrides the literal objective, acceptance criteria, or explicit AGENTS.md/CLAUDE.md guidance. It reaches the same call sites as the code-quality guidance: goal controller, goal orchestrator, goal reviewer, ralph orchestrator, and both ralph reviewers.
+- The `workflow` tool's routing guidance adds a repository-intent clause to the pre-launch architecture pass: for coding tasks, mine git history, merged PRs, issues, commits, and review comments before freezing authored workflow objectives and acceptance criteria so they capture unwritten conventions, weighing the requesting user's own activity highest; non-coding tasks mine their analogous available context sources (issue trackers, long-form docs, chat/comment threads, prior artifacts) the same way.
+
 ## [0.9.16-alpha.6] - 2026-08-26
 
 ### Changed

package/dist/builtin/workflows/builtin/goal-prompts.ts

@@ -1,11 +1,13 @@
 import {
   ACCEPTANCE_MATRIX_CONTRACT,
+  CODE_QUALITY_VERIFICATION_GUIDANCE,
   CONTRACT_FIDELITY_AUDIT,
   E2E_VERIFICATION_GUIDANCE,
   EVIDENCE_CLOSURE_POLICY,
   FINDINGS_CONSOLIDATION_CONTRACT,
   LITERAL_OBJECTIVE_CONTRACT,
   REGRESSION_EVIDENCE_CONTRACT,
+  REPO_INTENT_MINING_GUIDANCE,
   REVIEW_CODE_DELTA_CONTRACT,
   REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT,
   REVIEWER_INTERCOM_COORDINATION_PROTOCOL,
@@ -137,6 +139,8 @@ export function renderGoalContinuationPrompt(
     ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
     ["pr_handoff_policy", INTERMEDIATE_PR_HANDOFF_GUARDRAIL],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
     ["goal_guidelines", GOAL_CONTINUATION_REFERENCE],
     ["objective", ["Continue working toward the active goal using the ledger as authoritative state for status, receipts, reviews, blockers, reducer decisions, and lifecycle events.", `The same blocker must repeat for at least ${blockerThreshold} controller observations before blocked status is available.`, "Reviewer quorum plus the reducer decides completion from reviewers' authoritative stop_review_loop signals."].join("\n")],
   ]);
@@ -170,6 +174,8 @@ export function renderReviewerPrompt(args: {
     ["pr_handoff_policy", INTERMEDIATE_PR_HANDOFF_GUARDRAIL],
     ["auditability", RECEIPT_EXPECTATIONS],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
     ["final_action_policy", args.createPr ? "PR/MR/review creation is an authorized post-approval final action. If implementation and validation are proven and only that action remains, set goal_oracle_satisfied=true and stop_review_loop=true with no blocking findings, and record it as the remaining final action." : "PR/MR/review creation is not enabled; do not require or attempt it during review."],
     ["project_guidance", [
       "Apply AGENTS.md/CLAUDE.md and nearby code, test, script, config, generated-artifact, and CI conventions; specific project guidance overrides general guidance.",

package/dist/builtin/workflows/builtin/ralph-reviewer-prompt.ts

@@ -1,9 +1,11 @@
 import {
   ACCEPTANCE_MATRIX_CONTRACT,
+  CODE_QUALITY_VERIFICATION_GUIDANCE,
   E2E_VERIFICATION_GUIDANCE,
   EVIDENCE_CLOSURE_POLICY,
   LITERAL_OBJECTIVE_CONTRACT,
   REGRESSION_EVIDENCE_CONTRACT,
+  REPO_INTENT_MINING_GUIDANCE,
   REVIEW_CODE_DELTA_CONTRACT,
   REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT,
   REVIEWER_INTERCOM_COORDINATION_PROTOCOL,
@@ -49,6 +51,8 @@ export function renderRalphReviewerPrompt(args: {
     ["reviewer_coordination", REVIEWER_INTERCOM_COORDINATION_PROTOCOL],
     ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
     ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance(args.qaVideoPath)],
     ["evidence_closure", EVIDENCE_CLOSURE_POLICY],
     [

package/dist/builtin/workflows/builtin/ralph-runner.ts

@@ -10,10 +10,12 @@ import {
 import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
 import {
   ACCEPTANCE_MATRIX_CONTRACT,
+  CODE_QUALITY_VERIFICATION_GUIDANCE,
   CONTRACT_FIDELITY_AUDIT,
   FINDINGS_CONSOLIDATION_CONTRACT,
   LITERAL_OBJECTIVE_CONTRACT,
   REGRESSION_EVIDENCE_CONTRACT,
+  REPO_INTENT_MINING_GUIDANCE,
   SCOPE_DISCIPLINE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
   WORKTREE_DISCIPLINE_CONTRACT,
@@ -148,6 +150,8 @@ export async function runRalphWorkflow(
         ["project_setup", WORKER_PREFLIGHT_CONTRACT],
         ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
         ["qa_e2e_video", renderQaE2eVideoGuidance(qaVideoPath)],
+        ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+        ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
         [
           "delegation",
           [

package/dist/builtin/workflows/builtin/shared-prompts.ts

@@ -69,6 +69,31 @@ export const E2E_VERIFICATION_GUIDANCE = [
   "If E2E remains impractical, record the commands attempted, observed failure output, smallest missing prerequisite, and narrower validation run; an unattempted assumption is never valid grounds to skip.",
 ].join("\n");
 
+/**
+ * Code-quality verification is the lint/format/metrics/smells counterpart to
+ * E2E_VERIFICATION_GUIDANCE, and is included at the same call sites so goal and
+ * ralph stages — implementation, orchestrator, and reviewer alike — receive it.
+ */
+export const CODE_QUALITY_VERIFICATION_GUIDANCE = [
+  "For code-quality verification — linting, auto-formatting, complexity and duplication metrics, and code smells — use the qlty skill or delegate with `skill: \"qlty\"`; it drives one CLI across the repository's languages instead of ad-hoc per-tool linter invocations.",
+  "Weight this higher when the objective asks for verifiers or high code quality: enable the qlty plugins that fit this codebase, then run the check/format/metrics/smells loop and act on what it reports.",
+  "Repository-defined checks in AGENTS.md/CLAUDE.md, package scripts, and CI stay authoritative; qlty supplements them rather than replacing them, and its findings count as evidence only with the command and observed output recorded.",
+].join("\n");
+
+/**
+ * Repositories carry behavioral norms written docs never state — commit
+ * signing, message style, changelog discipline, review etiquette — and they
+ * are inferable from history. Included at the same goal/ralph call sites as
+ * the E2E and code-quality guidance so implementers match inferred
+ * conventions and reviewers check delivered work against them.
+ */
+export const REPO_INTENT_MINING_GUIDANCE = [
+  "Infer maintainer and requesting-user intent from repository behavior, not only written docs: mine git history (`git log`, `git log --show-signature`), merged PRs, issues and their comments, review comments, commit subjects and trailers, and CI/branch-protection config for unwritten conventions.",
+  "Read for commit-signing habits, commit-message style and issue linking, changelog discipline, PR size and stacking norms, review etiquette, formatting and lint norms, and branch naming. Prefer the dominant, recent, intentional pattern over accidental drift; when signals conflict, the requesting user's own commits, PRs, and comments weigh highest — different users of one repository keep different preferences.",
+  "Match inferred conventions in delivered work (for example, sign commits when the surrounding history is signed rather than skipping signing because no doc required it); in review, report deviations as convention findings backed by the mined evidence.",
+  "Behavioral evidence fills gaps where the contract is silent; it never overrides the literal objective, acceptance criteria, or explicit AGENTS.md/CLAUDE.md guidance, and it does not license new contract requirements.",
+].join("\n");
+
 export function renderE2eQaVideoReviewGuidance(
   knownVideoPath?: string,
 ): string {

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.16-alpha.6",
+  "version": "0.9.16-alpha.7",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/index.bundle.mjs

@@ -98572,6 +98572,19 @@ var E2E_VERIFICATION_GUIDANCE = [
   "If E2E remains impractical, record the commands attempted, observed failure output, smallest missing prerequisite, and narrower validation run; an unattempted assumption is never valid grounds to skip."
 ].join(`
 `);
+var CODE_QUALITY_VERIFICATION_GUIDANCE = [
+  'For code-quality verification — linting, auto-formatting, complexity and duplication metrics, and code smells — use the qlty skill or delegate with `skill: "qlty"`; it drives one CLI across the repository\'s languages instead of ad-hoc per-tool linter invocations.',
+  "Weight this higher when the objective asks for verifiers or high code quality: enable the qlty plugins that fit this codebase, then run the check/format/metrics/smells loop and act on what it reports.",
+  "Repository-defined checks in AGENTS.md/CLAUDE.md, package scripts, and CI stay authoritative; qlty supplements them rather than replacing them, and its findings count as evidence only with the command and observed output recorded."
+].join(`
+`);
+var REPO_INTENT_MINING_GUIDANCE = [
+  "Infer maintainer and requesting-user intent from repository behavior, not only written docs: mine git history (`git log`, `git log --show-signature`), merged PRs, issues and their comments, review comments, commit subjects and trailers, and CI/branch-protection config for unwritten conventions.",
+  "Read for commit-signing habits, commit-message style and issue linking, changelog discipline, PR size and stacking norms, review etiquette, formatting and lint norms, and branch naming. Prefer the dominant, recent, intentional pattern over accidental drift; when signals conflict, the requesting user's own commits, PRs, and comments weigh highest — different users of one repository keep different preferences.",
+  "Match inferred conventions in delivered work (for example, sign commits when the surrounding history is signed rather than skipping signing because no doc required it); in review, report deviations as convention findings backed by the mined evidence.",
+  "Behavioral evidence fills gaps where the contract is silent; it never overrides the literal objective, acceptance criteria, or explicit AGENTS.md/CLAUDE.md guidance, and it does not license new contract requirements."
+].join(`
+`);
 function renderE2eQaVideoReviewGuidance(knownVideoPath) {
   const target = knownVideoPath === undefined || knownVideoPath.length === 0 ? "Look for QA E2E video references in the goal ledger, implementation receipt, implementation notes, orchestrator report, or other review context artifacts." : `Known QA E2E video path for this run: ${knownVideoPath}`;
   return [
@@ -101269,6 +101282,8 @@ function renderGoalContinuationPrompt(ledger, ledgerPath, blockerThreshold, late
     ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
     ["pr_handoff_policy", INTERMEDIATE_PR_HANDOFF_GUARDRAIL],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
     ["goal_guidelines", GOAL_CONTINUATION_REFERENCE],
     ["objective", ["Continue working toward the active goal using the ledger as authoritative state for status, receipts, reviews, blockers, reducer decisions, and lifecycle events.", `The same blocker must repeat for at least ${blockerThreshold} controller observations before blocked status is available.`, "Reviewer quorum plus the reducer decides completion from reviewers' authoritative stop_review_loop signals."].join(`
 `)]
@@ -101294,6 +101309,8 @@ function renderReviewerPrompt(args) {
     ["pr_handoff_policy", INTERMEDIATE_PR_HANDOFF_GUARDRAIL],
     ["auditability", RECEIPT_EXPECTATIONS],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
     ["final_action_policy", args.createPr ? "PR/MR/review creation is an authorized post-approval final action. If implementation and validation are proven and only that action remains, set goal_oracle_satisfied=true and stop_review_loop=true with no blocking findings, and record it as the remaining final action." : "PR/MR/review creation is not enabled; do not require or attempt it during review."],
     ["project_guidance", [
       "Apply AGENTS.md/CLAUDE.md and nearby code, test, script, config, generated-artifact, and CI conventions; specific project guidance overrides general guidance.",
@@ -103490,6 +103507,8 @@ function renderRalphReviewerPrompt(args) {
     ["reviewer_coordination", REVIEWER_INTERCOM_COORDINATION_PROTOCOL],
     ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+    ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
     ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance(args.qaVideoPath)],
     ["evidence_closure", EVIDENCE_CLOSURE_POLICY],
     [
@@ -103884,6 +103903,8 @@ Read it before implementation or delegation because it is the primary current im
       ["project_setup", WORKER_PREFLIGHT_CONTRACT],
       ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
       ["qa_e2e_video", renderQaE2eVideoGuidance(qaVideoPath)],
+      ["code_quality_verification", CODE_QUALITY_VERIFICATION_GUIDANCE],
+      ["repository_intent", REPO_INTENT_MINING_GUIDANCE],
       [
         "delegation",
         [
@@ -123683,6 +123704,7 @@ var DEFAULT_PROMPT_GUIDANCE = [
   - Treat loop or stop-condition wording as a strong workflow signal, especially "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", "keep going until done", or any prompt that names an approval gate or evidence requirement.
   - Do not force-fit an installed workflow. When another graph better matches the task, write a task-specific TypeScript workflow inline. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
   - Before launching any workflow for a non-trivial task, perform a short workflow-architecture pass. Derive implementation lifecycle needs, whole-codebase research needs, independent slices, competing strategies, exact API/type/build contracts, schema or generated-artifact contracts, state transitions/lifecycle behavior, deterministic stop conditions, and required evidence. Enumerate implementation slices in this same pass, not a second planning ritual; give each slice its own objective, acceptance criteria, and gates, and require each to leave a buildable, testable repository state before the next slice. Use a compact internal coverage matrix: \`requirement/risk | required evidence | workflow/stage that produces it | gap\`. Add the topology row \`acyclic topology | node/edge sketch for branches and loops | architecture pass | unresolved back-edge\`. Unresolved material rows or back-edges must change the graph before launch.
+  - In that same pass, for coding tasks, infer repository intent from repo-level behavior before freezing objectives and acceptance criteria: mine git history (including \`git log --show-signature\`), merged PRs, issues, commits, and review comments for unwritten conventions — commit signing, message style and issue linking, changelog discipline, PR size and review norms — weighing the requesting user's own activity highest, so authored workflow contracts capture norms no doc states. For non-coding tasks, mine the analogous available context sources (issue trackers, long-form docs, chat/comment threads, prior artifacts) the same way. Inferred conventions fill contract gaps; they never override the stated objective or explicit repository docs.
   - In that architecture pass, sketch each branch, loop, and nested workflow boundary. Identify which stages repeat, require distinct tracked work for every iteration, name the current frontier before each repeat, reject self-edges and ancestor edges, compose nested workflows through \`ctx.workflow(...)\` boundaries rather than recursive \`run\` invocation, and preserve stable per-iteration identity and call order for resume/replay.
   - Compare candidate workflows by guarantees, not broad objectives: run one named workflow only when it covers the lifecycle and produces evidence for every material requirement/risk. A generic implementation workflow may cover the lifecycle without covering exact API/type/build contracts, schemas/generated artifacts, state transitions, or domain-specific gates. Do not treat "has reviewers" as proof that a task-specific risk is covered.
   - Use these routing signals without adding decorative stages: broad repository uncertainty → Fan-out-and-synthesize with repository-focused branches; independent slices → Fan-out-and-synthesize; plausible-but-wrong contract risk → Adversarial verification or a task-specific verification stage; competing architectures or implementations → Generate-and-filter or Tournament; an explicit repeat-until condition → Loop until done; implementation lifecycle → a task-specific worker/reviewer loop; exact API/build/schema requirements → dedicated deterministic gates.

package/docs/quickstart.md

@@ -241,6 +241,7 @@ Skills are reusable expert instructions. Trigger one with `/skill:<name>` follow
 | `tdd` | Test-first feature or bug work. | `/skill:tdd` |
 | `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks, framework-aware live review, and mount-failure recovery. | `/skill:impeccable` |
 | `playwright-cli` | Drive a real browser for end-to-end UI checks, screenshots, and reviewable proof videos. | `/skill:playwright-cli` |
+| `qlty` | Lint, auto-format, and measure code quality — complexity, duplication, and code smells — through one CLI across the repository's languages. | `/skill:qlty check this branch before I hand it off` |
 | `liteparse` | Pull text, tables, or values out of PDF, DOCX, PPTX, XLSX, and image files locally. | `/skill:liteparse` |
 | `show-me` | Explain a topic visually with concise diagrams, code-shape sketches, or focused HTML artifacts. HumanLayer, MIT licensed. | `/skill:show-me` |
 

package/docs/skills.md

@@ -81,6 +81,10 @@ The skill no longer recommends response prefilling, which returns an error on Cl
 
 The bundled `/skill:show-me` from [HumanLayer](https://github.com/humanlayer/skills) helps explain the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts. It is distributed under the MIT License.
 
+### Built-in code quality guidance
+
+The bundled `/skill:qlty` runs code-quality verification through the [qlty](https://qlty.sh) CLI, which drives 70+ linters, auto-formatters, and security scanners across 40+ languages: `qlty check` for linting, `qlty fmt` for auto-formatting, `qlty metrics` for complexity, lines, and cohesion, and `qlty smells` for duplication, deep nesting, and overly complex code. It triggers on requests for verifiers or high code quality and prefers one CLI over ad-hoc per-tool linter invocations. The skill directs the agent to [docs.qlty.sh/llms.txt](https://docs.qlty.sh/llms.txt) as the authoritative documentation index, tells it to enable the qlty plugins and linter extensions that fit the codebase before checking, and ships source-attributed reference excerpts beside `SKILL.md`. The CLI is not bundled; install it with `curl https://qlty.sh | bash` (macOS and Linux) or `powershell -c "iwr https://qlty.sh | iex"` (Windows), and keep `~/.qlty/bin` on `PATH`. Note that `qlty init` writes `.qlty/qlty.toml` into the repository. Offline, `qlty metrics` and `qlty smells` still work (built-in static analysis); `qlty check` and `qlty fmt` download plugins and runtimes on first use per repository and need network then.
+
 ## Skill Commands
 
 Skills register as `/skill:name` commands:

package/docs/workflows.md

@@ -231,6 +231,8 @@ The shapes, cheapest first:
 
 For every non-trivial workflow task, perform a short workflow-architecture pass before the first launch. Choose the execution shape before starting substantive work; reconnaissance already counts as inline execution. Derive the task's implementation lifecycle needs, whole-codebase research needs, independent work slices, competing strategies, exact API/type/build contracts, schema or generated-artifact contracts, state-transition/lifecycle behavior, deterministic stop conditions, and required evidence.
 
+For coding tasks, that pass also infers repository intent from repo-level behavior before objectives and acceptance criteria freeze: mine git history (including `git log --show-signature`), merged PRs, issues, commits, and review comments for unwritten conventions — commit signing, message style and issue linking, changelog discipline, PR size and review norms — weighing the requesting user's own activity highest so the authored contract captures norms no doc states. Non-coding tasks mine their analogous available context sources (issue trackers, long-form docs, chat or comment threads, prior artifacts) the same way. Inferred conventions fill contract gaps; they never override the stated objective or explicit repository docs.
+
 Use this compact coverage matrix internally (it may stay concise for a straightforward task), and let every unresolved material row change the graph choice:
 
 ```text
@@ -782,6 +784,8 @@ All six can run by name or as nested definitions. Prefer composition over copyin
 Goal persists the literal objective and immutable acceptance criteria in a run ledger, delegates implementation through bounded orchestrator turns, records receipts, and asks independent reviewers to inspect the current delta. A TypeScript reducer returns `complete`, `blocked`, or `needs_human` rather than trusting free-form completion claims. The complete Goal artifact directory — both its owning run segment and unique `artifact-<id>` segment — is a durable checkpoint. A fresh-ID continuation therefore reuses the source ledger, receipts, and review paths without rerunning replayed producer stages; loading that ledger preserves its existing records without duplicating replayed receipts or reviews. The model-visible `goal-ledger.json` continues to omit internal turn numbers, while a sibling `goal-ledger-state.json` preserves the complete turn-bearing state for lossless continuation reloads. A live chain of continuations also protects that original owner from retention pruning.
 
 Goal reviewers derive checks from the literal objective before consulting implementation receipts, inspect the actual checkout delta, and report commands, observed output, and file:line evidence rather than internal reasoning. Shared contracts cover acceptance-matrix traceability, contract-fidelity risks, end-to-end and QA-video evidence, and independent verification. `stop_review_loop` is the authoritative convergence signal: it remains `false` for P0–P2 findings, any `required_by_objective` finding, or unproven implementation/validation requirements; it becomes `true` only when independent evidence proves the objective and only non-blocking or authorized post-approval work remains. The deterministic reducer consumes that signal without reinterpreting free-form prose.
+Goal and Ralph stage prompts — orchestrator, implementation, and reviewer alike — also carry shared code-quality verification guidance that points at the `qlty` skill for linting, auto-formatting, complexity and duplication metrics, and code smells, weighted higher when the objective asks for verifiers or high code quality. Repository-defined checks in `AGENTS.md`/`CLAUDE.md`, package scripts, and CI stay authoritative.
+Both workflows also share repository-intent mining guidance: implementers and reviewers infer maintainer and requesting-user conventions from repository behavior — git history (including `git log --show-signature`), merged PRs, issues and their comments, review comments, commit subjects and trailers, and CI/branch-protection config — covering norms written docs rarely state, such as commit signing, message style and issue linking, changelog discipline, and review etiquette. The dominant, recent, intentional pattern wins over accidental drift, the requesting user's own activity weighs highest, implementers match the inferred conventions (an unsigned commit in a signed history is a miss, not a preference), and reviewers report deviations as convention findings. Behavioral evidence fills contract gaps; it never overrides the literal objective, acceptance criteria, or explicit `AGENTS.md`/`CLAUDE.md` guidance.
 Goal and Ralph share the same low-confidence finding re-verification and per-round convergence evidence, documented under [`ralph`](#ralph).
 
 | Input | Type | Required | Default | Description |