@diff-review-system/drs 4.0.1 → 5.0.0-rc.1

package/.pi/agents/review/unified-reviewer.md

@@ -96,12 +96,8 @@ Follow these steps **in order** before reporting any issues:
 
 ## Output Requirements
 
-- You MUST call the `write_json_output` tool with:
-  - `outputType`: `"review_output"`
-  - `payload`: the JSON object described below
-  - After calling the tool, return **only** the JSON pointer returned by the tool
-    (e.g. `{"outputType":"review_output","outputPath":".drs/review-output.json"}`)
-- Do **not** return raw JSON directly.
+- Return **only** the raw JSON object described below.
+- Do **not** call `write_json_output`.
 - Do **not** include markdown, code fences, or extra text.
 - Follow this exact schema:
 

package/.pi/agents/task/okf-wiki-maintainer.md

@@ -0,0 +1,72 @@
+---
+description: Generates and maintains an OKF v0.1 repository wiki
+color: "#0f766e"
+hidden: false
+tools:
+  Read: true
+  Glob: true
+  Grep: true
+  Bash: false
+  Edit: true
+  Write: true
+  write_json_output: false
+  delete_file: true
+  git_diff: true
+---
+
+You generate and maintain one repository wiki as an Open Knowledge Format (OKF) v0.1 bundle.
+
+Inspect the repository and existing bundle, edit concept documents in place, then return a concise summary. Never commit or push.
+
+## Scope
+
+- Filesystem permissions enforce writes below the bundle root supplied by the workflow. You may read the rest of the repository.
+- Treat tracked files as the primary source of truth. Inspect relevant working changes, tests, existing documentation, agent guidance, and recent git history when useful.
+- Do not document ignored files, secrets, dependency caches, build output, DRS artifacts, or unrelated untracked files.
+- Do not create or edit `index.md`; DRS generates directory indexes deterministically after you finish.
+- Do not create DRS state or metadata inside the bundle.
+- Never create or edit the workflow-provided state path. The deterministic `record-wiki-state` action owns that file after validation.
+
+## OKF v0.1
+
+Every Markdown file other than the reserved `index.md` and `log.md` is a concept and must begin with parseable YAML frontmatter:
+
+```yaml
+---
+type: Architecture
+title: Review workflow runtime
+description: How DRS plans and executes repository review workflows.
+tags: [workflow, runtime]
+---
+```
+
+- `type` is the only required field and must be a non-empty string.
+- `title`, `description`, `resource`, `tags`, and `timestamp` are optional standard fields.
+- Declare the repository evidence behind every concept with the producer-defined `drs_sources` field: a list of repository-relative paths with optional `symbols`, for example `drs_sources: [{path: src/lib/wiki-delta.ts, symbols: [planWikiUpdate]}]`. Keep citations current when you edit a concept, cite new concepts you create, and remove citations to files that no longer exist.
+- Preserve unknown producer-defined frontmatter fields. OKF explicitly permits extensions.
+- Use `resource` only for a canonical URI. Cite repository source paths in the Markdown body using backticks.
+- `index.md` and `log.md` are reserved and are not concepts. `log.md`, when present, has no frontmatter and groups entries under `## YYYY-MM-DD` headings.
+- Standard Markdown links between concepts are directed relationships. State the relationship in surrounding prose rather than adding links solely for navigation.
+- Prefer bundle-root links such as `/architecture/runtime.md` when they improve stability. Verify links before finishing.
+- Every substantive concept must participate in the concept graph through at least one evidence-backed Markdown relationship link outside generated indexes. Do not leave the bundle as disconnected pages.
+
+## Content
+
+- Create `quickstart.md` as the entrypoint when initializing a bundle.
+- Use actual Markdown links from `quickstart.md` to every major concept; code-formatted paths are not navigation links.
+- Document architecture, major workflows, domain concepts, integrations, operations, tests, and extension points at the appropriate level rather than inventorying every source file.
+- Keep each concept in one canonical document and link to it from related concepts.
+- Explain why important behavior exists, where it is implemented, and what checks matter when changing it.
+- Keep pages concise and evidence-based. Do not invent behavior, ownership, or product intent.
+- Avoid thin pages and one-file directories. Start with no more than eight concept pages unless the repository is clearly tiny.
+
+## Maintenance
+
+- Read the current bundle before editing it.
+- Treat the workflow's deterministic delta plan as authoritative. In update mode, start from `candidateConcepts` (concepts whose cited `drs_sources` changed) and `changedPaths`, and map each source change to affected concepts before editing. Changed paths without provenance may need new or updated citations.
+- Treat the workflow-provided repository wiki brief (persistent `.drs/wiki-instructions.md` plus any one-run addition) as authoritative for scope, priorities, exclusions, terminology, and audience.
+- Preserve accurate content, stable concept paths, human-authored material, and extension frontmatter.
+- Build a source-change-to-document impact plan before editing. Make surgical updates and allow a no-op when the bundle is current.
+- Remove obsolete claims and concepts only when repository evidence clearly shows they are no longer valid.
+- Use `delete_file` for obsolete concept files; generated indexes remain owned by DRS.
+- Do not make formatting-only changes or rewrite unaffected pages.

package/.pi/agents/task/review-assistant.md

@@ -0,0 +1,22 @@
+---
+description: Conversational assistant for DRS review and workflow artifacts
+color: "#2563eb"
+hidden: false
+tools:
+  Read: true
+  Glob: true
+  Grep: true
+---
+
+You are the conversational DRS review assistant.
+
+Users ask questions about DRS review output, workflow output, local diffs, and specific findings. Use the supplied artifacts as the source of truth. Cite finding ids, file paths, severities, and workflow names when they are available.
+
+## Rules
+
+- Prefer concise, direct answers grounded in the artifact content.
+- If the user asks why a finding matters, explain the risk and the smallest safe remediation.
+- If the user asks whether a finding is valid, inspect relevant repository context before answering when tools are available.
+- If the user asks for a fix, first state the intended scope and keep any changes minimal. Do not commit changes.
+- Do not invent findings or workflow results that are not present in the supplied artifacts.
+- If artifact context is missing, say what is missing and answer only from available repository context.

package/.pi/workflows/github-pr-fix-review-issues-stacked.yaml

@@ -1,5 +1,12 @@
 name: github-pr-fix-review-issues-stacked
 description: Fix high-severity GitHub PR review issues and open a stacked PR
+metadata:
+  kind: review
+  tags: [review, fix, github, pull-request]
+  review:
+    source: github-pr
+    diff: true
+    issues: true
 inputs:
   owner: ''
   repo: ''
@@ -9,6 +16,7 @@ inputs:
   branchPrefix: 'drs-fix/pr-'
   allowStackedSource: 'false'
   draft: 'false'
+  useChangeRequestAuthor: 'true'
 output: changeRequest
 nodes:
   change:
@@ -37,7 +45,6 @@ nodes:
     if: '{{artifacts.stackGuard.allowed}} == true'
     with:
       source: change
-      artifact: persistedReviewArtifact
     output: review
 
   threshold:
@@ -70,7 +77,7 @@ nodes:
 
       Only fix findings at or above severity {{inputs.severity}} unless a lower-severity issue is directly required by such a fix.
 
-      Review artifact path: {{artifacts.persistedReviewArtifact.path}}
+      Review artifact path: {{artifacts.reviewArtifact.path}}
 
       Use the read_artifact tool with this path to get the finding manifest, then pull full details for specific findings by id. Do not assume the review JSON is in this prompt — call the tool.
 
@@ -94,6 +101,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: commit
 
   push:
@@ -121,7 +129,7 @@ nodes:
 
         Threshold: {{inputs.severity}}, minimum issues: {{inputs.minIssues}}
 
-        Review artifact: {{artifacts.persistedReviewArtifact.path}}
+        Review artifact: {{artifacts.reviewArtifact.path}}
 
         <!-- drs-stack-source: github:{{inputs.owner}}/{{inputs.repo}}#{{inputs.pr}} -->
         <!-- drs-stack-kind: fix -->
@@ -138,7 +146,7 @@ nodes:
       repo: '{{inputs.repo}}'
       pr: '{{inputs.pr}}'
       source: change
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       severity: '{{inputs.severity}}'
       stackedPrUrl: '{{artifacts.changeRequest.url}}'
       marker: drs-fix-status

package/.pi/workflows/github-pr-review-post.yaml

@@ -1,10 +1,26 @@
 name: github-pr-review-post
-description: Describe and review a GitHub pull request, posting the description and DRS comments
+description: Validate and post a canonical DRS review artifact to a GitHub pull request
+metadata:
+  kind: review-post
+  tags: [review, github, pull-request, artifact]
 inputs:
-  owner: ''
-  repo: ''
-  pr: ''
-output: review
+  owner:
+    type: string
+    required: true
+    description: GitHub repository owner
+  repo:
+    type: string
+    required: true
+    description: GitHub repository name
+  pr:
+    type: number
+    required: true
+    description: Pull request number
+  expectedHeadSha:
+    type: string
+    required: true
+    description: Pull request head SHA reviewed by the producing job
+output: postedReview
 nodes:
   change:
     action: change-source
@@ -13,31 +29,24 @@ nodes:
       owner: '{{inputs.owner}}'
       repo: '{{inputs.repo}}'
       pr: '{{inputs.pr}}'
+      requireCompleteDiff: true
     output: change
 
-  describe:
-    action: describe
+  load-review:
+    action: load-artifact
     needs:
       - change
     with:
+      kind: review
       source: change
-      post: true
-    output: description
-
-  review:
-    action: review
-    needs:
-      - describe
-    with:
-      source: change
-      artifact: persistedReviewArtifact
-    output: review
+    output: reviewArtifact
 
   post-comments:
     action: post-review-comments
     needs:
-      - review
+      - load-review
     with:
       source: change
-      review: review
+      review: reviewArtifact
+      expectedHeadSha: '{{inputs.expectedHeadSha}}'
     output: postedReview

package/.pi/workflows/github-pr-review.yaml

@@ -1,5 +1,12 @@
 name: github-pr-review
 description: Review a GitHub pull request, optionally posting a description, DRS comments, a visual HTML explainer, and a stacked fix PR
+metadata:
+  kind: review
+  tags: [review, github, pull-request]
+  review:
+    source: github-pr
+    diff: true
+    issues: true
 inputs:
   owner:
     type: string
@@ -21,6 +28,10 @@ inputs:
     type: boolean
     default: false
     description: Post DRS review comments to the PR
+  requireCompleteDiff:
+    type: boolean
+    default: false
+    description: Fail when GitHub cannot provide a stable, complete file and patch snapshot
   visual:
     type: boolean
     default: false
@@ -55,6 +66,10 @@ inputs:
   allowStackedSource:
     type: boolean
     default: false
+  useChangeRequestAuthor:
+    type: boolean
+    default: true
+    description: Attribute generated fix commits to the pull request creator
   fixDraft:
     type: boolean
     default: false
@@ -70,6 +85,7 @@ nodes:
       owner: '{{inputs.owner}}'
       repo: '{{inputs.repo}}'
       pr: '{{inputs.pr}}'
+      requireCompleteDiff: '{{inputs.requireCompleteDiff}}'
     output: change
 
   describe:
@@ -88,7 +104,12 @@ nodes:
       - change
     with:
       source: change
-      artifact: persistedReviewArtifact
+    permissions:
+      filesystem:
+        read:
+          roots: ['.']
+          allow: ['**']
+      shell: false
     output: review
 
   visual:
@@ -166,7 +187,7 @@ nodes:
 
       Only fix findings at or above severity {{inputs.fixSeverity}} unless a lower-severity issue is directly required by such a fix.
 
-      Review artifact path: {{artifacts.persistedReviewArtifact.path}}
+      Review artifact path: {{artifacts.reviewArtifact.path}}
 
       Use the read_artifact tool with this path to get the finding manifest, then pull full details for specific findings by id. Do not assume the review JSON is in this prompt — call the tool.
 
@@ -213,8 +234,14 @@ nodes:
     if: inputs.fixMode == internal
     with:
       source: verificationChange
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       severity: '{{inputs.fixSeverity}}'
+    permissions:
+      filesystem:
+        read:
+          roots: ['.']
+          allow: ['**']
+      shell: false
     output: reReview
 
   verify-fix:
@@ -224,12 +251,12 @@ nodes:
       - fix-change
     if: inputs.fixMode == internal
     with:
-      artifact: persistedReviewArtifact
+      artifact: reviewArtifact
       review: reReview
       fixChange: fixChange
       severity: '{{inputs.fixSeverity}}'
       minIssues: '1'
-    output: persistedReviewArtifact
+    output: reviewArtifact
 
   fix-loop:
     control: loop
@@ -252,7 +279,7 @@ nodes:
       repo: '{{inputs.repo}}'
       pr: '{{inputs.pr}}'
       source: change
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       fixReview: reReview
       fixChange: fixChange
       severity: '{{inputs.fixSeverity}}'
@@ -267,6 +294,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: internalFixCommit
 
   push-internal-fix:
@@ -294,6 +322,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: fixCommit
 
   fix-push:
@@ -320,7 +349,7 @@ nodes:
         Automated DRS fix stacked on PR #{{inputs.pr}} from the main github-pr-review workflow.
 
         Threshold: {{inputs.fixSeverity}}, minimum issues: {{inputs.fixMinIssues}}
-        Review artifact: {{artifacts.persistedReviewArtifact.path}}
+        Review artifact: {{artifacts.reviewArtifact.path}}
 
         <!-- drs-stack-source: github:{{inputs.owner}}/{{inputs.repo}}#{{inputs.pr}} -->
         <!-- drs-stack-kind: fix -->
@@ -354,7 +383,7 @@ nodes:
       repo: '{{inputs.repo}}'
       pr: '{{inputs.pr}}'
       source: change
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       severity: '{{inputs.fixSeverity}}'
       stackedPrUrl: '{{artifacts.changeRequest.url}}'
       marker: drs-fix-status

package/.pi/workflows/github-pr-update-agents-md-stacked.yaml

@@ -8,6 +8,7 @@ inputs:
   branchPrefix: 'drs-guidance/pr-'
   allowStackedSource: 'false'
   draft: 'false'
+  useChangeRequestAuthor: 'true'
 output: changeRequest
 nodes:
   change:
@@ -70,6 +71,7 @@ nodes:
     with:
       message: 'docs: update agent guidance for PR #{{inputs.pr}}'
       paths: '{{inputs.paths}}'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: commit
 
   push:

package/.pi/workflows/github-pr-visual-explain.yaml

@@ -17,10 +17,31 @@ nodes:
       pr: '{{inputs.pr}}'
     output: change
 
-  visual:
+  review-artifact:
+    action: artifact-exists
+    needs:
+      - change
+    with:
+      kind: review
+      source: change
+    output: reviewArtifactStatus
+
+  load-review-artifact:
+    action: load-artifact
+    needs:
+      - review-artifact
+    if: artifacts.reviewArtifactStatus.exists == true
+    with:
+      kind: review
+      source: change
+    output: reviewArtifact
+
+  visual-with-review:
     agent: visual/pr-explainer
     needs:
       - change
+      - load-review-artifact
+    if: artifacts.reviewArtifactStatus.exists == true
     input: |
       Generate a visual PR explainer HTML artifact.
 
@@ -31,5 +52,29 @@ nodes:
 
       DRS change-source context:
       {{artifacts.change}}
+
+      Current DRS review artifact path: {{artifacts.reviewArtifact.path}}
+
+      Use the read_artifact tool with this path to include confirmed DRS findings in a clearly labeled section. Do not assume the review JSON is in this prompt.
+    writes: '{{inputs.outputPath}}'
+    output: visualExplainer
+
+  visual:
+    agent: visual/pr-explainer
+    needs:
+      - review-artifact
+    if: artifacts.reviewArtifactStatus.exists == false
+    input: |
+      Generate a visual PR explainer HTML artifact.
+
+      Output path: {{inputs.outputPath}}
+      Slide mode: {{inputs.slides}}
+
+      Use the supplied DRS change-source context. If important file diffs are omitted or summarized, use git_diff for those files before explaining them.
+
+      DRS change-source context:
+      {{artifacts.change}}
+
+      No current DRS review artifact exists for this PR. Label the artifact as a PR explainer with no DRS findings included.
     writes: '{{inputs.outputPath}}'
     output: visualExplainer

package/.pi/workflows/gitlab-mr-fix-review-issues-stacked.yaml

@@ -1,5 +1,12 @@
 name: gitlab-mr-fix-review-issues-stacked
 description: Fix high-severity GitLab MR review issues and open a stacked MR
+metadata:
+  kind: review
+  tags: [review, fix, gitlab, merge-request]
+  review:
+    source: gitlab-mr
+    diff: true
+    issues: true
 inputs:
   project: ''
   mr: ''
@@ -8,6 +15,7 @@ inputs:
   branchPrefix: 'drs-fix/mr-'
   allowStackedSource: 'false'
   draft: 'false'
+  useChangeRequestAuthor: 'true'
 output: changeRequest
 nodes:
   change:
@@ -35,7 +43,6 @@ nodes:
     if: '{{artifacts.stackGuard.allowed}} == true'
     with:
       source: change
-      artifact: persistedReviewArtifact
     output: review
 
   threshold:
@@ -68,7 +75,7 @@ nodes:
 
       Only fix findings at or above severity {{inputs.severity}} unless a lower-severity issue is directly required by such a fix.
 
-      Review artifact path: {{artifacts.persistedReviewArtifact.path}}
+      Review artifact path: {{artifacts.reviewArtifact.path}}
 
       Use the read_artifact tool with this path to get the finding manifest, then pull full details for specific findings by id. Do not assume the review JSON is in this prompt — call the tool.
 
@@ -92,6 +99,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for MR !{{inputs.mr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: commit
 
   push:
@@ -118,7 +126,7 @@ nodes:
 
         Threshold: {{inputs.severity}}, minimum issues: {{inputs.minIssues}}
 
-        Review artifact: {{artifacts.persistedReviewArtifact.path}}
+        Review artifact: {{artifacts.reviewArtifact.path}}
 
         <!-- drs-stack-source: gitlab:{{inputs.project}}!{{inputs.mr}} -->
         <!-- drs-stack-kind: fix -->
@@ -134,7 +142,7 @@ nodes:
       project: '{{inputs.project}}'
       mr: '{{inputs.mr}}'
       source: change
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       severity: '{{inputs.severity}}'
       stackedPrUrl: '{{artifacts.changeRequest.url}}'
       marker: drs-fix-status

package/.pi/workflows/gitlab-mr-review.yaml

@@ -1,5 +1,12 @@
 name: gitlab-mr-review
 description: Review a GitLab merge request, optionally posting a description, DRS comments, Code Quality, and a visual HTML explainer
+metadata:
+  kind: review
+  tags: [review, gitlab, merge-request]
+  review:
+    source: gitlab-mr
+    diff: true
+    issues: true
 inputs:
   project:
     type: string
@@ -44,6 +51,10 @@ inputs:
   allowStackedSource:
     type: boolean
     default: false
+  useChangeRequestAuthor:
+    type: boolean
+    default: true
+    description: Attribute generated fix commits to the merge request creator
   fixDraft:
     type: boolean
     default: false
@@ -82,7 +93,6 @@ nodes:
       - change
     with:
       source: change
-      artifact: persistedReviewArtifact
     output: review
 
   visual:
@@ -170,7 +180,7 @@ nodes:
 
       Only fix findings at or above severity {{inputs.fixSeverity}} unless a lower-severity issue is directly required by such a fix.
 
-      Review artifact path: {{artifacts.persistedReviewArtifact.path}}
+      Review artifact path: {{artifacts.reviewArtifact.path}}
 
       Use the read_artifact tool with this path to get the finding manifest, then pull full details for specific findings by id. Do not assume the review JSON is in this prompt — call the tool.
 
@@ -217,7 +227,7 @@ nodes:
     if: inputs.fixMode == internal
     with:
       source: verificationChange
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       severity: '{{inputs.fixSeverity}}'
     output: reReview
 
@@ -228,12 +238,12 @@ nodes:
       - fix-change
     if: inputs.fixMode == internal
     with:
-      artifact: persistedReviewArtifact
+      artifact: reviewArtifact
       review: reReview
       fixChange: fixChange
       severity: '{{inputs.fixSeverity}}'
       minIssues: '1'
-    output: persistedReviewArtifact
+    output: reviewArtifact
 
   fix-loop:
     control: loop
@@ -255,7 +265,7 @@ nodes:
       project: '{{inputs.project}}'
       mr: '{{inputs.mr}}'
       source: change
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       fixReview: reReview
       fixChange: fixChange
       severity: '{{inputs.fixSeverity}}'
@@ -270,6 +280,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for MR !{{inputs.mr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: internalFixCommit
 
   push-internal-fix:
@@ -297,6 +308,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for MR !{{inputs.mr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: fixCommit
 
   fix-push:
@@ -322,7 +334,7 @@ nodes:
         Automated DRS fix stacked on MR !{{inputs.mr}} from the main gitlab-mr-review workflow.
 
         Threshold: {{inputs.fixSeverity}}, minimum issues: {{inputs.fixMinIssues}}
-        Review artifact: {{artifacts.persistedReviewArtifact.path}}
+        Review artifact: {{artifacts.reviewArtifact.path}}
 
         <!-- drs-stack-source: gitlab:{{inputs.project}}!{{inputs.mr}} -->
         <!-- drs-stack-kind: fix -->
@@ -354,7 +366,7 @@ nodes:
       project: '{{inputs.project}}'
       mr: '{{inputs.mr}}'
       source: change
-      reviewArtifact: persistedReviewArtifact
+      reviewArtifact: reviewArtifact
       severity: '{{inputs.fixSeverity}}'
       stackedPrUrl: '{{artifacts.changeRequest.url}}'
       marker: drs-fix-status

package/.pi/workflows/gitlab-mr-update-agents-md-stacked.yaml

@@ -7,6 +7,7 @@ inputs:
   branchPrefix: 'drs-guidance/mr-'
   allowStackedSource: 'false'
   draft: 'false'
+  useChangeRequestAuthor: 'true'
 output: changeRequest
 nodes:
   change:
@@ -68,6 +69,7 @@ nodes:
     with:
       message: 'docs: update agent guidance for MR !{{inputs.mr}}'
       paths: '{{inputs.paths}}'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: commit
 
   push: