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

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/workflows/github-pr-fix-review-issues-stacked.yaml

@@ -16,6 +16,7 @@ inputs:
   branchPrefix: 'drs-fix/pr-'
   allowStackedSource: 'false'
   draft: 'false'
+  useChangeRequestAuthor: 'true'
 output: changeRequest
 nodes:
   change:
@@ -100,6 +101,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: commit
 
   push:

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,30 +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
-    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

@@ -28,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
@@ -62,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
@@ -77,6 +85,7 @@ nodes:
       owner: '{{inputs.owner}}'
       repo: '{{inputs.repo}}'
       pr: '{{inputs.pr}}'
+      requireCompleteDiff: '{{inputs.requireCompleteDiff}}'
     output: change
 
   describe:
@@ -95,6 +104,12 @@ nodes:
       - change
     with:
       source: change
+    permissions:
+      filesystem:
+        read:
+          roots: ['.']
+          allow: ['**']
+      shell: false
     output: review
 
   visual:
@@ -221,6 +236,12 @@ nodes:
       source: verificationChange
       reviewArtifact: reviewArtifact
       severity: '{{inputs.fixSeverity}}'
+    permissions:
+      filesystem:
+        read:
+          roots: ['.']
+          allow: ['**']
+      shell: false
     output: reReview
 
   verify-fix:
@@ -273,6 +294,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: internalFixCommit
 
   push-internal-fix:
@@ -300,6 +322,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for PR #{{inputs.pr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: fixCommit
 
   fix-push:

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/gitlab-mr-fix-review-issues-stacked.yaml

@@ -15,6 +15,7 @@ inputs:
   branchPrefix: 'drs-fix/mr-'
   allowStackedSource: 'false'
   draft: 'false'
+  useChangeRequestAuthor: 'true'
 output: changeRequest
 nodes:
   change:
@@ -98,6 +99,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for MR !{{inputs.mr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: commit
 
   push:

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

@@ -51,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
@@ -276,6 +280,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for MR !{{inputs.mr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: internalFixCommit
 
   push-internal-fix:
@@ -303,6 +308,7 @@ nodes:
     with:
       message: 'fix: address DRS review issues for MR !{{inputs.mr}}'
       paths: '.'
+      useChangeRequestAuthor: '{{inputs.useChangeRequestAuthor}}'
     output: fixCommit
 
   fix-push:

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:

package/.pi/workflows/release-changelog-finalize.yaml

@@ -31,6 +31,15 @@ nodes:
     agent: task/changelog-updater
     needs:
       - release-change
+    permissions:
+      filesystem:
+        read:
+          roots: ['.']
+          allow: [CHANGELOG.md]
+        write:
+          roots: ['.']
+          allow: [CHANGELOG.md]
+      shell: false
     input: |
       Finalize CHANGELOG.md for release {{inputs.version}} dated {{inputs.date}}.
 
@@ -41,6 +50,7 @@ nodes:
       - Ensure the file starts with `# Changelog` followed by the standard introduction.
       - Move release-worthy `## Unreleased` entries into `## {{inputs.version}} - {{inputs.date}}`.
       - Create `## {{inputs.version}} - {{inputs.date}}` directly above the previous released version if it does not exist.
+      - Consolidate any earlier prerelease sections for the same major.minor.patch version into this release section. A final release must not retain separate RC, beta, or alpha sections for that version.
       - Keep `## Unreleased` above the release section only if there are remaining unreleased entries; otherwise remove empty duplicate/unneeded headings.
       - Preserve existing older release sections.
       - Do not create git tags, publish packages, or edit files other than CHANGELOG.md.

package/.pi/workflows/repository-wiki-check.yaml

@@ -0,0 +1,40 @@
+name: repository-wiki-check
+description: Verify repository wiki delta state and OKF v0.1 conformance without a model call
+metadata:
+  kind: validation
+  tags:
+    - documentation
+    - wiki
+    - okf
+    - ci
+inputs:
+  root:
+    type: string
+    default: wiki
+    description: Repository-relative OKF bundle root
+  instructionsPath:
+    type: string
+    default: .drs/wiki-instructions.md
+    description: Repository-relative persistent wiki brief path outside the OKF bundle
+  statePath:
+    type: string
+    default: .drs/wiki-state.json
+    description: Repository-relative delta state path outside the OKF bundle
+output: wikiValidation
+nodes:
+  check-state:
+    action: check-wiki-state
+    with:
+      root: '{{inputs.root}}'
+      statePath: '{{inputs.statePath}}'
+      instructionsPath: '{{inputs.instructionsPath}}'
+    output: wikiDelta
+
+  validate-wiki:
+    action: validate-okf-wiki
+    needs:
+      - check-state
+    with:
+      root: '{{inputs.root}}'
+      version: '0.1'
+    output: wikiValidation

package/.pi/workflows/repository-wiki-sync.yaml

@@ -0,0 +1,187 @@
+name: repository-wiki-sync
+description: Generate or update one OKF v0.1 repository wiki bundle
+metadata:
+  kind: maintenance
+  tags:
+    - documentation
+    - wiki
+    - okf
+inputs:
+  root:
+    type: string
+    default: wiki
+    description: Repository-relative OKF bundle root
+  instructions:
+    type: string
+    default: ''
+    description: One-run addition to the persistent repository wiki brief
+  instructionsPath:
+    type: string
+    default: .drs/wiki-instructions.md
+    description: Repository-relative persistent wiki brief path outside the OKF bundle
+  statePath:
+    type: string
+    default: .drs/wiki-state.json
+    description: Repository-relative delta state path outside the OKF bundle
+  check:
+    type: boolean
+    default: false
+    description: Fail when the workflow produces uncommitted wiki or state changes
+output: wikiResult
+nodes:
+  plan-update:
+    action: plan-wiki-update
+    with:
+      root: '{{inputs.root}}'
+      statePath: '{{inputs.statePath}}'
+      instructionsPath: '{{inputs.instructionsPath}}'
+      instructions: '{{inputs.instructions}}'
+    output: wikiDelta
+
+  maintain-wiki:
+    agent: task/okf-wiki-maintainer
+    needs:
+      - plan-update
+    if: artifacts.wikiDelta.shouldRun == true
+    permissions:
+      filesystem:
+        read:
+          roots:
+            - '.'
+          allow:
+            - '**'
+        write:
+          roots:
+            - '{{inputs.root}}'
+          allow:
+            - '**/*.md'
+          deny:
+            - '**/index.md'
+        delete:
+          roots:
+            - '{{inputs.root}}'
+          allow:
+            - '**/*.md'
+          deny:
+            - '**/index.md'
+      shell: false
+    validation:
+      afterMutation:
+        - name: okf-document
+          root: '{{inputs.root}}'
+    input: |
+      Generate, reconcile, or update the repository wiki as one OKF v0.1 bundle.
+
+      Bundle root: {{inputs.root}}
+
+      Deterministic delta plan:
+      {{artifacts.wikiDelta}}
+
+      Repository wiki brief (persistent brief plus any one-run addition):
+      {{artifacts.wikiDelta.instructions}}
+
+      For generate mode, inspect the full repository and create the initial bundle. For update mode, prioritize candidateConcepts (concepts whose cited drs_sources changed) and use changedPaths as the primary scope, editing only directly affected concepts. For reconcile mode, preserve accurate existing content while repairing state or bundle drift and re-apply the repository wiki brief. Declare and maintain drs_sources citations in every concept you create or edit.
+
+      Edit concept files in place and return a concise summary. Do not edit index.md files; DRS synchronizes them in the next step. Do not commit or push.
+    output: wikiSummary
+
+  sync-indexes:
+    action: sync-okf-indexes
+    needs:
+      - maintain-wiki
+    with:
+      root: '{{inputs.root}}'
+      version: '0.1'
+    output: wikiIndexes
+
+  validate-updated-wiki:
+    action: validate-okf-wiki
+    needs:
+      - sync-indexes
+    with:
+      root: '{{inputs.root}}'
+      version: '0.1'
+    output: wikiValidation
+
+  record-state:
+    action: record-wiki-state
+    needs:
+      - validate-updated-wiki
+    with:
+      root: '{{inputs.root}}'
+      statePath: '{{inputs.statePath}}'
+      instructionsPath: '{{inputs.instructionsPath}}'
+      instructions: '{{inputs.instructions}}'
+    output: wikiState
+
+  check-updated-wiki:
+    action: check-wiki-clean
+    needs:
+      - record-state
+    if: inputs.check == true
+    with:
+      root: '{{inputs.root}}'
+      statePath: '{{inputs.statePath}}'
+
+  summarize-updated-wiki:
+    action: summarize-wiki-run
+    needs:
+      - record-state
+    if: inputs.check == false
+    with:
+      plan: wikiDelta
+      validation: wikiValidation
+      agentNode: maintain-wiki
+    output: wikiResult
+
+  summarize-checked-updated-wiki:
+    action: summarize-wiki-run
+    needs:
+      - check-updated-wiki
+    if: inputs.check == true
+    with:
+      plan: wikiDelta
+      validation: wikiValidation
+      agentNode: maintain-wiki
+    output: wikiResult
+
+  validate-current-wiki:
+    action: validate-okf-wiki
+    needs:
+      - plan-update
+    if: artifacts.wikiDelta.shouldRun == false
+    with:
+      root: '{{inputs.root}}'
+      version: '0.1'
+    output: wikiValidation
+
+  check-current-wiki:
+    action: check-wiki-clean
+    needs:
+      - validate-current-wiki
+    if: inputs.check == true
+    with:
+      root: '{{inputs.root}}'
+      statePath: '{{inputs.statePath}}'
+
+  summarize-current-wiki:
+    action: summarize-wiki-run
+    needs:
+      - validate-current-wiki
+    if: inputs.check == false
+    with:
+      plan: wikiDelta
+      validation: wikiValidation
+      agentNode: maintain-wiki
+    output: wikiResult
+
+  summarize-checked-current-wiki:
+    action: summarize-wiki-run
+    needs:
+      - check-current-wiki
+    if: inputs.check == true
+    with:
+      plan: wikiDelta
+      validation: wikiValidation
+      agentNode: maintain-wiki
+    output: wikiResult