{
  "markdown": "# DRS · Diff Review System\n\n[![npm version](https://img.shields.io/npm/v/@diff-review-system/drs)](https://www.npmjs.com/package/@diff-review-system/drs)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Knowledge Map](https://img.shields.io/badge/knowledge-map-4056c7.svg)](https://manojlds.github.io/drs/)\n\n**Workflow-first AI code maintenance for reviews, changelogs, docs, and repository upkeep.**\n\nDRS runs agentic workflows for local diffs, GitHub PRs, and GitLab MRs. Review is a first-class packaged workflow, and the same workflow engine can update changelogs, fix review findings, refresh agent guidance, post comments, and compose project-specific maintenance pipelines — all powered by Pi SDK.\n\n## Review calibration benchmark\n\nThe frozen `benchmarks/review` fixtures form an end-to-end **DRS calibration suite**, not a\npure model benchmark: they exercise configuration, diff parsing, the packaged review agent,\nruntime, and output parsing. Live provider calls are deliberately opt-in:\n\n```bash\ndrs benchmark review --suite development-v1 --model provider/model --live\n# repeat --model to compare candidates; --repeat defaults to 1\n```\n\nCanonical JSON and derived Markdown are written to `out/review-benchmark` by default; names\nidentify the suite, isolated profile, repeat count, and the config/agent/model selection, and\nexisting artifacts are never overwritten. The runner pins `medium` thinking, disables the\ndescribe pass, rejects model-affecting environment overrides, and records requested and actual\nusage models. Runtime/model and structured-output parser failures are separate ineffective\nreviews, never clean passes. Metrics are per model and run-level; recall and precision remain\n`pending-adjudication` until a human makes semantic decisions from the JSON queue. Expected\nanswers never enter reviewer workspaces. Traces are not retained in this MVP.\n\n## Why teams like DRS\n\n- 🧭 **Workflow-first automation**: run packaged or project-defined DAG workflows with `drs workflow run`\n- 🎯 **First-class review workflows**: `local-review`, `github-pr-review`, and `gitlab-mr-review` are included out of the box\n- 🧠 **Flexible agent pipelines**: add your own project-specific `review/*` and `task/*` agents\n- 📦 **Pi-native runtime**: in-process execution by default, no separate runtime service required\n- ✍️ **Maintenance workflows**: update changelogs, fix review issues, refresh AGENTS.md-style guidance, and generate PR/MR descriptions\n- 📚 **Repository wikis**: generate and maintain a portable OKF v0.1 bundle, [knowledge site](https://manojlds.github.io/drs/), and [concept graph](https://manojlds.github.io/drs/graph.html)\n- 🧾 **Portable outputs**: inline comments, JSON artifacts, and GitLab code quality reports\n- 🎯 **Smart context compression**: dynamic budget sizing with `contextCompression.thresholdPercent`\n\n## Quick Links\n\n- [Repository Knowledge Map](https://manojlds.github.io/drs/)\n- [Interactive Concept Graph](https://manojlds.github.io/drs/graph.html)\n- [Quick Start](#quick-start)\n- [Upgrading From 4.1 To 5.0](https://github.com/manojlds/drs/blob/main/docs/MIGRATING_TO_5.md)\n- [Deployment Modes](#deployment-modes)\n- [Customization](#customization)\n- [Configuration](#configuration)\n- [Documentation](#documentation)\n\n## Quick Start\n\n### 1. Prerequisites\n\n- Node.js 22.19+\n- API key for your chosen model provider (Anthropic/OpenAI/ZhipuAI/etc.)\n\n### 2. Install DRS\n\n```bash\nnpm install -g @diff-review-system/drs\n```\n\nThis installs DRS with Pi runtime bundled — no separate runtime installation needed.\n\nThe npm package is a CLI application. Programmatic imports and deep imports from `dist/` are not a supported API.\n\n### 3. Initialize Project\n\n```bash\ncd your-project\ndrs init\n```\n\n### 4. Configure Environment\n\n```bash\n# Create a local env file\ntouch .env\n\n# Edit .env and set:\n# - GITLAB_TOKEN: Your GitLab access token (for GitLab MRs)\n# - GITHUB_TOKEN: Your GitHub access token (for GitHub PRs)\n# - Pi runtime runs in-process automatically (no remote server needed)\n# - Provider API Key: Set the API key for your chosen model provider\n#   - ANTHROPIC_API_KEY for Claude models (e.g., anthropic/claude-opus-4-5-20251101)\n#   - ZHIPU_API_KEY for GLM models (e.g., zhipuai/glm-4.7)\n#   - OPENAI_API_KEY for OpenAI models (e.g., openai/gpt-4)\n#   - See .env.example for all supported providers\n```\n\nDRS CLI now loads `.env` automatically from your current working directory.\n\n**Note**: DRS runs Pi in-process by default and does not require a remote runtime endpoint.\n\n### 5. Run Local Workflows\n\n```bash\n# Review unstaged changes\ndrs workflow run local-review\n\n# Review staged changes\ndrs workflow run local-review --input staged=true\n\n# Update CHANGELOG.md from local changes\ndrs workflow run local-changelog-update\n\n# Update CHANGELOG.md from the previous tag to the current tag, or explicit refs\ndrs workflow run tag-changelog-update --input from=v3.3.1 --input to=v4.0.0-rc.1\n\n# Fix issues from the latest saved local review artifact\ndrs workflow run local-fix-review-issues\n\n# Refresh AGENTS.md or equivalent repository guidance\ndrs workflow run local-update-agents-md\n\n# Generate or update one OKF v0.1 repository wiki bundle under wiki/\n# The command ends with a structural, usage, cost, and elapsed-time summary.\ndrs workflow run repository-wiki-sync\n\n# Verify the committed wiki delta state and OKF bundle without a model call\ndrs workflow run repository-wiki-check\n\n# Search the canonical wiki without a model or site build\ndrs wiki search \"temporal retry policy\" --limit 5\n\n# Build or locally serve the human-readable repository wiki website\ndrs wiki build --source wiki --output .drs/wiki-site\ndrs wiki serve --source wiki\n\n# Verify a deployed wiki site, graph, search, raw bundle, and linked assets\ndrs wiki check-site https://example.github.io/project/\n\n# To use a project-specific reviewer, configure review.agent in .drs/drs.config.yaml\n# then run the same workflow.\n```\n\n### Most-Used Commands\n\n| Goal | Command |\n|---|---|\n| Review local unstaged changes | `drs workflow run local-review` |\n| Review local staged changes | `drs workflow run local-review --input staged=true` |\n| Update changelog from local changes | `drs workflow run local-changelog-update` |\n| Update changelog from tag range | `drs workflow run tag-changelog-update` |\n| Fix issues from latest saved local review artifact | `drs workflow run local-fix-review-issues` |\n| Update AGENTS.md-style guidance | `drs workflow run local-update-agents-md` |\n| Generate or update repository wiki | `drs workflow run repository-wiki-sync` |\n| Check repository wiki without a model | `drs workflow run repository-wiki-check` |\n| Search repository wiki without a model | `drs wiki search <query...>` |\n| Build repository wiki website | `drs wiki build` |\n| Serve repository wiki website | `drs wiki serve` |\n| Verify deployed wiki website | `drs wiki check-site <url>` |\n| Update changelog and review local changes | `drs workflow run local-changelog-review` |\n| Review GitHub PR via workflow | `drs workflow run github-pr-review --input owner=<owner> --input repo=<repo> --input pr=<number>` |\n| Review GitLab MR via workflow | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number>` |\n| Show GitHub PR review context | `drs workflow run github-pr-show-changes --input owner=<owner> --input repo=<repo> --input pr=<number>` |\n| Show GitLab MR review context | `drs workflow run gitlab-mr-show-changes --input project=<group/repo> --input mr=<number>` |\n| Generate visual PR explainer artifact | `drs workflow run github-pr-visual-explain --input owner=<owner> --input repo=<repo> --input pr=<number>` |\n| Generate visual MR explainer artifact | `drs workflow run gitlab-mr-visual-explain --input project=<group/repo> --input mr=<number>` |\n| Generate visual local diff explainer | `drs workflow run local-visual-explain` |\n| Describe, review, and comment on GitHub PR via workflow | `drs workflow run github-pr-review --input owner=<owner> --input repo=<repo> --input pr=<number> --input describe=true --input post=true` |\n| Describe, review, and comment on GitLab MR via workflow | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number> --input describe=true --input post=true` |\n| Describe, review, comment, and generate visual PR explainer | `drs workflow run github-pr-review --input owner=<owner> --input repo=<repo> --input pr=<number> --input describe=true --input post=true --input visual=true` |\n| Review GitLab MR and write Code Quality report | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number> --input codeQuality=true` |\n| Describe/review/comment GitLab MR and write Code Quality report | `drs workflow run gitlab-mr-review --input project=<group/repo> --input mr=<number> --input describe=true --input post=true --input codeQuality=true` |\n| Generate PR description | `drs workflow run github-pr-describe --input owner=<owner> --input repo=<repo> --input pr=<number>` |\n| Generate MR description | `drs workflow run gitlab-mr-describe --input project=<group/repo> --input mr=<number>` |\n| Post or update a PR comment | `drs workflow run github-pr-post-comment --input owner=<owner> --input repo=<repo> --input pr=<number> --input body=\"...\" --input marker=<id>` |\n| Post or update an MR comment | `drs workflow run gitlab-mr-post-comment --input project=<group/repo> --input mr=<number> --input body=\"...\" --input marker=<id>` |\n| Run any configured agent | `drs run-agent task/docs-updater --prompt \"Update release notes\"` |\n| Run a configured workflow | `drs workflow run release-notes --input-file diff=.drs/diff.md` |\n| Run the default project workflow | `drs workflow run` |\n| List available workflows | `drs workflow list` |\n| Show workflow inputs and steps | `drs workflow show github-pr-review` |\n\n## Deployment Modes\n\n### Mode 1: Local CLI\n\nReview code locally before pushing:\n\n```bash\n# Review local changes\ndrs workflow run local-review\n\n# Review specific GitLab MR\ndrs workflow run gitlab-mr-review --input project=my-org/my-repo --input mr=123 --input describe=true --input post=true\n\n# Review specific GitHub PR\ndrs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456 --input describe=true --input post=true\n\n# Review and generate a visual explainer artifact\ndrs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456 --input describe=true --input post=true --input visual=true\n\n# Review local staged changes\ndrs workflow run local-review --input staged=true\n\n# Override model/agent behavior through config, then run workflows\ndrs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456\n\n# Use ultrathink with workflows\ndrs workflow run github-pr-review --input owner=octocat --input repo=hello-world --input pr=456 --ultrathink\n\n# Show the diff context passed to agents\ndrs workflow run github-pr-show-changes --input owner=octocat --input repo=hello-world --input pr=456\n\n# Show diff context for a single file\ndrs workflow run github-pr-show-changes --input owner=octocat --input repo=hello-world --input pr=456 --input file=src/app.ts\n\n# Generate self-contained HTML visual explainers\ndrs workflow run local-visual-explain\ndrs workflow run github-pr-visual-explain --input owner=octocat --input repo=hello-world --input pr=456\ndrs workflow run gitlab-mr-visual-explain --input project=my-org/my-repo --input mr=123\n\n# Generate PR/MR descriptions on demand\ndrs workflow run github-pr-describe --input owner=octocat --input repo=hello-world --input pr=456\ndrs workflow run github-pr-describe --input owner=octocat --input repo=hello-world --input pr=456 --input post=true\ndrs workflow run gitlab-mr-describe --input project=my-org/my-repo --input mr=123\ndrs workflow run gitlab-mr-describe --input project=my-org/my-repo --input mr=123 --input post=true\n\n# Post or update a single marked PR/MR comment\ndrs workflow run github-pr-post-comment --input owner=octocat --input repo=hello-world --input pr=456 --input body=\"Release notes are ready.\" --input marker=release-notes\ndrs workflow run gitlab-mr-post-comment --input project=my-org/my-repo --input mr=123 --input body=\"Release notes are ready.\" --input marker=release-notes\n```\n\n### Mode 2: GitLab CI/CD\n\nAdd to your `.gitlab-ci.yml`:\n\n```yaml\ninclude:\n  - remote: 'https://raw.githubusercontent.com/manojlds/drs/main/src/ci/gitlab-ci.template.yml'\n\nai_review:\n  extends: .drs_review\n  stage: review\n```\n\n**See [GitLab CI Integration Guide](docs/GITLAB_CI_INTEGRATION.md)** for:\n- Pi-based CI setup examples\n- Parallel pipeline strategies (child pipelines, DAG with needs)\n- Complete examples that don't block your main pipeline\n\n### Mode 3: GitHub Actions\n\nDRS includes a **secure, pre-configured workflow** at `.github/workflows/pr-review.yml` with built-in protection against external PR abuse.\n\n**Security Features**:\n- ✅ **Auto-review for trusted contributors** with write access using same-repository branches\n- ⏸️ **Manual approval required** for forked and external contributions\n- 🔒 **Trusted base checkout** prevents external PR code, configuration, agents, and install scripts from executing\n- 🔑 **Split credentials** keep model generation read-only and move GitHub writes into a separate deterministic artifact-posting job\n- 🏷️ **Label-based cost approval** with the `safe-to-review` label\n\n**Quick Setup**:\n\n1. **Configure API Keys** in repository Settings → Secrets:\n   - `ANTHROPIC_API_KEY` (for Claude models), or\n   - `ZHIPU_API_KEY` (for ZhipuAI GLM models), or\n   - `OPENAI_API_KEY` (for OpenAI models)\n\n2. **Set up External PR Protection** (Important!):\n   - Create GitHub Environment: `external-pr-review`\n   - Add required reviewers (maintainers)\n   - Create `safe-to-review` label\n   - Prevent self-review and administrator bypass where repository policy allows\n\n**See [GitHub Actions Integration Guide](docs/GITHUB_ACTIONS_INTEGRATION.md)** for:\n- Complete setup instructions\n- External PR security configuration\n- Model configuration options\n- Troubleshooting tips\n\n**See [External PR Security Guide](docs/EXTERNAL_PR_SECURITY.md)** for:\n- Detailed security setup\n- Cost protection mechanisms\n- Maintainer workflow\n- Attack prevention strategies\n\n### Visual PR Explainer Artifacts\n\nDRS includes visual explainer workflows that generate a self-contained HTML page for reviewers:\n\n- `github-pr-visual-explain` writes `.drs/visual-pr-explainer.html` by default.\n- `gitlab-mr-visual-explain` writes `.drs/visual-mr-explainer.html` by default.\n- `local-visual-explain` writes `.drs/visual-local-explainer.html` by default.\n\nThe main review workflows also support visual artifacts:\n\n```bash\ndrs workflow run github-pr-review \\\n  --input owner=octocat \\\n  --input repo=hello-world \\\n  --input pr=456 \\\n  --input describe=true \\\n  --input post=true \\\n  --input visual=true\n```\n\nThe built-in `visual/pr-explainer` agent includes DRS-specific HTML generation guidance out of the box. Override `.drs/agents/visual/pr-explainer/agent.md` or configure `agents.overrides.visual/pr-explainer` to tune the output for your project. If you install an external `visual-explainer` skill, add it through `agents.overrides.visual/pr-explainer.skills` so the agent loads those richer templates and design rules.\n\nTo publish the generated page from GitHub Actions, upload it as an artifact:\n\n```yaml\n- name: Generate visual explainer\n  env:\n    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n    OPENCODE_API_KEY: ${{ secrets.DRS_PROVIDER_API_KEY }}\n  run: |\n    node dist/cli/index.js workflow run github-pr-review \\\n      --input owner=\"${{ github.event.repository.owner.login }}\" \\\n      --input repo=\"${{ github.event.repository.name }}\" \\\n      --input pr=\"${{ github.event.pull_request.number }}\" \\\n      --input describe=true \\\n      --input post=true \\\n      --input visual=true \\\n      --input visualOutputPath=\".drs/visual-pr-explainer.html\"\n\n- uses: actions/upload-artifact@v4\n  with:\n    name: visual-pr-explainer\n    path: .drs/visual-pr-explainer.html\n```\n\n## GitLab Code Quality Reports\n\nDRS can generate GitLab-compatible code quality reports that integrate seamlessly with GitLab CI/CD. This provides an alternative (or complement) to inline MR comments.\n\n### Why Use Code Quality Reports?\n\n**Benefits:**\n- **Native GitLab Integration**: Issues appear in the MR widget and Changes tab\n- **Better UX**: Issues marked with symbols in the code gutter\n- **All Severities**: Include MEDIUM/LOW issues without cluttering MR discussions\n- **Historical Tracking**: GitLab tracks quality trends over time\n- **Non-intrusive**: Doesn't create discussion threads\n\n**When to Use:**\n- Use `describe=true` to update the PR/MR description before review\n- Use `post=true` for review issues requiring discussion\n- Use **code quality reports** (`--code-quality-report`) for comprehensive static analysis\n- Use **both together** for maximum visibility\n\n### CLI Usage\n\n```bash\n# Use workflow-based MR review with comments\ndrs workflow run gitlab-mr-review --input project=my-org/my-repo --input mr=123 --input describe=true --input post=true\n\n# For code quality artifacts, enable codeQuality\ndrs workflow run gitlab-mr-review --input project=my-org/my-repo --input mr=123 --input codeQuality=true\n```\n\n### GitLab CI Integration\n\nAdd to your `.gitlab-ci.yml`:\n\n```yaml\ncode_review:\n  stage: review\n  image: node:20-alpine\n  before_script:\n    - npm install -g @diff-review-system/drs\n  script:\n    - drs workflow run gitlab-mr-review --input project=$CI_PROJECT_PATH --input mr=$CI_MERGE_REQUEST_IID --input describe=true --input post=true\n  only:\n    - merge_requests\n```\n\nThe code quality report will appear in:\n1. **MR Overview**: Widget showing new/resolved issues\n2. **Changes Tab**: Gutter symbols on problematic lines\n3. **Pipeline Tab**: Quality trend graphs\n\n### Report Format\n\nDRS generates reports in GitLab's CodeClimate-compatible format:\n\n```json\n[\n  {\n    \"description\": \"Query uses string concatenation. Use parameterized queries instead.\",\n    \"check_name\": \"drs-security\",\n    \"fingerprint\": \"7815696ecbf1c96e6894b779456d330e\",\n    \"severity\": \"blocker\",\n    \"location\": {\n      \"path\": \"src/api/users.ts\",\n      \"lines\": { \"begin\": 42 }\n    }\n  }\n]\n```\n\n**Severity Mapping:**\n- CRITICAL → blocker\n- HIGH → critical\n- MEDIUM → major\n- LOW → minor\n\nFor more details, see [GitLab Code Quality Documentation](https://docs.gitlab.com/ci/testing/code_quality/).\n\n## Pi Runtime Configuration\n\nDRS runs on Pi SDK as the sole review runtime.\n\n### In-Process Runtime (Default)\n\nBy default, DRS starts Pi runtime in-process:\n\n```bash\ndrs workflow run local-review\n```\n\n### Runtime Mode\n\nDRS uses Pi in-process runtime only.\n\n## Architecture\n\nDRS uses Pi runtime wiring with markdown-based agent definitions. Agents are addressed by fully qualified ids: `<namespace>/<name>`.\n\n```\n.pi/\n└── agents/\n    └── review/\n        └── unified-reviewer.md  # Packaged unified reviewer\n```\n\nBuilt-in agent definitions live under `.pi/agents`.\n\n## Customization\n\n> **Full guide**: See [docs/CUSTOM_AGENTS.md](docs/CUSTOM_AGENTS.md) for complete documentation on custom agents, skills, context, per-agent tools, and configuration examples.\n\n### Override Default Agents\n\nCreate custom agents in your project:\n\n```bash\n# Override the packaged unified reviewer\nmkdir -p .drs/agents/review/unified-reviewer\ncat > .drs/agents/review/unified-reviewer/agent.md << 'EOF'\n---\ndescription: Custom unified reviewer\nmodel: anthropic/claude-sonnet-4-5-20250929\n---\n\nYou are a reviewer for this specific application.\n\n## Project-Specific Rules\n[Add your custom rules here]\nEOF\n```\n\n### Add Context Without Overriding\n\nAdd project-specific guidance to a built-in agent without replacing its prompt:\n\n```bash\nmkdir -p .drs/agents/review/unified-reviewer\ncat > .drs/agents/review/unified-reviewer/context.md << 'EOF'\n# Unified Reviewer Context\n- Flag functions over 200 lines as HIGH\n- We use TypeORM — flag raw SQL queries\nEOF\n```\n\n### Global Project Context\n\n`.drs/context.md` is injected into **every** agent's prompt:\n\n```markdown\n# Project Context\nNode.js microservice using Express + TypeORM.\nPrioritize correctness, safety, and clarity.\n```\n\n### Create New Custom Agents\n\nAdd review agents that don't exist in the built-in set:\n\n```bash\nmkdir -p .drs/agents/review/api-reviewer\ncat > .drs/agents/review/api-reviewer/agent.md << 'EOF'\n---\ndescription: REST API contract reviewer\ntools:\n  Read: true\n  Grep: true\n---\nReview REST API changes for backward compatibility.\nEOF\n```\n\nThen select it in config: `review.agent: review/api-reviewer`\n\nFor non-review work, create agents in any namespace and run them directly:\n\n```bash\nmkdir -p .drs/agents/task/docs-updater\ncat > .drs/agents/task/docs-updater/agent.md << 'EOF'\n---\ndescription: Documentation update assistant\ntools:\n  Read: true\n  Grep: true\n---\nUpdate documentation based on the user's request.\nEOF\n\ndrs run-agent task/docs-updater --prompt \"Summarize the latest API changes\"\n```\n\nYou can also put the run prompt and output behavior in config, then invoke only the agent id:\n\n```yaml\nagents:\n  overrides:\n    task/docs-updater:\n      run:\n        prompt: \"Summarize the latest API changes\"\n        output: .drs/docs-summary.json\n        json: true\n```\n\n```bash\ndrs run task/docs-updater\n```\n\n### Configure Workflows\n\nWorkflows compose agents and built-in actions into a dependency graph. They are useful when one agent produces an artifact that another agent or action consumes.\n\nDefine reusable project workflows in `.drs/workflows/*.yaml`.\n\n```yaml\nname: release-notes\ninputs:\n  diff:\n    file: .drs/diff.md\nnodes:\n  summarize:\n    agent: task/change-summarizer\n    input: |\n      Summarize these changes:\n\n      {{inputs.diff}}\n    output: summary\n  write-summary:\n    action: write\n    needs: [summarize]\n    input: \"{{artifacts.summary}}\"\n    writes: RELEASE_NOTES.md\n```\n\n```bash\ndrs workflow run release-notes\ndrs workflow run # uses workflow.default from .drs/drs.config.yaml when configured\ndrs workflow run release-notes --input-file diff=changes.md --json\n```\n\nSelect the default workflow in `.drs/drs.config.yaml`:\n\n```yaml\nworkflow:\n  default: local-changelog-review\n```\n\nSee [docs/WORKFLOWS.md](docs/WORKFLOWS.md) for the full workflow configuration reference.\n\n### Temporal Execution (Experimental)\n\nDRS can dispatch workflows through Temporal. The workflow YAML remains the source of truth; DRS compiles it to a JSON plan, runs deterministic scheduling in a generic Temporal workflow, and executes workflow nodes as Temporal activities.\n\nConfigure Temporal in `.drs/drs.config.yaml` when the defaults do not match your environment:\n\n```yaml\ntemporal:\n  address: localhost:7233\n  namespace: default\n  taskQueue: drs-workflows\n  workflowIdPrefix: drs\n```\n\nStart a worker in the repository where node activities should execute:\n\n```bash\ndrs temporal worker\n```\n\nRun a supported workflow through Temporal:\n\n```bash\ndrs workflow run local-review --executor temporal\ndrs workflow run github-pr-show-changes --executor temporal --input owner=octocat --input repo=hello-world --input pr=456\ndrs workflow run local-review --executor temporal --no-wait\ndrs workflow run local-review --executor temporal --trace\n```\n\nFor a safe local smoke test that does not require model or platform credentials, run the packaged control-flow workflow:\n\n```bash\ndrs workflow run temporal-control-smoke --executor temporal --input mode=loop\ndrs workflow run temporal-control-smoke --executor temporal --input mode=pass\ndrs workflow run temporal-control-smoke --executor temporal --input mode=end\n```\n\nTemporal mode is experimental. It supports DAG workflows and DRS control-flow nodes (`loop`, `switch`, `passThrough`, `end`), structured logs, workflow queries, cancellation state, trace artifacts, and side-effect retry safeguards. See [docs/TEMPORAL.md](docs/TEMPORAL.md) for worker deployment, Temporal UI troubleshooting, and opt-in smoke coverage. See [TEMPORAL_EXECUTION_PLAN.md](TEMPORAL_EXECUTION_PLAN.md) for the rollout plan.\n\n### Configure Review Behavior\n\nEdit `.drs/drs.config.yaml`:\n\n```yaml\nagents:\n  default:\n    model: zhipuai/glm-4.7\n    skills: []\n  namespaces:\n    review:\n      model: anthropic/claude-sonnet-4-5-20250929\n    task:\n      model: openai/gpt-4o\n  overrides:\n    task/docs-updater:\n      run:\n        promptFile: prompts/docs-update.md\n        output: .drs/docs-update.json\n        json: true\n\nreview:\n  agent: review/unified-reviewer\n  ignorePatterns:\n    - \"*.test.ts\"\n    - \"*.md\"\n  describe:\n    enabled: true\n  cursorFixLinks:\n    enabled: false\n    # workspace: my-repo\n\ncontextCompression:\n  enabled: true\n  # Dynamic budget = thresholdPercent × model context window\n  thresholdPercent: 0.15\n  # Fallback if model context window metadata is unavailable\n  maxTokens: 32000\n  softBufferTokens: 1500\n  hardBufferTokens: 1000\n\ndescribe:\n  model: zhipuai/glm-4.7\n```\n\nNotes:\n- Review orchestration is workflow-first in v4: use `drs workflow run ...` for local/PR/MR review.\n- `describe.model` is used by describe workflows and by review-driven descriptions.\n- `contextCompression.thresholdPercent` sets a context-window-aware budget (e.g. `0.15` means 15%).\n- `contextCompression.maxTokens` is the fallback cap when context window metadata is unavailable.\n- `review.agent` selects the single authoritative review agent.\n- Packaged built-in review agent ID: `review/unified-reviewer`.\n- Add a project-specific review agent under `.drs/agents/review/<name>/agent.md` and select it with `review.agent`.\n- Unknown agent names fail fast with a validation error before review execution starts.\n\n### Model Pricing Overrides (Cost Reporting)\n\nIf your provider/model reports token usage but returns `$0.0000` cost, you can set pricing manually.\nValues are in **USD per 1M tokens**.\n\n```yaml\npricing:\n  models:\n    opencode/glm-5-free:\n      input: 0.0\n      output: 0.0\n      cacheRead: 0.0\n      cacheWrite: 0.0\n```\n\nYou can also set pricing directly under `pi.provider.<name>.models[].cost` for custom providers.\n\n### Custom Provider Model Metadata (Context Window, Limits, Compat)\n\nIf you define custom providers/models under `pi.provider.<name>`, you can set metadata used by DRS:\n\n- `contextWindow`: used for dynamic compression sizing when `thresholdPercent` is enabled\n- `maxTokens`: model output limit hint\n- `cost`: token pricing override (USD per 1M tokens)\n- `compat`: OpenAI compatibility overrides passed through to Pi runtime (for proxy quirks)\n  - set at provider level (`pi.provider.<name>.compat`) to apply defaults to all models\n  - set at model level (`pi.provider.<name>.models[].compat`) for per-model overrides\n\n```yaml\npi:\n  provider:\n    my-provider:\n      baseUrl: \"https://api.example.com/v1\"\n      api: \"openai-completions\"\n      # apiKey accepts env var name, literal key, or !command\n      apiKey: \"MY_PROVIDER_API_KEY\"\n      # Optional provider-wide defaults for all models\n      compat:\n        supportsStore: false\n      models:\n        - id: \"my-model\"\n          name: \"My Model\"\n          contextWindow: 200000\n          maxTokens: 8192\n          cost:\n            input: 0.50\n            output: 1.50\n            cacheRead: 0.00\n            cacheWrite: 0.00\n          # Optional per-model override\n          compat:\n            supportsUsageInStreaming: false\n            maxTokensField: \"max_tokens\"\n```\n\n> Note: For built-in providers/models, context window metadata comes from the runtime model registry.\n\n### Context Compression (Large Diff Handling)\n\nDRS trims large diffs before sending them to models, so reviews stay within context limits.\n\n- `thresholdPercent` enables **dynamic budgeting** based on model context window.\n- `maxTokens` is used as fallback when context metadata is missing.\n- Generated files and deletion-only hunks can be auto-excluded from prompt context.\n\nExample:\n\n```yaml\ncontextCompression:\n  enabled: true\n  thresholdPercent: 0.15 # 15% of model context window\n  maxTokens: 32000       # fallback cap\n  softBufferTokens: 1500\n  hardBufferTokens: 1000\n  tokenEstimateDivisor: 4\n  summaryThresholdMultiplier: 3 # use summary-only context above hard limit * multiplier\n```\n\n### Runtime Timeouts and Provider Retry\n\nTo prevent hung reviews, configure runtime-level call/stream timeouts and provider request retry limits:\n\n```yaml\npi:\n  runtime:\n    operationTimeoutMs: 300000      # timeout for create/prompt/messages calls\n    streamTimeoutMs: 900000         # total timeout while waiting for agent completion\n    streamPollIntervalMs: 2000      # polling cadence for session messages\n  retry:\n    provider:\n      timeoutMs: 45000              # provider request timeout passed to Pi SDK\n      maxRetries: 2                 # provider request retries (Pi SDK)\n      maxRetryDelayMs: 15000        # max backoff delay between retries\n```\n\nEnvironment variables override runtime timeout fields:\n\n- `DRS_RUNTIME_OPERATION_TIMEOUT_MS`\n- `DRS_RUNTIME_STREAM_TIMEOUT_MS`\n- `DRS_RUNTIME_STREAM_POLL_INTERVAL_MS`\n\n### Pi-Native Skill Discovery\n\nDRS auto-discovers skills from these directories when `agents.paths.skills` is not set:\n\n1. `.drs/skills` (project-level overrides)\n2. `.agents/skills` (legacy/shared project skills)\n3. `.pi/skills` (Pi-native skills)\n\nIf the same skill name exists in multiple locations, earlier paths win (`.drs` > `.agents` > `.pi`).\n\nExample layout:\n\n```text\n.drs/skills/\n  secure-fetch/SKILL.md        # Project override (preferred)\n.agents/skills/\n  secure-fetch/SKILL.md        # Legacy/shared fallback\n.pi/skills/\n  secure-fetch/SKILL.md        # Pi-native fallback\n  db-indexing/SKILL.md         # Additional Pi-native skill\n```\n\nTo force a single custom skills directory, set `agents.paths.skills`:\n\n```yaml\nagents:\n  paths:\n    skills: config/agent-skills\n```\n\n## Review Domains\n\n### Security Analysis\n\nFocuses on:\n- OWASP Top 10 vulnerabilities\n- Injection attacks (SQL, XSS, Command)\n- Authentication/authorization issues\n- Sensitive data exposure\n- Security misconfigurations\n\n### Quality Analysis\n\nReviews:\n- Design patterns and anti-patterns\n- Code complexity\n- DRY violations\n- Error handling\n- Code smells\n\n### Style Analysis\n\nChecks:\n- Naming conventions\n- Code formatting\n- Documentation quality\n- Type safety (TypeScript)\n- Unused code\n\n### Performance Analysis\n\nAnalyzes:\n- Algorithmic complexity\n- Database query efficiency\n- Memory management\n- Caching opportunities\n- Concurrency issues\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Required (depending on platform)\nGITLAB_TOKEN=glpat-xxx              # For GitLab MR reviews\nGITHUB_TOKEN=ghp-xxx                # For GitHub PR reviews\n\n# Provider API Keys (set the one for your chosen model provider)\nANTHROPIC_API_KEY=sk-ant-xxx        # For Anthropic Claude models\nZHIPU_API_KEY=xxx                   # For ZhipuAI GLM models\nOPENAI_API_KEY=sk-xxx               # For OpenAI models\n\n# Optional\nGITLAB_URL=https://gitlab.com\nDRS_DEFAULT_MODEL=anthropic/claude-sonnet-4-5-20250929\nDRS_AGENT_REVIEW_UNIFIED_REVIEWER_MODEL=anthropic/claude-opus-4-5-20251101\n# Configure the reviewer in .drs/drs.config.yaml via review.agent.\n# DRS_REVIEW_AGENT overrides it; single-valued REVIEW_AGENTS is deprecated.\nREVIEW_THINKING_LEVEL=medium              # Reasoning effort: off, minimal, low, medium, high, xhigh\n```\n\n### Configuration Files\n\n1. `.drs/drs.config.yaml` - DRS-specific configuration\n2. `.gitlab-review.yml` - Alternative location\n3. Environment variables (for provider credentials and platform tokens)\n\n## Development\n\nQuick start for local development:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Run the CLI from TypeScript once\nnpm run dev:cli -- workflow list\n\n# Watch-mode CLI entrypoint\nnpm run dev -- workflow list\n```\n\n## Requirements\n\n- Node.js 22.19+\n- API key for your selected provider (Anthropic/OpenAI/ZhipuAI/etc.)\n- GitLab access token (for GitLab MR reviews)\n- GitHub access token (for GitHub PR reviews)\n- Git 2.30+ (for local mode)\n\nPi runtime is included as a dependency — no separate installation or server needed.\n\n## License\n\nApache-2.0\n\n## Documentation\n\n- [5.0 Migration Guide](https://github.com/manojlds/drs/blob/main/docs/MIGRATING_TO_5.md) - Required changes when upgrading from DRS 4.1\n- [GitLab CI Integration Guide](docs/GITLAB_CI_INTEGRATION.md) - Complete guide for GitLab CI/CD setup\n- [GitHub Actions Integration Guide](docs/GITHUB_ACTIONS_INTEGRATION.md) - GitHub Actions workflow setup\n- [External PR Security Guide](docs/EXTERNAL_PR_SECURITY.md) - Security controls for external contributors\n- [Custom Agents & Skills Guide](docs/CUSTOM_AGENTS.md) - Custom agents, context, skills, and per-agent tools\n- [Workflows Guide](docs/WORKFLOWS.md) - Compose agents and actions into dependency graphs\n- [Release Guide](docs/RELEASING.md) - Atomic release tagging and tag-bound npm publication\n- [Model Overrides Guide](docs/MODEL_OVERRIDES.md) - Per-agent model configuration\n- [Pi Documentation](https://github.com/badlogic/pi-mono)\n\n## Contributing\n\nContributions welcome! Please read the contributing guidelines first.\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/manojlds/drs/issues)\n- Discussions: [GitHub Discussions](https://github.com/manojlds/drs/discussions)\n- Repository: [github.com/manojlds/drs](https://github.com/manojlds/drs)\n",
  "bytes": 33405,
  "sha": "ccd659e03d9548e2062d2474aae455b4f5c199b3291c3457493a66ea51c6a0d9",
  "repo_slug": "manojlds/drs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_manojlds_drs_wiki_index_md_0ecf3001/readme"
}