ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/projects/template-maintenance/DESIGN.md

@@ -0,0 +1,134 @@
+# Template-Maintenance Tooling — Design & Scoping
+
+**Status:** DESIGN ONLY — not started. Implementation deferred until after the backwards-compat
+cutover release. This doc scopes the work so the AI agent (integrations agent) can pick it up.
+**Owner:** Oscar. **Drafted:** 2026-07-02.
+
+---
+
+## Why
+
+A customer delivery needs **300+ templates** built/maintained programmatically (deadline ~Sept
+2026 for the CSV→templates pipeline). We need a GraphQL-native way to **build and update templates
+(workflows)** — create stages/sections/fields/forces/strategies/etc., and later diff a desired
+template against a live one and apply only the delta.
+
+This is a **new, additive** capability. It has **no end-script dependencies** and does **not** touch
+the maintained cutover integrations (toocs-coding, cans-upsert, supplier-documents, and Travis's
+upcoming mitre10). **OozeRedirect stays for the APIv2-shaped cases.** Template editing needs **no
+backwards compatibility** — we rewrite it cleanly, reusing the *ideas* (not the code) proven for
+APIv2, and add specs (preventative — see "Testing philosophy").
+
+Can ship in the **same release** as the cutover fixes as long as it **loads** and **passes the tests
+we can gather** (no runtime coupling to existing scripts).
+
+---
+
+## What already exists (survey, 2026-07-01/02) — this is "extend a pattern", not "build new"
+
+### Gem (`ecoportal-api-graphql`) — the mutation surface is largely built
+- **91** `input/workflow_command/*.rb` command inputs (stages, sections, fields, forces, bindings,
+  tasks, strategies, operations, recipients, callbacks, gauge stops, linked fields, select options…).
+- `input/workflow_command.rb` — `WorkflowCommand::COMMAND_MAP` registry (`SCHEMA_VERSION`).
+- `mutation/page/execute_workflow_commands.rb` — applies a command batch (`executeWorkflowCommands`).
+- `query/pages_workflow_commands.rb` + `base/pages_workflow*` — the workflow READ model.
+- `base/force.rb` — queues `editForce`/`addBinding` commands (forces ARE mutable via the command-bus;
+  see `.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md`).
+
+### eco-helpers — the samples space + the diff→commands PRECEDENT
+- `lib/eco/api/usecases/graphql/samples/pages/{page,org_page}/{base,dsl}.rb` + `pages/CLAUDE.md` —
+  the **established sample convention**: each sample is a `base.rb` + `dsl.rb` pair. A template
+  sample slots in as `samples/pages/template/{base,dsl}.rb`.
+- `lib/eco/api/usecases/graphql/samples/location/command/{dsl,service,service/tree_update,results,
+  track_changed_ids}.rb` + `samples/location/service/tree_diff/convertible/*` — a **working
+  diff→apply-commands engine** for LOCATION STRUCTURE (which uses `location_structure/apply_commands`
+  in the gem). This is the architectural precedent to mirror for templates.
+  - **`track_changed_ids` is the hard part already solved:** newly created nodes get server-assigned
+    ids that *subsequent* commands must reference (a new stage's id feeds the addSection targeting it).
+    Template build has the identical id-threading problem — reuse this pattern, don't reinvent it.
+
+---
+
+## Design: template editing = the location diff→commands engine, retargeted to workflow commands
+
+Mirror `samples/location/command` + `tree_diff`, but:
+- **Target model:** template/workflow (stages → sections → fields → forces/strategies/…) instead of
+  the location tree.
+- **Command vocabulary:** the 91 `WorkflowCommand` inputs instead of location `apply_commands`.
+- **Apply mutation:** `executeWorkflowCommands` instead of `applyCommands`.
+- **DSL home:** `samples/pages/template/{base,dsl}.rb`, following the existing `page`/`org_page` shape.
+
+Two capabilities, in order of need:
+1. **Build from scratch** — declare a desired template via the DSL → emit an ordered command sequence
+   (addStage → addSection → addField → …) → `executeWorkflowCommands`, threading server-assigned ids
+   between commands (`track_changed_ids` pattern) → read back to verify.
+2. **Diff & update** — read the live template's workflow structure, diff against the desired DSL,
+   emit only the delta commands (the eventual UAT→PROD `template-diff-deploy` need). Build (1) first;
+   (2) reuses the same command emitter + the tree_diff approach.
+
+---
+
+## Reference target (the test/characterization anchor)
+
+Reconstruct **template sample `6a3fa5b8f89e07c758df622b`** step by step. Capture it once as a pinned
+fixture (a `dump_template` tool — extend `tests/dump_page_model.rb`'s approach to fetch the workflow
+structure via the `pages_workflow_commands`/`PagesWorkflow` read). Each construction step reproduces
+one piece of that sample; the fixture is the golden master to diff against.
+
+---
+
+## Testing philosophy (aligned with how our devs actually work)
+
+NOT specs-first-as-design. Specs here are **preventative** (guard against future breakage), matching
+the team's practice. Two layers:
+1. **Offline serialization specs (CI-pure, fast):** each `WorkflowCommand` input → correct GraphQL
+   payload; the command emitter produces the right ordered sequence + id-threading for a given DSL.
+   Added incrementally as each command type is wired — regression net, not design driver.
+2. **Live characterization harness (sandbox org, NOT CI):** replay the command sequence to reconstruct
+   sample `6a3fa5b8…622b`, fetch the result, assert structure-equivalence vs the pinned fixture.
+   `executeWorkflowCommands` mutates server state, so this runs against a sandbox/dev org by hand,
+   not in CI. Doubles as the regression net for the 300+ template delivery.
+
+Specs go in **eco-helpers** (for the samples/pages layer) and in the gem (for command serialization).
+
+---
+
+## Phases
+
+- **Phase 0 — Study & capture (read-only; no prod writes):** read the two precedents
+  (`samples/pages/{page,org_page}/{base,dsl}.rb` + `pages/CLAUDE.md`; `samples/location/command` +
+  `tree_diff`, esp. `track_changed_ids`); build `dump_template` + pin sample `6a3fa5b8…622b`; map which
+  of the 91 commands the sample needs.
+- **Phase 1 — Gem read-back + ergonomic execute facade:** confirm the `PagesWorkflow` read returns a
+  diff-able structure; ensure `executeWorkflowCommands` has a clean builder facade. Offline command
+  specs (incremental).
+- **Phase 2 — `samples/pages/template/{base,dsl}.rb` (build-from-scratch):** DSL → ordered command
+  emitter + id-threading → execute → read-back verify.
+- **Phase 3 — Characterization suite:** the sandbox replay-the-sample suite (one assertion group per
+  construction step) vs the Phase 0 fixture.
+- **Phase 4 — Diff & update:** read live template, diff vs desired, emit delta commands (reuses the
+  tree_diff approach). Feeds `template-diff-deploy` (UAT→PROD via changelog).
+- **Phase 5 — Ship:** rides the same release; gated only on "loads + passes gathered tests"; no
+  end-script deps; OozeRedirect untouched.
+
+---
+
+## Constraints / guardrails
+- No runtime coupling to the maintained integrations; OozeRedirect is for APIv2 cases only.
+- `WorkflowCommandInput` API is **volatile** — design for change (thin, data-driven command mapping;
+  keep `SCHEMA_VERSION` in view).
+- Prefer capturing verified platform facts in the **shared** knowledge base (not machine-local memory)
+  — the forces-RCA lesson.
+
+## Open questions (for the implementing agent / Oscar)
+1. Sandbox org for the live characterization harness — which org/creds?
+2. Is the `PagesWorkflow` read complete enough to diff a full template, or are there gaps (like the
+   forces READ query `Query::PageWithForces`, which is WIP)?
+3. Command ordering/dependency rules — is there a canonical order the backend expects, or does
+   `executeWorkflowCommands` resolve intra-batch references? (drives the id-threading design)
+4. Does `6a3fa5b8…622b` exercise forces? If so, coordinate with the `force_support?` read/write split.
+
+## Related
+- `.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md` (command-bus + forces)
+- Memory: post-cutover-priorities, project-template-csv-pipeline, project-template-diff-deploy,
+  project-template-update-architecture, project-workflow-space.

data/.ai-assistance/projects/workflow-space/TODO.md

@@ -0,0 +1,213 @@
+# TODOs — Workflow Space Project
+
+> Created 2026-06-11 from live schema introspection `20260605T101224_live_ep_graphql_schema.graphql.json`.
+> Phases W1-W5 implemented on branch `pages`. All completed 2026-06-11.
+
+---
+
+## Phase W1 — Read Model (PagesWorkflow)
+
+- [x] **W1.1** `Base::PagesWorkflow` — `autoPageCreationEnabled`, `stages` (passarray),
+  `fields` (embeds_many RegisterField), `commands` connection reference.
+  *Done 2026-06-11 — `lib/ecoportal/api/graphql/base/pages_workflow.rb`*
+
+- [x] **W1.2** `Base::PagesWorkflow::RegisterField` — `key`, `name`, `type`, `total`,
+  `missing`, `enableCrossRegisterReporting`.
+  *Done 2026-06-11 — `base/pages_workflow/register_field.rb`*
+
+- [x] **W1.3** `Base::PagesWorkflow::CallbackType` — `id`, `triggerCondition`, `operations`
+  (dispatched via OperationInterface), `triggers` (dispatched via TriggerInterface).
+  *Done 2026-06-11 — `base/pages_workflow/callback_type.rb`*
+
+- [x] **W1.4** `Base::PagesWorkflow::OperationInterface` + three concrete classes:
+  `Operations::AssignTo` (targetTaskType, escalationLevels),
+  `Operations::CreatePage` (templateId, crossReferenceFieldId),
+  `Operations::SendNotification` (recurring, emailConfig, inSystemConfig, recipientConfig).
+  `from_doc` dispatches on `__typename`.
+  *Done 2026-06-11 — `base/pages_workflow/operation_interface.rb` + `operations/`*
+
+- [x] **W1.5** `Base::PagesWorkflow::TriggerInterface` + concrete class:
+  `Triggers::ConditionalLogic` (filters: [StoredEsFilter!]).
+  `from_doc` dispatches on `__typename`.
+  *Done 2026-06-11 — `base/pages_workflow/trigger_interface.rb` + `triggers/`*
+
+- [x] **W1.6** Supporting value objects: `TimeDelayConfig`, `EscalationLevel`,
+  `RecipientConfig`, `EmailConfig`, `InSystemConfig`, `UserSelection`,
+  `PeopleFieldSelection`, `TaskConfigSelection`, `ActionTypeSelection`, `MailboxFieldSelection`.
+  *Done 2026-06-11*
+
+- [x] **W1.7** `Base::PagesWorkflow::CommandInterface` + three concrete classes:
+  `CommandChange` (changes: [Change!]), `CommandChangeMessage` (changeMessages: [String!]),
+  `CommandEsChange` (changes: [StoredEsFilterChange!]).
+  *Done 2026-06-11 — `base/pages_workflow/command_interface.rb`*
+
+- [x] **W1.8** `Model::PagesWorkflow < Base::PagesWorkflow` — `class_resolver` wiring
+  for `command_connection_class`, `operation_class`, `trigger_class`.
+  *Done 2026-06-11 — `lib/ecoportal/api/graphql/model/pages_workflow.rb`*
+
+- [x] **W1.9** `Connection::PagesWorkflowCommand` — paginated connection for command log.
+  *Done 2026-06-11 — `lib/ecoportal/api/graphql/connection/pages_workflow_command.rb`*
+
+- [x] **W1.10** Three fragments in `fragment/pages_workflow.rb`:
+  `PagesWorkflowFields`, `PagesWorkflowCallbackFields`, `PagesWorkflowCommandFields`.
+  *Done 2026-06-11*
+
+---
+
+## Phase W2 — Mutation: ExecuteWorkflowCommands
+
+- [x] **W2.1** `Mutation::Page::ExecuteWorkflowCommands` — `field_name :executeWorkflowCommands`,
+  `query(id:, patch_ver:, commands:)` method, `default_payload_block` (patchVer + item +
+  errors). `payload_class` → `Payload::ExecuteWorkflowCommands`.
+  *Done 2026-06-11 — `mutation/page/execute_workflow_commands.rb`*
+
+- [x] **W2.2** `Payload::ExecuteWorkflowCommands` — `patchVer`, `item` (Model::PagesWorkflow),
+  `success?`, `error?`, `body`.
+  *Done 2026-06-11 — `payload/execute_workflow_commands.rb`*
+
+---
+
+## Phase W3 — Input: WorkflowCommand dispatcher
+
+- [x] **W3.1** `Input::WorkflowCommand` — `SCHEMA_VERSION`, `COMMAND_MAP` (all 90 schema
+  keys mapped to Ruby module constant strings), `.build(key, **kwargs)`, `.valid_key?`,
+  `.build_commands`.
+  *Done 2026-06-11 — `lib/ecoportal/api/graphql/input/workflow_command.rb`*
+
+---
+
+## Phase W4 — Sub-input modules (~83 commands)
+
+All sub-input modules follow the pattern:
+`module CommandName; SCHEMA_VERSION; VALID_KEYS; def self.build(**kwargs); end`
+
+- [x] **W4.1** Page-level: `EditPage`, `EditPageCreatorPermissions`.
+  *Done 2026-06-11*
+
+- [x] **W4.2** Stage structural: `AddStage`, `RemoveStage`, `EditStage`, `MoveStage`.
+  *Done 2026-06-11*
+
+- [x] **W4.3** Stage permissions: `EditCreatorPermissions`, `EditRestrictCommentTagging`,
+  `AddCommentTaggingUserGroup`, `RemoveCommentTaggingUserGroup`,
+  `EditRestrictTaskAssignment`, `AddTaskAssignmentUserGroup`,
+  `RemoveTaskAssignmentUserGroup`, `AddStageTag`, `RemoveStageTag`.
+  *Done 2026-06-11*
+
+- [x] **W4.4** Section: `AddSection`, `RemoveSection`, `AddStageSection`,
+  `RemoveStageSection`, `EditSectionHeader`, `CollapseSection`, `ExpandSection`,
+  `ReorderSection`.
+  *Done 2026-06-11*
+
+- [x] **W4.5** Task: `AddTask`, `RemoveTask`, `EditTaskDue`, `RemoveTaskDue`,
+  `RemoveTaskPriorityLevel`, `EditRequiredSignOffs`, `EditReminder`.
+  *Done 2026-06-11*
+
+- [x] **W4.6** Strategy: `AddDefaultStrategy`, `EditDefaultStrategy`,
+  `RemoveDefaultStrategy`, `AddDefaultDirectStrategyUser`,
+  `RemoveDefaultDirectStrategyUser`, `AddStrategy`, `EditStrategy`,
+  `RemoveStrategy`, `AddDirectStrategyUser`, `RemoveDirectStrategyUser`,
+  `AddOperationStrategy`, `EditOperationStrategy`, `RemoveOperationStrategy`,
+  `AddOperationDirectStrategyUser`, `RemoveOperationDirectStrategyUser`.
+  *Done 2026-06-11*
+
+- [x] **W4.7** Callback + Operation: `AddWorkflowCallback`, `RemoveCallback`,
+  `EditTrigger`, `AddOperation`, `EditOperation`, `RemoveOperation`.
+  *Done 2026-06-11*
+
+- [x] **W4.8** Recipients (10 variants): `AddRecipientUser`, `RemoveRecipientUser`,
+  `AddRecipientPeopleField`, `RemoveRecipientPeopleField`, `AddRecipientTaskConfig`,
+  `RemoveRecipientTaskConfig`, `AddRecipientActionType`, `RemoveRecipientActionType`,
+  `AddRecipientFilter`, `RemoveRecipientFilter`.
+  *Done 2026-06-11*
+
+- [x] **W4.9** Scheduled: `AddScheduledCallback`, `EditScheduledCallback`,
+  `RemoveScheduledCallback`, `AddScheduledCallbackAction`, `AddActionTag`,
+  `RemoveActionTag`.
+  *Done 2026-06-11*
+
+- [x] **W4.10** Field structural: `AddField`, `MoveField`, `RemoveField`.
+  *Done 2026-06-11*
+
+- [x] **W4.11** Field configuration: `EditFieldConfiguration` (base) + 12 byType
+  sub-modules in `field_config/`: `PlainText`, `RichText`, `Date`, `Gauge`, `Select`,
+  `People`, `CrossReference`, `ImageGallery`, `LocationField`, `ContractorEntities`,
+  `Signature`, `Table`.
+  *Done 2026-06-11*
+
+- [x] **W4.12** Select options: `AddSelectFieldOption`, `EditSelectFieldOption`,
+  `RemoveSelectFieldOption`.
+  *Done 2026-06-11*
+
+- [x] **W4.13** Gauge stops: `AddGaugeFieldStop`, `EditGaugeFieldStop`,
+  `RemoveGaugeFieldStop`.
+  *Done 2026-06-11*
+
+- [x] **W4.14** Linked fields: `AddLinkedFieldConfig`, `EditLinkedFieldConfig`,
+  `RemoveLinkedFieldConfig`.
+  *Done 2026-06-11*
+
+- [x] **W4.15** Forces / bindings: `AddForce`, `RemoveForce`, `EditForce`,
+  `ReorderForces`, `AddBinding`, `EditBinding`, `RemoveBinding`,
+  `AddLinkedHelper`, `EditLinkedHelper`, `RemoveLinkedHelper`.
+  *Done 2026-06-11*
+
+---
+
+## Phase W5 — Concerns and Cross-cutting
+
+- [x] **W5.1** `Concerns::Deprecation` — `SCHEMA_VERSION`, `WARNED` (Set), `warn_once(key, msg)`.
+  Process-level warning deduplicator used across this area and others.
+  *Done 2026-06-11 — `lib/ecoportal/api/graphql/concerns/deprecation.rb`*
+
+- [x] **W5.2** Code-spec docs:
+  - `.ai-assistance/code/workflow-space.md` — read model + command bus spec.
+  - `.ai-assistance/code/workflow-command-guide.md` — full command mapping + usage examples.
+  *Done 2026-06-11*
+
+---
+
+## Notes on Implementation Approach
+
+### SCHEMA_VERSION tracking
+
+Every file in the workflow space carries `SCHEMA_VERSION = '20260605'.freeze`. This
+matches the introspection snapshot date. When engineering changes the Workflow Builder
+schema, re-run introspection, update the constant across all affected files, and diff
+`WorkflowCommandInput` against the new schema to catch added or removed command keys.
+
+### Concerns::Deprecation
+
+The `warn_once` pattern guards against repeated warnings from hot code paths (e.g.
+schema version mismatches, deprecated method calls). It holds its warned-key `Set`
+at the module level — process-global, not per-instance. This is intentional.
+
+---
+
+## Phase F — Deferred Items
+
+These items were identified during W1-W5 but deferred due to complexity or low
+immediate priority.
+
+- [x] **F.1** Kickstand mutations — `startKickstandWorkflow`, `stopKickstandWorkflow`,
+  `failKickstandWorkflow`, `bulkUpdateKickstandWorkflows`.
+  `Base::Kickstand::Workflow`, `Payload::Kickstand::{Workflow,BulkUpdateWorkflows}`,
+  `Mutation::Kickstand::{Start,Stop,Fail}Workflow + BulkUpdateWorkflows`,
+  `Builder::Kickstand` wired as `api.kickstand`.
+  *Done 2026-06-12*
+
+- [x] **F.2** `PagesWorkflow.commands` connection — `Query::PagesWorkflowCommands`
+  navigates `currentOrganization.page.workflow.commands`; uses `PagesWorkflowCommandFields`.
+  *Done 2026-06-12*
+
+- [x] **F.3** Full Stage fragment with `workflowCallbacks` — `Fragment::StageWithCallbacksFields`
+  on `Stage` spreads `PagesWorkflowCallbackFields` into `workflowCallbacks`.
+  Stage model already had `workflow_callbacks` accessor; now it can be populated.
+  *Done 2026-06-12*
+
+- [x] **F.4** `Builder::Page#execute_workflow_commands` — already shipped with W1-W5
+  (`builder/page.rb:68`).
+
+- [x] **F.5** Rake task `schema_drift` — compares `WorkflowCommandInput` schema keys vs
+  `COMMAND_MAP`, and audits `SCHEMA_VERSION` currency across all workflow-space files.
+  Run: `bundle exec rake schema_drift`.
+  *Done 2026-06-12*

data/.ai-assistance/reinstall-claude-desktop-windows.md

@@ -0,0 +1,136 @@
+# Reinstall Claude Desktop App on Windows (MSIX → Standard)
+
+**Why:** The default Claude Desktop installer uses MSIX packaging, which silently redirects
+AppData writes into a sandboxed container. This breaks MCP config paths, plugin loading,
+and adds an extra layer of isolation on top of CoWork's sandbox.
+This guide switches to a standard (non-sandboxed) installation.
+
+**Does this affect Claude Code CLI?** No. The CLI is an independent npm/winget package.
+This procedure does not touch it.
+
+---
+
+## Before you start
+
+### 1. Back up your session data
+
+Copy this entire folder somewhere safe (e.g. `C:\claude\backup\`):
+
+```
+C:\Users\<username>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\
+```
+
+This contains your sessions, config, and plugins. Everything else (repos, projects) is
+unaffected — it lives on your filesystem independently of the app.
+
+### 2. Note your MCP config location
+
+Your current working config is at:
+```
+C:\Users\<username>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
+```
+Copy this file separately so you can reference it after reinstall.
+
+---
+
+## Step 1 — Kill Claude processes
+
+Open **PowerShell as Administrator** and run:
+
+```powershell
+Get-Process *claude*,*chrome-native-host*,*cowork* -ErrorAction SilentlyContinue | Stop-Process -Force
+```
+
+---
+
+## Step 2 — Remove the MSIX package
+
+In the same Admin PowerShell:
+
+```powershell
+Get-AppxPackage -Name "Claude*" -AllUsers | Remove-AppxPackage -AllUsers -ErrorAction SilentlyContinue
+```
+
+---
+
+## Step 3 — Delete the sandboxed package folder
+
+In File Explorer, navigate to:
+```
+%LOCALAPPDATA%\Packages\
+```
+Delete the folder named `Claude_pzs8sxrjxfjjc` (or similar).
+
+---
+
+## Step 4 — Allow apps from any source (one-time Windows setting)
+
+To prevent Windows from silently re-packaging the installer as MSIX:
+
+`Settings → Apps → Advanced app settings → Choose where to get apps → set to Anywhere`
+
+---
+
+## Step 5 — Install via winget (standard path)
+
+Open a **standard (non-admin) PowerShell** and run:
+
+```powershell
+winget install Anthropic.Claude
+```
+
+If winget doesn't find it, download the standalone `.exe` directly from
+**https://claude.com/download** and run it. Do not use the Microsoft Store.
+
+---
+
+## Step 6 — Launch Claude and confirm paths
+
+After first launch, verify the config now lives at the standard location:
+```
+C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json
+```
+If that file exists, the sandboxing is gone.
+
+---
+
+## Step 7 — Restore your session data
+
+Copy your backup into the new location:
+```
+From: C:\claude\backup\Claude\
+To:   C:\Users\<username>\AppData\Roaming\Claude\
+```
+
+**Merge carefully** — if the reinstall already created files there, prioritise your backup
+for `local-agent-mode-sessions\` and `claude_desktop_config.json`.
+Do not blindly overwrite the whole folder.
+
+---
+
+## Step 8 — Restore MCP config
+
+If your `claude_desktop_config.json` did not carry over from the backup, copy your saved
+copy from Step 0 into `AppData\Roaming\Claude\claude_desktop_config.json`.
+
+Restart Claude Desktop. Check Settings → Developer to confirm MCPs are loading.
+
+---
+
+## After reinstall
+
+- CoWork sessions should resume from where you left off
+- MCP "Edit Config" button will now open the correct file
+- Plugin skills will load from the correct paths
+- The CoWork sandbox will no longer be inside an MSIX container layer
+
+---
+
+## What is NOT affected by this reinstall
+
+| Thing | Safe? | Notes |
+|-------|-------|-------|
+| Claude Code CLI | ✓ | Separate npm/winget install, untouched |
+| Git repos (e.g. ecoportal-api-graphql) | ✓ | Live on filesystem, nothing to do with the app |
+| `.claude/` folder in repos | ✓ | Part of the repo, git-tracked |
+| `local_paths.md` | ✓ | Git-ignored but stays on your disk |

data/.ai-assistance/scripts/CLAUDE.md

@@ -0,0 +1,150 @@
+# Scripts
+
+These scripts move token-expensive work (file scanning, UUID gen, archiving) to CPU.
+Agents call scripts and read their output — they do not replicate this logic in prose.
+
+## Script index
+
+| Script | Language | Called by | Purpose |
+|--------|----------|-----------|---------|
+| `setup-mcps.ts` | TypeScript | Human (once per machine) | Write GitKraken + GitLab MCP entries to Claude Desktop config |
+| `setup-mcps.test.ts` | TypeScript | CI / on-demand | Unit tests for setup-mcps.ts logic |
+| `bridge-init.sh` | Bash | Code (startup) | Detect env, scan inbox+stale tasks, return JSON summary |
+| `lock-acquire.sh` | Bash | Either | Atomically acquire bridge LOCK; detects stale locks by mtime |
+| `task-create.ts` | TypeScript | CoWork or Code | Create a new inbox task file |
+| `task-read.ts` | TypeScript | Either | Parse a task file → structured JSON (reduces read token cost) |
+| `task-complete.ts` | TypeScript | Code (after finishing) | Write outbox, archive pair |
+| `check-outbox.sh` | Bash | CoWork | Check if Code has responded to a task |
+| `bridge-status.sh` | Bash | Either | Quick dashboard: counts, last activity |
+| `capabilities-check.ts` | TypeScript | Scheduled / on-demand | Verify capabilities, update assumptions-log |
+
+## Usage
+
+### setup-mcps.ts
+Run once per machine when onboarding. Writes GitKraken + GitLab MCP entries into
+Claude Desktop's global config. Safe to re-run — merges, never overwrites unrelated entries.
+```bash
+npx ts-node .ai-assistance/scripts/setup-mcps.ts
+# prompts for GitLab PAT (defaults from .env), then writes claude_desktop_config.json
+# backs up existing config to claude_desktop_config.json.backup first
+```
+
+### setup-mcps.test.ts
+```bash
+npx ts-node .ai-assistance/scripts/setup-mcps.test.ts
+# runs unit tests for parseEnvFile, buildMcpEntries, mergeConfig, getConfigPath
+# exits 0 on all pass, 1 if any fail
+```
+
+### bridge-init.sh
+```bash
+bash .ai-assistance/scripts/bridge-init.sh
+# outputs: {"env":"code","user":"oscar","pending":2,"tasks":[...],"stale":1,"stale_tasks":["oscar-abc-old-task.md"]}
+# also writes output to .ai-assistance/bridge/STATUS (read by Code on startup)
+# stale_tasks: IN_PROGRESS files older than 1 hour — likely crashed sessions
+```
+
+### lock-acquire.sh
+```bash
+result=$(bash .ai-assistance/scripts/lock-acquire.sh \
+  --agent code \
+  --user oscar \
+  --intent "Implementing Phase D mutations" \
+  [--expiry-minutes 60]      # default: 60
+  [--lock-file /custom/path] # default: .ai-assistance/bridge/LOCK
+)
+# success: {"acquired":true,"lock_file":"...","expires":"2026-06-08T12:00:00Z"}
+# failure: {"acquired":false,"reason":"locked","held_by":"code/oscar","intent":"...","age_seconds":42}
+# stale lock (expired by mtime): auto-detected and overwritten
+
+# Release when done:
+rm .ai-assistance/bridge/LOCK
+```
+
+Uses temp-file + hard-link for atomicity (POSIX + NTFS). Falls back to bash `noclobber`
+if hard links unavailable. Always check `"acquired":true` before proceeding.
+
+**Hook notes (hard-won):**
+- Correct Claude Code hook event name is `SessionStart` (not `PostSessionStart`)
+- Use `bash script.sh` in hook commands — `source` is not available in hook context
+- Hook stdout is NOT injected into Code's context — Code never sees it as a message
+- Solution: write output to `bridge/STATUS`; Code reads that file when asked
+- Code is passive and will not act on hook output unprompted — ask "any pending tasks?"
+  at session start; Code reads STATUS and reports immediately
+
+```bash
+```
+
+### task-create.ts
+```bash
+npx ts-node .ai-assistance/scripts/task-create.ts \
+  --title "List open MRs" \
+  --request "Run: git branch --show-current in ecoportal-api-graphql, then list all open MRs via GitLab plugin" \
+  --expected "Current branch name + MR table (ID, title, source branch, author, date)" \
+  --from cowork \
+  --to code \
+  --user oscar
+# outputs: created oscar-[uuid]-list-open-mrs.md
+```
+
+### task-read.ts
+```bash
+# Read from inbox (default)
+npx ts-node .ai-assistance/scripts/task-read.ts --task oscar-a3f2b1c-list-open-mrs.md
+
+# Explicitly target outbox or archive
+npx ts-node .ai-assistance/scripts/task-read.ts --task oscar-a3f2b1c-list-open-mrs.md --dir outbox
+
+# Read by absolute path
+npx ts-node .ai-assistance/scripts/task-read.ts --file /abs/path/to/task.md
+
+# Output: structured JSON with title, status, created, from, to,
+#         context, request, expected, result, notes, raw_path
+# Uses this instead of reading raw Markdown — saves ~200 tokens per task read.
+```
+
+### task-complete.ts
+```bash
+npx ts-node .ai-assistance/scripts/task-complete.ts \
+  --task oscar-a3f2b1c-list-open-mrs.md \
+  --status done \
+  --result "Branch: feature/auth. MRs: ..." \
+  --notes "GitLab plugin authenticated successfully"
+# outputs: wrote outbox file, archived pair
+```
+
+### check-outbox.sh
+```bash
+bash .ai-assistance/scripts/check-outbox.sh oscar-a3f2b1c-list-open-mrs.md
+# outputs: DONE | "Branch: feature/auth. Open MRs: 3"
+# or:      PENDING | no response yet
+# or:      FAILED | "GitLab credentials not configured"
+```
+
+### bridge-status.sh
+```bash
+bash .ai-assistance/scripts/bridge-status.sh
+# outputs: pending:2 done:5 failed:0 archived:12 last_activity:2026-06-03T14:32Z
+```
+
+### capabilities-check.ts
+```bash
+npx ts-node .ai-assistance/scripts/capabilities-check.ts
+# checks connector endpoints, flags stale assumptions, updates assumptions-log.md
+# uses Haiku model for any inference (cheap, fast)
+```
+
+## Dependencies
+
+```bash
+# TypeScript scripts require:
+npm install -g ts-node typescript
+
+# Node type definitions (required for ts-node to resolve assert, process, etc.):
+npm install --save-dev @types/node
+
+# tsconfig.json must include "types": ["node"] in compilerOptions
+
+# capabilities-check.ts additionally requires:
+npm install @anthropic-ai/sdk
+```