@vypdev/copilot 3.3.0 → 3.5.0

package/README.md

@@ -21,7 +21,8 @@ Full documentation: **[docs.page/vypdev/copilot](https://docs.page/vypdev/copilo
 | [How to use](https://docs.page/vypdev/copilot/how-to-use) | Step-by-step setup: PAT, `copilot setup`, workflows |
 | [Features & capabilities](https://docs.page/vypdev/copilot/features) | Workflow triggers, single actions, agent execution, and concurrency |
 | [Authentication](https://docs.page/vypdev/copilot/authentication) | PAT setup, permissions, token best practices |
-| [Configuration](https://docs.page/vypdev/copilot/configuration) | All inputs: branches, labels, projects, images, etc. |
+| [Configuration](https://docs.page/vypdev/copilot/configuration) | All inputs: branches, labels, projects, locale, agents, and more |
+| [Release orchestration](https://docs.page/vypdev/copilot/issues/deployment-orchestration) | Production-first release/hotfix flow, npm OIDC, reconciliation, and recovery |
 | [Agents](https://docs.page/vypdev/copilot/agents) | Runtime, model, CLI, policy, and failure behavior |
 | [Security & Operations](https://docs.page/vypdev/copilot/security-operations) | Credentials, trust boundaries, provisioning, verification, upgrades, and rollback |
 | [Development](https://docs.page/vypdev/copilot/development) | Architecture, testing, documentation, artifacts, and release process |
@@ -38,6 +39,8 @@ pnpm add --global @vypdev/copilot
 copilot --version
 cd /path/to/your/repository
 copilot setup
+# Optional local visual assistant, in the same repository:
+copilot setup --web
 ```
 
 `@vypdev/copilot` contains both the `copilot` CLI and the compiled GitHub Action.
@@ -45,16 +48,36 @@ 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;
+- copy the selected workflows, Issue Forms, pull request template, and repository agent guidance 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 wizard selects issue workflow kinds with a Space/Enter multi-select; `All`
+is the default. It also generates `.copilot/repository-profile.json`,
+`.copilot/AGENT_GUIDE.md`, and the Codex skill
+`.agents/skills/copilot-repository-workflow/SKILL.md` by default. The generated
+guidance makes clear that the Action owns remote branch lifecycle: agents work
+on the exact existing branch and push normal commits, but do not create, rename,
+delete, replace, or force-push managed branches.
+
 The setup PAT entered by the operator is separate from the workflow `PAT` Secret.
+Interactive setup can guide creation of both via GitHub's prefilled PAT form:
+picks the permission-affecting setup options first, then the operator creates a temporary setup token, and the bot account creates the
+persistent workflow token. GitHub handles account switching, 2FA, repository
+selection, and final creation; Copilot never creates or revokes either token.
 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).
 
+`--web` opens an ephemeral, loopback-only setup page with a six-stage progress
+rail, plan review, separate masked inputs for the two PAT roles, and a
+System/Light/Dark theme control. If the browser does not open, use the local
+URL printed in the terminal. The page does not create PATs: GitHub owns the
+form, account switch, 2FA, and token issuance. You must explicitly approve
+the plan and Apply; `--web` cannot be combined with unattended approval or
+secret-bearing command-line flags. The terminal wizard remains the default.
+
 ### Manual workflow integration (advanced)
 
 You can integrate the Action manually when the CLI setup flow is not suitable:
@@ -81,14 +104,19 @@ for action-level examples.
 - **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, and optionally run Bugbot; a separate agent-free observer watches every branch and recommends synchronizing children when their parent moves.
 - **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.
+- **Single actions** — On-demand maintenance and analysis, plus workflow-owned callbacks for durable release and hotfix operations.
 - **Branch synchronization** — Authorized issue/PR commands merge parent into working branch, call the fixer only for eligible conflicts, run verification, reject remote races, push, and report exactly what happened.
-- **Evidence and safety** — Every run writes a bounded Job Summary; PR reviews expose a `Copilot / Review` Check Run, active findings fail that check, agent sandboxes run without approval or network access, and all agent/comment content remains bounded, secret-redacted, and treated as untrusted data.
+- **Release and hotfix orchestration** — Cut from the correct immutable origin, promote through a protected production PR, publish only the accepted production commit, and reconcile it back through resumable managed PRs without keeping a runner polling checks.
+- **Evidence and safety** — Every run writes a bounded Job Summary; PR findings are reconciled from GitHub into one status card, historical review status blocks, and a `Copilot / Review` Check Run. Actionable findings are neutral by default and fail it only when `bugbot-fail-on-unresolved` is enabled, while unknown/incomplete state always fails closed. Agent sandboxes run without approval or network access, and all agent/comment content remains bounded, secret-redacted, and treated as untrusted data.
 - **Bugbot quality** — Hierarchical rules, semantic finding identity, safe GitHub suggestions, analysis-only dry runs, a multilingual regression corpus, real-agent benchmark runner, content-free telemetry/analytics, and the provider-neutral `@vypdev/copilot/bugbot` API.
-- **Concurrency** — Each workflow waits only for older active runs of that same workflow. Polling is adaptive and rate-limit-aware, with a 90-minute queue deadline and no cancellation or overwrite of intermediate runs. Event templates can also skip bot-authored jobs before runner allocation through the optional, generic `COPILOT_BOT_LOGIN` Repository Variable. See [Features → Workflow concurrency](https://docs.page/vypdev/copilot/features#workflow-concurrency-and-sequential-execution).
+- **Concurrency** — Durable mutation workflows wait only for older active runs of that same workflow, with rate-limit-aware polling and a 90-minute deadline. Commit and Pull Request templates share a branch-scoped latest-revision group so a newer Bugbot review supersedes an older one; provider re-reads and head guards make interrupted finding transitions retryable. Event templates can also skip bot-authored jobs before runner allocation through `COPILOT_BOT_LOGIN`. 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.
 
+The programmatic Bugbot API is request-only: `review(BugbotReviewRequest)` is
+the sole review entrypoint, and internal runtime aggregates are not exported.
+See the [Programmatic API](https://docs.page/vypdev/copilot/bugbot/programmatic-api).
+
 ---
 
 ## Contributing

package/action.yml

@@ -1,10 +1,19 @@
-name: "Copilot - Github with super powers"
+name: "Copilot - GitHub with super powers"
 description: "Automates branch management, GitHub project linking, and issue/PR tracking with Git-Flow methodology."
 author: "Efra Espada"
 inputs:
   debug:
     description: "Enable debug mode."
     default: "false"
+  pr-approval-observer:
+    description: "Run the isolated, trusted-default-branch pull-request approval observer."
+    default: "false"
+  pr-approval-pr-number:
+    description: "Positive pull-request number for an authorized manual approval recheck."
+    default: ""
+  pr-approval-policy:
+    description: "Versioned PR approval policy forwarded by the observer workflow; runtime rereads the Variable before a review write."
+    default: ""
   single-action:
     description: "Launch single actions."
     default: ""
@@ -15,14 +24,17 @@ inputs:
     description: "Version target for executing single action."
     default: ""
   single-action-title:
-    description: "Title target for executing single action."
+    description: "Durable release/hotfix title for prepare_deployment_action."
     default: ""
   single-action-changelog:
-    description: "Changelog target for executing single action."
+    description: "Durable release/hotfix changelog for prepare_deployment_action."
     default: ""
   single-action-message:
     description: "Markdown message for the publish_issue_comment single action."
     default: ""
+  single-action-operation-id:
+    description: "Expected durable deployment operation ID for trusted continuation actions."
+    default: ""
   single-action-comment-id:
     description: "Optional issue comment ID to replace or append to."
     default: ""
@@ -35,12 +47,15 @@ inputs:
   emoji-labeled-title:
     description: "Enable titles with emojis based on issue labels."
     default: "true"
-  branch-management-launcher-label:
-    description: "Label to trigger branch management actions."
-    default: "branched"
-  branch-management-always:
-    description: "If true, ignores the branch-management-launcher-label requirement for running Git Board."
+  issue-managed-branches:
+    description: "Let the Action create linked branches after an authorized in-progress start."
+    default: "true"
+  pre-branch-sdd:
+    description: "Require a validated SDD first commit for started feature and contract-change issues. Requires issue-managed-branches."
     default: "false"
+  issue-workflow-profile:
+    description: "JSON profile of enabled issue workflows."
+    default: ""
   branch-management-emoji:
     description: "Emoji to indicate branched issues. It will be ignored if emoji-labeled-title is false."
     default: "🧑‍💻"
@@ -122,9 +137,12 @@ inputs:
   state-planned-label:
     description: "Label for the Copilot lifecycle state: planned."
     default: "state:planned"
-  state-in-progress-label:
-    description: "Label for the Copilot lifecycle state: implementation in progress."
-    default: "state:in-progress"
+  state-working-label:
+    description: "Label for work ready on a branch or branchless help."
+    default: "state:working"
+  state-specifying-label:
+    description: "Label for active SDD clarification and drafting."
+    default: "state:specifying"
   state-reviewing-label:
     description: "Label for the Copilot lifecycle state: reviewing."
     default: "state:reviewing"
@@ -306,12 +324,15 @@ inputs:
     description: "Color of the issue type for help."
     default: "purple"
 
-  issues-locale:
-    description: "Locale of the issues."
+  repository-locale:
+    description: "BCP-47 locale for repository-facing messages. Issue and pull-request locales inherit it."
     default: "en-US"
+  issues-locale:
+    description: "Optional BCP-47 locale override for issue-facing messages. Empty inherits repository-locale."
+    default: ""
   pull-requests-locale:
-    description: "Locale of the pull requests."
-    default: "en-US"
+    description: "Optional BCP-47 locale override for pull-request-facing messages. Empty inherits repository-locale."
+    default: ""
   main-branch:
     description: "Name of the main branch (e.g., master)."
     default: "master"
@@ -336,78 +357,6 @@ inputs:
   release-tree:
     description: "Naming convention for release branches."
     default: "release"
-  images-on-issue:
-    description: "Include images in issue comments."
-    default: "true"
-  images-on-pull-request:
-    description: "Include images in pull request comments."
-    default: "true"
-  images-on-commit:
-    description: "Include images in commit comments."
-    default: "true"
-  images-issue-automatic:
-    description: "Image URLs to display in automatic action issue comments."
-    default: ""
-  images-issue-feature:
-    description: "Image URLs to display in feature action issue comments."
-    default: ""
-  images-issue-bugfix:
-    description: "Image URLs to display in bugfix action issue comments."
-    default: ""
-  images-issue-docs:
-    description: "Image URLs to display in docs action issue comments."
-    default: ""
-  images-issue-chore:
-    description: "Image URLs to display in chore action issue comments."
-    default: ""
-  images-issue-hotfix:
-    description: "Image URLs to display in hotfix action issue comments."
-    default: ""
-  images-issue-release:
-    description: "Image URLs to display in release action issue comments."
-    default: ""
-  images-pull-request-automatic:
-    description: "Image URLs to display in automatic action pull request comments."
-    default: ""
-  images-pull-request-feature:
-    description: "Image URLs to display in feature action pull request comments."
-    default: ""
-  images-pull-request-bugfix:
-    description: "Image URLs to display in bugfix action pull request comments."
-    default: ""
-  images-pull-request-docs:
-    description: "Image URLs to display in docs action pull request comments."
-    default: ""
-  images-pull-request-chore:
-    description: "Image URLs to display in chore action pull request comments."
-    default: ""
-  images-pull-request-hotfix:
-    description: "Image URLs to display in hotfix action pull request comments."
-    default: ""
-  images-pull-request-release:
-    description: "Image URLs to display in release action pull request comments."
-    default: ""
-  images-commit-feature:
-    description: "Image URLs to display in feature action commit comments."
-    default: ""
-  images-commit-bugfix:
-    description: "Image URLs to display in bugfix action commit comments."
-    default: ""
-  images-commit-release:
-    description: "Image URLs to display in release action commit comments."
-    default: ""
-  images-commit-automatic:
-    description: "Image URLs to display in automatic action commit comments."
-    default: ""
-  images-commit-docs:
-    description: "Image URLs to display in docs action commit comments."
-    default: ""
-  images-commit-chore:
-    description: "Image URLs to display in chore action commit comments."
-    default: ""
-  images-commit-hotfix:
-    description: "Image URLs to display in hotfix action commit comments."
-    default: "" 
   commit-prefix-transforms:
     description: "List of transformations to apply sequentially for commit prefix generation. Options: replace-slash, replace-all, lowercase, uppercase, kebab-case, snake-case, camel-case, trim, remove-numbers, clean-dashes, etc."
     default: "replace-slash"
@@ -420,21 +369,51 @@ inputs:
   hotfix-workflow:
     description: "Hotfix workflow for running hotfix deploys."
     default: "hotfix_workflow.yml"
+  release-reconciliation-strategy:
+    description: "Release reconciliation source after production publication: production-lineage, canonical-gitflow, or manual."
+    default: "production-lineage"
+  hotfix-reconciliation-strategy:
+    description: "Hotfix reconciliation source after production publication: production-lineage, canonical-gitflow, or manual."
+    default: "production-lineage"
+  reconciliation-pr-mode:
+    description: "Managed PR behavior: auto, auto-merge, merge-queue, or create-only."
+    default: "auto"
+  merge-queue-check-attestations:
+    description: "JSON array of exact required-check attestations for merge queue targets; unknown checks block by default."
+    default: "[]"
+  reconciliation-backmerge-mode:
+    description: "Back-merge branch shape: auto, direct, or sync-branch."
+    default: "auto"
+  hotfix-active-release-policy:
+    description: "Hotfix reconciliation target policy: prefer-release, development, or both."
+    default: "prefer-release"
+  reconciliation-tree:
+    description: "Safe prefix for ephemeral reconciliation branches."
+    default: "sync"
+  reconciliation-cleanup:
+    description: "Branch cleanup after reconciliation: all, source-only, sync-only, or none."
+    default: "all"
+  reconciliation-issue-completion:
+    description: "Launcher issue behavior after completion: close or keep-open."
+    default: "close"
+  orchestration-presentation-mode:
+    description: "Release control-center detail: guided, compact, or quiet."
+    default: "guided"
+  orchestration-diagrams:
+    description: "Render fixed-label Mermaid diagrams with a textual equivalent in guided mode."
+    default: "true"
+  orchestration-comment-mode:
+    description: "Issue notification policy: update or milestones."
+    default: "update"
   desired-assignees-count:
     description: "The number of assignees desired for the issue or pull request. If set to 0, no assignees will be added. If the number exceeds the available members, all members will be assigned. Max 10."
     default: "1"
   desired-reviewers-count:
     description: "The number of reviewers desired for the pull request. If set to 0, no reviewers will be added. If the number exceeds the available members, all members will be reviewers. Max 15."
     default: "1"
-  merge-timeout:
-    description: "The timeout for the merge workflow in seconds. If set to 0, the merge will not be timed out."
-    default: "600"
   token:
     description: "Fine-grained personal access token for branch and project operations"
     required: true
-  queue-gate-only:
-    description: "Admit this workflow to the sequential queue and return before constructing or executing a project action."
-    default: "false"
   agent-provider:
     description: "Single agent provider used by findings and fixer tasks: codex, opencode, or cursor. A provider failure is terminal; no fallback provider is attempted."
     default: "codex"
@@ -447,9 +426,9 @@ inputs:
 
   agent-model:
     description: "Selected model name without the provider prefix. The provider is configured separately with agent-model-provider."
-    default: "gpt-5.6-luna"
-  agent-command:
-    description: "Optional executable command for the selected CLI agent. Defaults are model-aware: codex exec with --model and model_provider, opencode run --model provider/model, or agent -p --model. No fallback command is attempted."
+    default: "gpt-6-luna"
+  agent-executable:
+    description: "Optional exact CLI basename or absolute executable path. Arguments, wrappers, and alternate basenames are rejected."
     default: ""
   findings-provider:
     description: "Optional provider override for findings."
@@ -464,8 +443,8 @@ inputs:
   findings-model:
     description: "Optional model override for findings."
     default: ""
-  findings-command:
-    description: "Optional CLI command override for findings."
+  findings-executable:
+    description: "Optional validated executable override for findings."
     default: ""
   fixer-provider:
     description: "Optional provider override for fixer."
@@ -480,8 +459,8 @@ inputs:
   fixer-model:
     description: "Optional model override for fixer."
     default: ""
-  fixer-command:
-    description: "Optional CLI command override for fixer."
+  fixer-executable:
+    description: "Optional validated executable override for fixer."
     default: ""
   planner-provider:
     description: "Optional provider override for planning and conversational commands."
@@ -495,8 +474,8 @@ inputs:
   planner-model:
     description: "Optional model override for planning and conversational commands."
     default: ""
-  planner-command:
-    description: "Optional CLI command override for planning."
+  planner-executable:
+    description: "Optional validated executable override for planning."
     default: ""
   reviewer-provider:
     description: "Optional provider override for pull-request review."
@@ -510,8 +489,8 @@ inputs:
   reviewer-model:
     description: "Optional model override for pull-request review."
     default: ""
-  reviewer-command:
-    description: "Optional CLI command override for pull-request review."
+  reviewer-executable:
+    description: "Optional validated executable override for pull-request review."
     default: ""
   tester-provider:
     description: "Optional provider override for future test-planning and verification tasks."
@@ -525,12 +504,9 @@ inputs:
   tester-model:
     description: "Optional model override for test tasks."
     default: ""
-  tester-command:
-    description: "Optional CLI command override for test tasks."
+  tester-executable:
+    description: "Optional validated executable override for test tasks."
     default: ""
-  ai-pull-request-description:
-    description: "Enable AI-powered automatic updates for pull request descriptions."
-    default: "true"
   ai-pull-request-description-mode:
     description: "PR description policy: replace (full ownership), append (preserve human text), preserve (only explicit /copilot description), or disabled."
     default: "replace"