[#347] 🤖 - 347 347 Develop

.cursor/rules/architecture.mdc

@@ -29,7 +29,7 @@ alwaysApply: true
 | Steps (commit) | `src/usecase/steps/commit/` | notify commit, check size |
 | Steps (issue comment) | `src/usecase/steps/issue_comment/` | check_issue_comment_language (translation) |
 | Steps (PR review comment) | `src/usecase/steps/pull_request_review_comment/` | check_pull_request_comment_language (translation) |
-| Bugbot autofix & user request | `src/usecase/steps/commit/bugbot/` + `user_request_use_case.ts` | detect_bugbot_fix_intent_use_case (plan agent: is_fix_request, is_do_request, target_finding_ids), BugbotAutofixUseCase + runBugbotAutofixCommitAndPush (fix findings), DoUserRequestUseCase + runUserRequestCommitAndPush (generic “do this”). Permission: ProjectRepository.isActorAllowedToModifyFiles (org member or repo owner). |
+| Bugbot autofix & user request | `src/usecase/steps/commit/bugbot/` + `user_request_use_case.ts` | detect_bugbot_fix_intent_use_case (plan agent: is_fix_request, is_do_request, is_review_request, target_finding_ids), BugbotAutofixUseCase + runBugbotAutofixCommitAndPush (fix findings), DoUserRequestUseCase + runUserRequestCommitAndPush (generic “do this”). Permission: ProjectRepository.isActorAllowedToModifyFiles (org member, or repo owner/write collaborator for personal repos); natural-language mutation requires the bot mention. |
 | Manager (content) | `src/manager/` | description handlers, configuration_handler, markdown_content_hotfix_handler (PR description, hotfix changelog content) |
 | Models | `src/data/model/` | Execution, Issue, PullRequest, SingleAction, etc. |
 | Repos | `src/data/repository/` | branch_repository, issue_repository, workflow_repository, ai_repository (OpenCode), file_repository, project_repository |

.cursor/rules/bugbot.mdc

@@ -65,13 +65,13 @@ Bugbot has two main modes: **detection** (on push or single action) and **fix/do
    - `loadBugbotContext(param, { branchOverride })` → unresolved findings.  
    - Build `UnresolvedFindingSummary[]` (id, title from `extractTitleFromBody`, description = fullBody.slice(0, 4000)).  
    - If PR review comment and `commentInReplyToId`: fetch parent comment body (`getPullRequestReviewCommentBody`), slice(0,1500).trim for prompt.  
-   - `buildBugbotFixIntentPrompt(commentBody, unresolvedFindings, parentCommentBody?)` → prompt asks: is_fix_request?, target_finding_ids?, is_do_request?  
-   - `askAgent(OPENCODE_AGENT_PLAN, prompt, BUGBOT_FIX_INTENT_RESPONSE_SCHEMA)` → `{ is_fix_request, target_finding_ids, is_do_request }`.  
-   - Payload: `isFixRequest`, `isDoRequest`, `targetFindingIds` (filtered to valid unresolved ids), `context`, `branchOverride`.
+   - `buildBugbotFixIntentPrompt(commentBody, unresolvedFindings, parentCommentBody?)` → prompt asks: is_fix_request?, target_finding_ids?, is_do_request?, is_review_request?.
+   - `askAgent(OPENCODE_AGENT_PLAN, prompt, BUGBOT_FIX_INTENT_RESPONSE_SCHEMA)` → `{ is_fix_request, target_finding_ids, is_do_request, is_review_request }`.
+   - Payload: `isFixRequest`, `isDoRequest`, `isReviewRequest`, `targetFindingIds` (filtered to valid unresolved ids), `context`, `branchOverride`.
 
 2. **Permission:** `ProjectRepository.isActorAllowedToModifyFiles(owner, actor, token)`.  
    - If owner is Organization: `orgs.checkMembershipForUser` (204 = allowed).  
-   - If owner is User: allowed only if `actor === owner`.
+   - If owner is User: allowed for the owner or a repository collaborator with `push`, `maintain`, or `admin` permission.
 
 3. **Branch A – Bugbot autofix** (when `canRunBugbotAutofix(payload)` and `allowedToModifyFiles`):  
    - `BugbotAutofixUseCase.invoke({ execution, targetFindingIds, userComment, context, branchOverride })`  
@@ -84,12 +84,13 @@ Bugbot has two main modes: **detection** (on push or single action) and **fix/do
    - `buildUserRequestPrompt(execution, userComment)` – repo context + sanitized user request; `copilotMessage(ai, prompt)`.  
    - If success: `runUserRequestCommitAndPush(execution, { branchOverride })` – same verify/checkout/add/commit/push with message `chore(#N): apply user request` or `chore: apply user request`.
 
-5. **Think** (when no file-modifying action ran): `ThinkUseCase.invoke(param)` – answers the user (e.g. question).
+5. **Review** (when the bot is mentioned and the request is read-only analysis): the existing findings/review flow runs without file changes.
+6. **Think** (when no file-modifying action ran): `ThinkUseCase.invoke(param)` – answers the user (e.g. question).
 
 **Key paths (fix/do):**
 
 - `detect_bugbot_fix_intent_use_case.ts` – intent detection, branch resolution for issue_comment
-- `build_bugbot_fix_intent_prompt.ts` – prompt for is_fix_request / is_do_request / target_finding_ids
+- `build_bugbot_fix_intent_prompt.ts` – prompt for is_fix_request / is_do_request / is_review_request / target_finding_ids
 - `bugbot_fix_intent_payload.ts` – getBugbotFixIntentPayload, canRunBugbotAutofix, canRunDoUserRequest
 - `schema.ts` – BUGBOT_FIX_INTENT_RESPONSE_SCHEMA (is_fix_request, target_finding_ids, is_do_request)
 - `bugbot_autofix_use_case.ts` – build prompt, copilotMessage (build agent)

.cursor/rules/usecase-flows.mdc

@@ -143,6 +143,6 @@ Invoked when:
 
 ## 8. Flow dependencies
 
-- **Bugbot autofix / Do user request**: require OpenCode, `isActorAllowedToModifyFiles` (org member or repo owner), and on issue_comment optionally branch from PR (`getHeadBranchForIssue`).
+- **Bugbot autofix / Do user request**: require OpenCode for natural-language intent, an explicit `@vypbot` mention for natural-language file changes, `isActorAllowedToModifyFiles` (org member, or repo owner / write collaborator for personal repos), and on issue_comment a branch from an open PR (`getHeadBranchForIssue`). Explicit `/copilot fix` and `/copilot implement` commands are deterministic and auditable.
 - **Think**: used in IssueComment and PullRequestReviewComment when neither autofix nor do user request runs (by intent or by permission).
 - **CommitUseCase**: NotifyNewCommitOnIssue, CheckChangesIssueSize, CheckProgress, DetectPotentialProblems (bugbot) always run in that order on every push with commits.

.github/ISSUE_TEMPLATE/help_request.yml

@@ -17,6 +17,11 @@ body:
       value: |
         ---
 
+  - type: markdown
+    attributes:
+      value: |
+        **Copilot assistance:** After opening this issue, mention `@vypbot` in a comment to ask for an explanation, diagnosis, or read-only code/security analysis. Use `/copilot help` to see all available commands.
+
   - type: dropdown
     id: help_area
     attributes:

.github/workflows/ci_check.yml

@@ -81,6 +81,9 @@ jobs:
       - name: Validate documentation assets
         run: pnpm run validate:docs-page
 
+      - name: Validate documentation contract
+        run: pnpm run validate:documentation
+
       - name: Validate workflow contract
         run: pnpm run validate:workflows
 

.github/workflows/copilot_close_inactive_issues.yml

@@ -0,0 +1,47 @@
+name: Copilot - Close Inactive Issues
+
+on:
+  schedule:
+    - cron: '0 */6 * * *'
+  workflow_dispatch:
+    inputs:
+      inactivity_threshold_hours:
+        description: Hours without activity before closing a waiting issue
+        required: false
+        default: '168'
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  copilot-inactive-issues:
+    name: Copilot - Close Inactive Issues
+    runs-on: [self-hosted, codex]
+    timeout-minutes: 120
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v5
+
+      - uses: ./
+        with:
+          single-action: close_inactive_issues_action
+          inactivity-threshold-hours: ${{ inputs.inactivity_threshold_hours || vars.INACTIVITY_THRESHOLD_HOURS || '168' }}
+          agent-provider: ${{ vars.AGENT_PROVIDER || 'codex' }}
+          agent-model-provider: ${{ vars.AGENT_MODEL_PROVIDER || 'openai' }}
+          agent-model: ${{ vars.AGENT_MODEL || 'gpt-5.6-luna' }}
+          agent-effort: ${{ vars.AGENT_EFFORT }}
+          agent-command: ${{ vars.AGENT_COMMAND }}
+          findings-provider: ${{ vars.FINDINGS_PROVIDER }}
+          findings-model-provider: ${{ vars.FINDINGS_MODEL_PROVIDER }}
+          findings-model: ${{ vars.FINDINGS_MODEL }}
+          findings-effort: ${{ vars.FINDINGS_EFFORT }}
+          findings-command: ${{ vars.FINDINGS_COMMAND }}
+          fixer-provider: ${{ vars.FIXER_PROVIDER }}
+          fixer-model-provider: ${{ vars.FIXER_MODEL_PROVIDER }}
+          fixer-model: ${{ vars.FIXER_MODEL }}
+          fixer-effort: ${{ vars.FIXER_EFFORT }}
+          fixer-command: ${{ vars.FIXER_COMMAND }}
+          token: ${{ secrets.PAT }}

CONTRIBUTING.md

@@ -39,20 +39,20 @@ pnpm run build
 - **`src/infrastructure/composition/`** – Capability and use-case composition roots.
 - **`src/infrastructure/github/`** – GitHub provider clients and transport adapters.
 - **`src/manager/`** – Content handlers for PR descriptions, hotfix changelog, and markdown (e.g. `configuration_handler`, `markdown_content_hotfix_handler`).
-- **`src/data/model/`** – Models and model policies; the directory still contains some transitional orchestration and is not uniformly pure domain.
+- **`src/data/model/`** – Provider-neutral models and pure model policies. Runtime orchestration belongs under `src/application/usecases/`.
 - **`src/data/repository/`** – Specialized capability adapters and repository policies.
-- **`src/utils/`** – Constants, logger, content utils, etc.
+- **`src/utils/`** – Small side-effect-free utilities and the concrete logger; feature contracts live with their owning layer.
 - **`action.yml`** – Action metadata and input definitions.
 - **`build/`** – Compiled output (bundled JS); do not edit directly.
 
 ## Conventions
 
 1. **TypeScript** – Prefer TypeScript; keep action and CLI buildable with `ncc`.
-2. **Constants** – Use `INPUT_KEYS` and `ACTIONS` from `src/utils/constants.ts` instead of ad-hoc strings.
+2. **Contracts and constants** – Use `INPUT_KEYS` from `src/application/contracts/input_keys.ts` and `ACTIONS` from `src/data/model/action_types.ts` instead of ad-hoc strings.
 3. **Logging** – Use the semantic application logging port from `src/application/ports/logging_ports.ts` in application code. Concrete logging adapters and direct `src/utils/logger.ts` usage belong only at the outer infrastructure/entrypoint boundary.
 4. **New inputs** – When adding inputs:
    - Update `action.yml`
-   - Add to `INPUT_KEYS` in `src/utils/constants.ts`
+   - Add to `INPUT_KEYS` in `src/application/contracts/input_keys.ts`
    - Read the input through the appropriate input builder/reader used by the action or CLI composition root.
 
 ## Code Quality

README.md

@@ -30,30 +30,60 @@ Full documentation: **[docs.page/vypdev/copilot](https://docs.page/vypdev/copilo
 
 ## Getting started
 
-1. **Create a PAT** and store it as a repo secret (e.g. `PAT`). See [Authentication](https://docs.page/vypdev/copilot/authentication).
-2. **Use the action** from the marketplace so versions are stable:
-   ```yaml
-   uses: vypdev/copilot@v3
-   ```
-3. **Install the CLI** when you want to run setup or single actions locally:
-   ```bash
-   npm install --global @vypdev/copilot
-   copilot --version
-   ```
-   Update the published CLI later with **`copilot upgrade`**.
-4. **Add workflows** — Copy the files from `setup/workflows/` into your `.github/workflows/`, or run **`copilot setup`** from your repo root (with `PERSONAL_ACCESS_TOKEN` in `.env`). See [How to use](https://docs.page/vypdev/copilot/how-to-use).
+The recommended onboarding path is to install the published package globally with
+`pnpm` and initialize the target repository with `copilot setup`:
+
+```bash
+pnpm add --global @vypdev/copilot
+copilot --version
+cd /path/to/your/repository
+copilot setup
+```
+
+`@vypdev/copilot` contains both the `copilot` CLI and the compiled GitHub Action.
+The global installation makes the CLI and the setup templates available; it does
+not install an Action into GitHub. `copilot setup` is the canonical initialization
+flow and will, according to the selected features:
+
+- copy the required workflows, issue templates, and pull request template into the repository;
+- create the labels and issue types used by the workflows;
+- configure non-sensitive Repository Variables; and
+- validate or provision the workflow PAT and provider credentials at the selected scope.
+
+The setup PAT entered by the operator is separate from the workflow `PAT` Secret.
+Use `copilot setup --dry-run` to inspect the plan before making local or remote
+changes. See the complete [How to use](https://docs.page/vypdev/copilot/how-to-use)
+guide and [Authentication](https://docs.page/vypdev/copilot/authentication).
+
+### Manual workflow integration (advanced)
+
+You can integrate the Action manually when the CLI setup flow is not suitable:
+copy selected files from `setup/workflows/` into `.github/workflows/` and add
+steps such as:
+
+```yaml
+- uses: vypdev/copilot@v3
+  with:
+    token: ${{ secrets.PAT }}
+```
+
+This is a lower-level integration path, not an alternative name for
+`copilot setup`: it does not automatically create labels, issue types, Variables,
+Secrets, templates, or the complete set of workflows. Those resources must be
+configured and kept consistent manually. See [Workflow setup](https://docs.page/vypdev/copilot/issues/workflow-setup)
+for action-level examples.
 
 ---
 
 ## What it does
 
-- **Issues** — Branch creation from labels (feature, bugfix, hotfix, release, docs, chore), project linking, assignees, lifecycle/size/progress labels; optional Bugbot (AI) on the issue; from a comment you can plan, recheck, fix, or dismiss findings.
-- **Pull requests** — Link PRs to issues, update project columns, assign reviewers; optional AI-generated PR description and automatic Bugbot review with stable finding threads; from a PR review comment you can request a read-only recheck or an authorized autofix.
+- **Issues** — Branch creation from labels (feature, bugfix, hotfix, release, docs, chore), project linking, assignees, lifecycle/size/progress labels; new issues receive a contextual `@vypbot` welcome; from comments you can ask for help, explain/diagnose/analyze code, plan work, fix findings, or request an authorized implementation.
+- **Pull requests** — Link PRs to issues, update project columns, assign reviewers; optional AI-generated PR description and automatic Bugbot review with stable finding threads; use `/copilot analyze` or `@vypbot analyze ...` for read-only review, or request an authorized change.
 - **Push (commits)** — Notify the issue, update size/progress; optional Bugbot (detection) and prefix checks.
 - **Projects** — Link issues and PRs to boards and move them to the right columns.
 - **Single actions** — On-demand: check progress, think, create release/tag, mark deployed, etc.
 - **Evidence and safety** — Every run writes a bounded Job Summary; PR reviews expose a `Copilot / Review` Check Run, active findings fail that check, and all agent/comment content remains bounded and treated as untrusted data.
-- **Concurrency** — Uses a repository-wide application queue across the seven Copilot/Task mutation workflows. Polling is adaptive and rate-limit-aware, with a 90-minute queue deadline and no cancellation or overwrite of intermediate runs. See [Features → Workflow concurrency](https://docs.page/vypdev/copilot/features#workflow-concurrency-and-sequential-execution).
+- **Concurrency** — Uses a repository-wide application queue across the eight Copilot/Task mutation workflows. Polling is adaptive and rate-limit-aware, with a 90-minute queue deadline and no cancellation or overwrite of intermediate runs. See [Features → Workflow concurrency](https://docs.page/vypdev/copilot/features#workflow-concurrency-and-sequential-execution).
 
 AI features use the configured agent runtime and qualified model; see the [Agents](https://docs.page/vypdev/copilot/agents) and [Security & Operations](https://docs.page/vypdev/copilot/security-operations) documentation. You can run progress and Bugbot locally through the [Single actions → Workflow & CLI](https://docs.page/vypdev/copilot/single-actions/workflow-and-cli) path.