opencode-skills-collection 4.0.41 → 4.0.43

package/bundled-skills/project-state-governor/references/project-state-schema.md

@@ -0,0 +1,173 @@
+# Canonical Project-State Schema
+
+Use the smallest structure that remains easy to load and reason about.
+
+## Compact mode: `PROJECT_STATE.md`
+
+```markdown
+# Project State
+
+## Mission
+[Why the project exists. Long-lived.]
+
+## Success Criteria
+[Owner-defined durable criteria for meaningful project success.]
+
+## Current Phase
+[Current engineering/product/research phase.]
+
+## Active Workstreams
+### [Workstream ID or name]
+- Status: PLANNED | ACTIVE | BLOCKED | PAUSED | COMPLETED | CANCELLED
+- Goal: ...
+- DoD / exit condition: ...
+- Current state: ...
+- Next: ...
+
+Keep terminal workstream records long enough to preserve verified `COMPLETED`
+or `CANCELLED` transitions. During consolidation, compress old terminal
+workstreams into decision-relevant milestone or project history only when their
+detailed record no longer affects future work.
+
+## Milestones
+### [Milestone ID or name]
+- Status: PROPOSED | ACTIVE | BLOCKED | PAUSED | DONE | CANCELLED | DEFERRED
+- Goal: ...
+- DoD: ...
+- Parent: ...
+- Next: ...
+
+## Current Tasks
+### [Task ID or name]
+- Status: PROPOSED | ACTIVE | BLOCKED | DEFERRED | DONE | CANCELLED
+- Goal: ...
+- Task DoD: ...
+- Parent: ...
+- Evidence: ... [only when useful]
+- Confidence: CONFIRMED | INFERRED | UNKNOWN [only when useful]
+
+Keep terminal task records long enough to preserve the verified lifecycle transition. During consolidation, compress old `DONE` or `CANCELLED` tasks into decision-relevant milestone history when their detailed record no longer affects future work.
+
+## Active Research / Experiments
+### [Hypothesis or candidate ID]
+- Status: PROPOSED | ACTIVE | SUPPORTED | REJECTED | INCONCLUSIVE | INVALIDATED | FORWARD_ONLY
+- Hypothesis: ...
+- Protocol / stage: ...
+- Current evidence: ...
+- Provenance: ... [experiment/manifest ID when material]
+- Next authorized step: ...
+
+## Decisions
+### [Decision ID or concise title]
+- Decision: ...
+- Rationale: ...
+- Authority / provenance: ... [when material]
+
+## Constraints / Invariants
+- ...
+
+## Known Issues / Blockers
+- ...
+
+## Deferred Work
+- ...
+
+## Negative Evidence / Rejected Directions
+- [what] — [why] — [evidence] — [permanent or conditional]
+
+## Lessons / Pitfalls
+- [validated recurring mistake or owner correction worth preserving]
+
+## Recent Milestones
+- [date/commit only when useful] ...
+```
+
+## Scaled mode
+
+Use only when compact mode causes context bloat or unrelated subsystem loading.
+
+```text
+.project/
+  MANIFEST.md
+  STATE.md
+  DECISIONS.md
+  CONSTRAINTS.md
+  NEGATIVE_EVIDENCE.md
+  areas/
+    <subsystem>.md
+```
+
+### `.project/MANIFEST.md`
+Keep it short. It is the routing index, not a summary dump.
+
+```markdown
+# Project Memory Manifest
+
+## Read First
+- STATE.md — mission, phase, current workstreams and tasks, recent terminal transitions, blockers, next actions
+
+## Read When Relevant
+- DECISIONS.md — durable owner/project decisions
+- CONSTRAINTS.md — technical/business/research invariants
+- NEGATIVE_EVIDENCE.md — costly rejected directions and important lessons
+- areas/execution.md — execution subsystem state
+- areas/research.md — research subsystem state
+```
+
+### `.project/STATE.md`
+Contain mission, success criteria, phase, current workstreams, milestones,
+current tasks, recent terminal transitions, blockers, and next direction. Keep
+it sufficient for a fast cold start.
+
+Apply the compact-mode terminal retention rules in scaled mode too. Keep
+verified `COMPLETED` or `CANCELLED` workstreams and `DONE` or `CANCELLED`
+tasks until consolidation can compress them into decision-relevant milestone
+or project history without losing information that still affects future work.
+
+### `DECISIONS.md`
+Store only durable decisions that materially constrain future work.
+
+### `CONSTRAINTS.md`
+Store only constraints/invariants future agents must respect.
+
+### `NEGATIVE_EVIDENCE.md`
+Store concise costly failures, rejected directions, and validated lessons likely to prevent repeated work.
+
+### `areas/*.md`
+Use only for large independent subsystems. Do not duplicate global mission or global decisions inside area files.
+
+## Provenance rule
+
+Add provenance only when it materially improves trust. Prefer concise references:
+
+- owner decision / issue ID;
+- commit SHA;
+- test name/result;
+- contract/schema path;
+- experiment or manifest ID.
+
+## Confidence rule
+
+Use:
+
+- `CONFIRMED` for directly supported authoritative facts;
+- `INFERRED` for provisional interpretation;
+- `UNKNOWN` when evidence is insufficient.
+
+Do not represent `INFERRED` as settled truth.
+
+## Completion hierarchy
+
+Track completion at the correct level:
+
+- Session DoD
+- Task DoD
+- Milestone DoD
+- Workstream DoD
+- Mission success criteria
+
+A child completing does not automatically complete its parent.
+
+## Compression rule
+
+When state grows, remove or compress detail that is no longer decision-relevant. Git is the historical archive.

package/bundled-skills/project-state-governor/references/reconstruction-workflow.md

@@ -0,0 +1,183 @@
+# Repository State Reconstruction Workflow
+
+Use this workflow when a repository contains conflicting historical reviews, plans, TODOs, status notes, GPT summaries, branch-specific docs, or unclear progress.
+
+## 1. Establish scope and authority
+
+Identify:
+
+- repository and target branch;
+- owner-requested cleanup boundary;
+- candidate paths and their complete instruction scope: include the candidate itself when it is an existing directory, otherwise stop at its parent; for recursive directory operations, discover every nested `AGENTS.md` in the affected subtree before inspecting or mutating it;
+- compact vs scaled canonical-state mode;
+- whether deletion is explicitly authorized or only recommendations are allowed.
+
+Do not expand into unrelated feature work.
+
+Before inspecting, writing, moving, or deleting a candidate path, resolve its full `AGENTS.md` chain. Apply deeper rules only to their governed subtree, and do not let a repository-level cleanup instruction override a more specific local constraint.
+
+## 2. Inventory candidate state documents
+
+Find files likely to contain project state:
+
+- plans/TODOs;
+- reviews/audits;
+- implementation summaries;
+- status/progress/handoff docs;
+- research manifests and decision records;
+- GPT-generated summaries;
+- branch-specific notes.
+
+Do not assume every Markdown file is status documentation.
+
+Classify each file initially as:
+
+- `AUTHORITATIVE`;
+- `CURRENT_SUPPORTING`;
+- `HISTORICAL`;
+- `DUPLICATE`;
+- `STALE`;
+- `CONTRADICTORY`;
+- `GENERATED_TEMPORARY`;
+- `UNKNOWN`.
+
+## 3. Extract claims, not prose
+
+Extract only material claims affecting current state:
+
+- mission/success criteria;
+- completion claims and DoD;
+- active tasks/workstreams;
+- decisions/constraints;
+- blockers;
+- research state/results;
+- rejected directions/lessons;
+- branch assumptions.
+
+Ignore rhetorical explanation and conversation chronology unless needed as provenance.
+
+## 4. Verify each material claim
+
+Inspect only the code, tests, contracts, commits, configuration, and history necessary to evaluate claims.
+
+Classify claims:
+
+- `CURRENT_CONFIRMED`: supported by authoritative evidence;
+- `CURRENT_INFERRED`: plausible but not directly authoritative;
+- `SUPERSEDED`: once true, now replaced;
+- `FALSE`: contradicted by higher-authority evidence;
+- `CONFLICTED`: multiple legitimate interpretations remain;
+- `UNKNOWN`: insufficient evidence.
+
+Never use current code as automatic proof of intended semantics.
+Never promote `CURRENT_INFERRED` to settled truth without justification.
+
+## 5. Verify completion at the correct level
+
+For each completion claim, distinguish:
+
+- session completion;
+- task completion;
+- milestone completion;
+- workstream completion;
+- mission success.
+
+Reject parent-level completion claims supported only by child-level evidence.
+
+## 6. Resolve conflict type
+
+### OBSOLETE_HISTORY
+Statement was once valid but superseded. Keep only current canonical state.
+
+### IMPLEMENTATION_DRIFT
+Code and intended requirement differ. Determine which violates higher authority.
+
+### UNRESOLVED_BUSINESS_CONFLICT
+Multiple legitimate outcomes remain. Escalate the smallest owner decision.
+
+### FALSE_OR_UNSUPPORTED_HISTORY
+Review/AI output was never established. Do not preserve as truth.
+
+### BRANCH_DIVERGENCE
+Branches reflect different states. Keep them distinct until merge/authority is resolved.
+
+## 7. Rebuild canonical state
+
+Use `project-state-schema.md`.
+
+Rules:
+
+- preserve current durable state only;
+- preserve concise high-value negative evidence and lessons;
+- represent unresolved ambiguity explicitly;
+- attach provenance/confidence only where material;
+- do not copy whole historical documents;
+- do not create an append-only archive;
+- choose compact mode unless scaled routing clearly improves retrieval.
+
+## 8. Build a staged cleanup set
+
+For each old document choose:
+
+- `KEEP`: independent stable purpose remains;
+- `MERGE_THEN_DELETE`: unique durable content must enter canonical state first;
+- `DELETE`: redundant/stale/generated with no unique required content;
+- `OWNER_DECISION`: significance or deletion authority is genuinely uncertain.
+
+Never delete first and reconcile later.
+
+If broad deletion was not explicitly authorized, present this cleanup set for owner review before applying destructive changes.
+
+## 9. Apply authorized cleanup
+
+When authorized:
+
+- update canonical state;
+- remove obsolete redundant status files;
+- preserve legitimate technical/public docs;
+- avoid unrelated code edits;
+- keep branch-specific facts branch-specific;
+- ensure secrets/sensitive data are not copied into canonical state.
+
+## 10. Consolidate
+
+After reconstruction:
+
+- remove duplicate canonical facts;
+- compress low-value completed history;
+- retain important decisions, constraints, negative evidence, and lessons;
+- update MANIFEST if scaled mode is used.
+
+## 11. Verify
+
+Before declaring reconstruction complete, verify:
+
+- canonical state is internally consistent;
+- active tasks are actually open;
+- completion claims match the correct DoD level;
+- key decisions/constraints are represented;
+- meaningful negative evidence is preserved;
+- stale status docs no longer compete as sources of truth;
+- no unique required information was lost;
+- branch scope is represented correctly;
+- provenance/confidence caveats are accurate;
+- canonical state contains no exposed secrets copied during cleanup.
+
+## 12. Report
+
+Return only:
+
+### Project State Changes
+What became canonical or changed status.
+
+### Current Focus
+Resulting active workstream/task/research direction.
+
+### Remaining Blockers / Decisions
+Only unresolved items requiring action.
+
+### Documentation Actions
+Files kept, staged, merged/deleted, or awaiting owner review.
+
+### Evidence Notes
+Only material provenance/confidence caveats.

package/bundled-skills/salesforce-development/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: salesforce-development
 description: Expert patterns for Salesforce platform development including
-  Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs,
-  Connected Apps, and Salesforce DX with scratch orgs and 2nd generation
+  Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs, External Client Apps, and Salesforce DX with scratch orgs and 2nd generation
   packages (2GP).
 risk: safe
 source: vibeship-spawner-skills (Apache 2.0)
@@ -12,8 +11,75 @@ date_added: 2026-02-27
 # Salesforce Development
 
 Expert patterns for Salesforce platform development including Lightning Web
-Components (LWC), Apex triggers and classes, REST/Bulk APIs, Connected Apps,
-and Salesforce DX with scratch orgs and 2nd generation packages (2GP).
+Components (LWC), Apex triggers and classes, REST/Bulk APIs, External Client Apps, and Salesforce DX with scratch orgs and 2nd generation packages (2GP).
+
+## Modern Architecture Guidance
+
+### Security and User Mode
+
+For current Apex development, make the intended data-access mode explicit.
+
+- Prefer `WITH USER_MODE` for SOQL/SOSL that should enforce the running user's object permissions, FLS, sharing, and other supported security controls.
+- Use user-mode DML or `Database` methods when the operation should enforce user permissions.
+- Use system mode only when elevated access is intentional and justified.
+- `WITH SECURITY_ENFORCED` is legacy guidance and should not be used for new API 67.0+ code.
+- API 67.0 changes the platform defaults for database operations and class sharing, so do not assume older API-version behavior applies to newer code.
+
+### Integration Pattern Selection
+
+Choose an integration pattern based on latency, volume, ownership, and reliability requirements:
+
+| Requirement | Preferred pattern |
+| --- | --- |
+| Synchronous request/response | REST or Composite API |
+| Large asynchronous data movement | Bulk API 2.0 |
+| Publish business events | Platform Events |
+| Detect Salesforce record changes | Change Data Capture |
+| High-scale event consumption | Pub/Sub API |
+| Salesforce outbound authentication | Named Credentials / External Credential |
+| New OAuth client configuration | External Client App |
+
+Do not select an API only because a record-count threshold is crossed. Evaluate data volume, latency, transaction boundaries, retry behavior, error handling, and monitoring.
+
+### Event-Driven Integration
+
+Prefer events over continuous polling when the platform and integration support it.
+
+Bulk API 2.0 supports event-driven job status and result notifications through Pub/Sub API, including partial query results. Use polling only when event-driven processing is unavailable or unnecessary.
+
+For asynchronous external calls, design for idempotency. A timeout does not prove that the remote operation failed; retrying a non-idempotent request can create duplicates.
+
+Use a stable idempotency key when the receiving system supports it.
+
+### Authentication
+
+For new Salesforce API integrations, prefer External Client Apps. Existing Connected Apps can continue to operate, but new Connected App creation is restricted from Spring '26.
+
+Prefer OAuth-based authentication over username/password SOAP `login()`. Salesforce has announced retirement of SOAP `login()` for API versions 31.0 through 64.0 in Summer '27.
+
+Never place private keys, client secrets, passwords, or long-lived access tokens in source code.
+
+### API Versioning
+
+Do not copy a hard-coded API version from an old example into a new integration.
+
+Use the API version appropriate for the target org and integration, and update it deliberately as platform versions change. Examples should use `{apiVersion}` when the exact version is not material.
+
+### Production Deployment
+
+For production metadata deployments, validate first:
+
+```bash
+sf project deploy validate --target-org my-prod --source-dir force-app --test-level RunLocalTests
+```
+
+If validation succeeds, use the returned job ID for:
+
+```bash
+sf project deploy quick --target-org my-prod --job-id <validation-job-id>
+```
+
+Quick deploy reuses the successful validation and therefore skips rerunning Apex tests. Do not use `project deploy quick` for sandboxes; use `project deploy start` or a dry run as appropriate.
 
 ## Patterns
 
@@ -87,7 +153,7 @@ public with sharing class MyController {
       SELECT Id, Name, Email, Phone
       FROM Contact
       WHERE AccountId = :accountId
-      WITH SECURITY_ENFORCED
+      WITH USER_MODE
       LIMIT 100
     ];
   }
@@ -247,7 +313,7 @@ public class IndustryChangeQueueable implements Queueable, Database.AllowsCallou
         SELECT Id, Name, Industry, OwnerId
         FROM Account
         WHERE Id IN :accountIds
-        WITH SECURITY_ENFORCED
+        WITH USER_MODE
       ];
 
       // Process and make callout
@@ -287,7 +353,7 @@ public class IndustryChangeQueueable implements Queueable, Database.AllowsCallou
       SELECT Id, Industry__c, AccountId
       FROM Opportunity
       WHERE AccountId IN :accIds
-      WITH SECURITY_ENFORCED
+      WITH USER_MODE
     ];
 
     Map<Id, Account> accountMap = new Map<Id, Account>([
@@ -307,7 +373,9 @@ public class IndustryChangeQueueable implements Queueable, Database.AllowsCallou
     // Log error
     System.debug(LoggingLevel.ERROR, 'Queueable failed: ' + e.getMessage());
 
-    // Retry with exponential backoff (max 3 retries)
+    // Retry only when the operation is idempotent. This example does not implement
+    // delayed exponential backoff; production integrations should use a durable,
+    // observable retry mechanism.
     if (retryCount < 3) {
       // Chain new job for retry
       System.enqueueJob(new IndustryChangeQueueable(accountIds, retryCount + 1));
@@ -329,25 +397,26 @@ public class IndustryChangeQueueable implements Queueable, Database.AllowsCallou
 - long-running operations
 - callouts from triggers
 
-### REST API Integration with Connected App
+### REST API Integration with External Client App
 
-External integrations use Connected Apps with OAuth 2.0. JWT Bearer flow
-for server-to-server, Web Server flow for user-facing apps. Always use
-Named Credentials for secure callout configuration.
+New integrations should use External Client Apps (ECA) with OAuth 2.0. Existing
+Connected Apps continue to work, but creation of new Connected Apps is restricted
+from Spring '26. Use Named Credentials for Salesforce outbound callouts.
 
 // Node.js - JWT Bearer Flow (server-to-server)
 import jwt from 'jsonwebtoken';
 import fs from 'fs';
 
 class SalesforceClient {
-  private accessToken: string | null = null;
-  private instanceUrl: string | null = null;
+  protected accessToken: string | null = null;
+  protected instanceUrl: string | null = null;
   private tokenExpiry: number = 0;
 
   constructor(
     private clientId: string,
     private username: string,
     private privateKeyPath: string,
+    protected apiVersion: string,
     private loginUrl: string = 'https://login.salesforce.com'
   ) {}
 
@@ -394,7 +463,7 @@ class SalesforceClient {
     await this.authenticate();
 
     const response = await fetch(
-      `${this.instanceUrl}/services/data/v59.0/query?q=${encodeURIComponent(soql)}`,
+      `${this.instanceUrl}/services/data/${this.apiVersion}/query?q=${encodeURIComponent(soql)}`,
       {
         headers: {
           'Authorization': `Bearer ${this.accessToken}`,
@@ -414,7 +483,7 @@ class SalesforceClient {
     await this.authenticate();
 
     const response = await fetch(
-      `${this.instanceUrl}/services/data/v59.0/sobjects/${sobject}`,
+      `${this.instanceUrl}/services/data/${this.apiVersion}/sobjects/${sobject}`,
       {
         method: 'POST',
         headers: {
@@ -449,7 +518,8 @@ class SalesforceClient {
 const sf = new SalesforceClient(
   process.env.SF_CLIENT_ID!,
   process.env.SF_USERNAME!,
-  './certificates/server.key'
+  './certificates/server.key',
+  process.env.SF_API_VERSION!
 );
 
 const accounts = await sf.query(
@@ -460,7 +530,7 @@ const accounts = await sf.query(
 
 - external integration
 - REST API access
-- connected apps
+- external client apps and connected apps
 
 ### Bulk API 2.0 for Large Data Operations
 
@@ -496,7 +566,7 @@ class SalesforceBulkClient extends SalesforceClient {
 
   private async createBulkJob(sobject: string, operation: string): Promise<any> {
     const response = await fetch(
-      `${this.instanceUrl}/services/data/v59.0/jobs/ingest`,
+      `${this.instanceUrl}/services/data/${this.apiVersion}/jobs/ingest`,
       {
         method: 'POST',
         headers: {
@@ -520,7 +590,7 @@ class SalesforceBulkClient extends SalesforceClient {
     const csv = this.recordsToCSV(records);
 
     await fetch(
-      `${this.instanceUrl}/services/data/v59.0/jobs/ingest/${jobId}/batches`,
+      `${this.instanceUrl}/services/data/${this.apiVersion}/jobs/ingest/${jobId}/batches`,
       {
         method: 'PUT',
         headers: {
@@ -534,7 +604,7 @@ class SalesforceBulkClient extends SalesforceClient {
 
   private async closeJob(jobId: string): Promise<void> {
     await fetch(
-      `${this.instanceUrl}/services/data/v59.0/jobs/ingest/${jobId}`,
+      `${this.instanceUrl}/services/data/${this.apiVersion}/jobs/ingest/${jobId}`,
       {
         method: 'PATCH',
         headers: {
@@ -548,12 +618,12 @@ class SalesforceBulkClient extends SalesforceClient {
 
   private async waitForJobCompletion(jobId: string): Promise<any> {
     const maxWaitTime = 10 * 60 * 1000;  // 10 minutes
-    const pollInterval = 5000;  // 5 seconds
+    const pollInterval = 5000;  // fallback polling interval; prefer event-driven completion when available
     const startTime = Date.now();
 
     while (Date.now() - startTime < maxWaitTime) {
       const response = await fetch(
-        `${this.instanceUrl}/services/data/v59.0/jobs/ingest/${jobId}`,
+        `${this.instanceUrl}/services/data/${this.apiVersion}/jobs/ingest/${jobId}`,
         {
           headers: { 'Authorization': `Bearer ${this.accessToken}` }
         }
@@ -584,7 +654,7 @@ class SalesforceBulkClient extends SalesforceClient {
 
   private async getFailedResults(jobId: string): Promise<any[]> {
     const response = await fetch(
-      `${this.instanceUrl}/services/data/v59.0/jobs/ingest/${jobId}/failedResults`,
+      `${this.instanceUrl}/services/data/${this.apiVersion}/jobs/ingest/${jobId}/failedResults`,
       {
         headers: { 'Authorization': `Bearer ${this.accessToken}` }
       }
@@ -665,7 +735,7 @@ the day, unlike sandbox refresh limits.
   ],
   "namespace": "myns",
   "sfdcLoginUrl": "https://login.salesforce.com",
-  "sourceApiVersion": "59.0"
+  "sourceApiVersion": "67.0"
 }
 
 # Development workflow commands
@@ -872,13 +942,12 @@ Dynamic SOQL with string concatenation is vulnerable
 
 Message: Dynamic SOQL with concatenation. Use bind variables or String.escapeSingleQuotes().
 
-### Missing WITH SECURITY_ENFORCED
+### Missing Explicit Data Access Mode
 
 Severity: WARNING
 
-SOQL should enforce FLS/CRUD permissions
-
-Message: SOQL without security enforcement. Add WITH SECURITY_ENFORCED.
+Review Apex data access to ensure the intended user/system security model is explicit.
+Prefer `WITH USER_MODE` for user-context SOQL/SOSL and user-mode DML where appropriate.
 
 ### Hardcoded Salesforce ID
 
@@ -896,21 +965,21 @@ Credentials must use Named Credentials or Custom Metadata
 
 Message: Hardcoded credentials. Use Named Credentials or Custom Metadata.
 
-### Direct DOM Manipulation in LWC
+### Unnecessary DOM Manipulation in LWC
 
 Severity: WARNING
 
-LWC uses shadow DOM, direct manipulation breaks encapsulation
-
-Message: Direct DOM access in LWC. Use this.template.querySelector() or data binding.
+Prefer declarative template rendering and component state. When DOM access is
+actually required, scope it to elements owned by the component; prefer `lwc:ref`
+and `this.refs` where appropriate.
 
-### Reactive Property Without @track
+### Unnecessary @track Usage
 
 Severity: INFO
 
-Complex object properties need @track for reactivity
-
-Message: Object assignment may need @track for reactivity (post-Spring '20 objects are auto-tracked).
+LWC fields are reactive by default. Use `@track` only when you need deep
+tracking of mutations to properties of plain objects or elements of arrays.
+Prefer assigning a new object or array instead of mutating state in place.
 
 ### Wire Without Refresh After DML
 
@@ -945,6 +1014,7 @@ Message: DML after @wire without refreshApex. Data may be stale.
 - User mentions or implies: connected app
 
 ## Limitations
+- Salesforce platform behavior and API versions change frequently; verify current official documentation before implementing version-sensitive features.
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.