ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/workflow-space.md

@@ -1,353 +0,0 @@
-# Workflow Space — Code Spec
-
-*Read this before working on `PagesWorkflow`, `Model::PagesWorkflow`, or `Input::WorkflowCommand`.*
-
----
-
-## Overview
-
-The Workflow Space covers two distinct subsystems that share the word "workflow":
-
-1. **The read model** (`PagesWorkflow`) — queried as `page.workflow` — describes the
-   automation configuration attached to a template or page (stages, fields, callbacks).
-2. **The command bus** (`executeWorkflowCommands`) — a single mutation that accepts an
-   array of `WorkflowCommandInput` objects to structurally modify a template or page
-   (add/rename stages, add fields, configure field options, set up callbacks, etc.).
-
-These are deeply related but separate code areas.
-
----
-
-## SCHEMA_VERSION
-
-All files in this area carry:
-
-```ruby
-SCHEMA_VERSION = '20260605'.freeze
-```
-
-This constant tracks the introspection snapshot used to derive the type list:
-`20260605T101224_live_ep_graphql_schema.graphql.json`.
-
-**When to update:** Re-run schema introspection and update this constant (across all
-affected files) when engineering reports schema changes to the Workflow Builder types.
-Use `grep -r SCHEMA_VERSION lib/` to find all files that need updating.
-Do not update the constant speculatively — only after verified re-introspection.
-
----
-
-## W1 — Read Model: PagesWorkflow
-
-### What it is
-
-`PagesWorkflow` is the workflow configuration embedded on every page (and template).
-It is available at `page.workflow` when the `PagesWorkflowFields` fragment is included
-in the query. It is NOT automatically included in `CommonPageUnion` — callers must
-request it explicitly.
-
-### Type hierarchy
-
-```
-PagesWorkflow
-  autoPageCreationEnabled: Boolean!
-  fields:  [RegisterField!]!       — field registry (key/name/type/total)
-  stages:  [Stage!]!               — stage list (id, name, ordering, state, active, started)
-  commands: PagesWorkflowCommandInterfaceConnection!  — paginated command log (deferred F.2)
-```
-
-**CallbackType** — attached to stages (requires `PagesWorkflowCallbackFields` fragment
-on Stage — see gap F.3):
-
-```
-PagesWorkflowCallbackType
-  id, triggerCondition: CallbackTriggerConditionEnum!
-  triggers:   [PagesWorkflowTriggerInterface!]!
-  operations: [PagesWorkflowOperationInterface!]!
-```
-
-**OperationInterface** — dispatches to three concrete types via `__typename`:
-
-```
-PagesWorkflowOperationInterface
-  id, timeDelayPassed: Boolean!, timeDelayConfig, delayedExecuteAt
-
-  PagesWorkflowOperationsAssignTo    — task assignment automation
-    targetTaskType, lastFulfilled, strategies, escalationLevels
-
-  PagesWorkflowOperationsCreatePage  — auto-create a page on trigger
-    templateId, crossReferenceFieldId
-
-  PagesWorkflowOperationsSendNotification  — notification dispatch
-    recurring, recurrenceActive, emailConfig, inSystemConfig, recipientConfig, ...
-```
-
-**TriggerInterface** — dispatches to one concrete type:
-
-```
-PagesWorkflowTriggerInterface
-  id
-
-  PagesWorkflowTriggersConditionalLogic  — field-value conditions
-    filters: [StoredEsFilter!]!
-```
-
-**CommandInterface** — the paginated command log (audit trail), dispatches to three:
-
-```
-PagesWorkflowCommandInterface
-  id, commandAction, createdAt, patchVer, ownerId, stageId, stageName, taskId
-
-  PagesWorkflowCommandChange        — structured diff changes
-    changes: [Change!]!
-  PagesWorkflowCommandChangeMessage — free-text change messages
-    changeMessages: [String!]!
-  PagesWorkflowCommandEsChange      — ES filter changes
-    changes: [StoredEsFilterChange!]!
-```
-
-### Ruby implementation
-
-| Layer | Class | File |
-|---|---|---|
-| Base model | `Base::PagesWorkflow` | `lib/ecoportal/api/graphql/base/pages_workflow.rb` |
-| Read model | `Model::PagesWorkflow` | `lib/ecoportal/api/graphql/model/pages_workflow.rb` |
-| Callback | `Base::PagesWorkflow::CallbackType` | `base/pages_workflow/callback_type.rb` |
-| Operation base | `Base::PagesWorkflow::OperationInterface` | `base/pages_workflow/operation_interface.rb` |
-| AssignTo | `Base::PagesWorkflow::Operations::AssignTo` | `base/pages_workflow/operations/assign_to.rb` |
-| CreatePage | `Base::PagesWorkflow::Operations::CreatePage` | `base/pages_workflow/operations/create_page.rb` |
-| SendNotification | `Base::PagesWorkflow::Operations::SendNotification` | `base/pages_workflow/operations/send_notification.rb` |
-| Trigger base | `Base::PagesWorkflow::TriggerInterface` | `base/pages_workflow/trigger_interface.rb` |
-| ConditionalLogic | `Base::PagesWorkflow::Triggers::ConditionalLogic` | `base/pages_workflow/triggers/conditional_logic.rb` |
-| Command base | `Base::PagesWorkflow::CommandInterface` | `base/pages_workflow/command_interface.rb` |
-| CommandChange | `Base::PagesWorkflow::CommandChange` | `base/pages_workflow/command_change.rb` |
-| CommandChangeMessage | `Base::PagesWorkflow::CommandChangeMessage` | `base/pages_workflow/command_change_message.rb` |
-| CommandEsChange | `Base::PagesWorkflow::CommandEsChange` | `base/pages_workflow/command_es_change.rb` |
-
-Supporting value objects: `RegisterField`, `TimeDelayConfig`, `EscalationLevel`,
-`EmailConfig`, `InSystemConfig`, `RecipientConfig`, `UserSelection`,
-`PeopleFieldSelection`, `TaskConfigSelection`, `ActionTypeSelection`,
-`MailboxFieldSelection`.
-
-### Fragments
-
-Three fragments are defined in `lib/ecoportal/api/graphql/fragment/pages_workflow.rb`:
-
-| Fragment constant | GraphQL fragment name | Purpose |
-|---|---|---|
-| `:PagesWorkflowFields` | `PagesWorkflowFields on PagesWorkflow` | Core read model (autoPageCreationEnabled, fields, stages) |
-| `:PagesWorkflowCallbackFields` | `PagesWorkflowCallbackFields on PagesWorkflowCallbackType` | Full callback with triggers + operations (all three operation types) |
-| `:PagesWorkflowCommandFields` | `PagesWorkflowCommandFields on PagesWorkflowCommandInterface` | Command log entries |
-
-### How to access workflow on a page
-
-The `workflow` field on `BasePageInterface` is mapped but NOT included in
-`CommonPageUnion`. You must query it explicitly with the `PagesWorkflowFields` fragment:
-
-```ruby
-page = graphql.currentOrganization.page(id: page_id) do
-  spread :PagesWorkflowFields   # adds workflow { autoPageCreationEnabled fields { ... } stages { ... } }
-  id
-  name
-  patchVer
-end
-
-page.workflow.auto_page_creation_enabled  # => Boolean
-page.workflow.stages                       # => Array of raw Stage hashes (id, name, ordering, state)
-page.workflow.fields                       # => Array of RegisterField instances
-```
-
-**Note:** `page.workflow.stages` returns raw stage data, not `Base::Page::Phased::Stage`
-instances. For full stage access (sections, components, tasks), use the normal page query
-with `CommonPageUnion`.
-
-### How to read callbacks (via stage)
-
-Stage-level callbacks require the `PagesWorkflowCallbackFields` fragment to be spread
-on the `Stage` type. This is not yet wired into the standard stage fragment — see F.3.
-
-When available:
-
-```ruby
-stage = page.stages['Risk Assessment']
-stage.workflow_callbacks.each do |cb|
-  puts cb.trigger_condition
-  cb.operations.each { |op| puts op.class.name }
-end
-```
-
----
-
-## W2-W5 — Write Model: Command Bus
-
-### What it is
-
-`executeWorkflowCommands` is the single mutation used for all structural changes to
-a template or page workflow. Rather than individual mutations per action, it accepts
-an ordered array of `WorkflowCommandInput` objects — each is a one-key hash dispatching
-to a typed sub-input.
-
-### Mutation signature
-
-```graphql
-mutation ExecuteWorkflowCommands($input: ExecuteWorkflowCommandsInput!) {
-  executeWorkflowCommands(input: $input) {
-    patchVer
-    item { autoPageCreationEnabled fields { ... } stages { ... } }
-    errors { details fullMessages }
-  }
-}
-```
-
-`ExecuteWorkflowCommandsInput`:
-- `id: ID!` — the page or template ID
-- `patchVer: Int!` — optimistic concurrency lock (required, not optional)
-- `commands: [WorkflowCommandInput!]!` — the command array
-
-### Ruby classes
-
-| Class | File | Purpose |
-|---|---|---|
-| `Mutation::Page::ExecuteWorkflowCommands` | `mutation/page/execute_workflow_commands.rb` | Executes the mutation |
-| `Payload::ExecuteWorkflowCommands` | `payload/execute_workflow_commands.rb` | Wraps response: `patchVer`, `item` (PagesWorkflow), `success?`, `error?`, `body` |
-| `Input::WorkflowCommand` | `input/workflow_command.rb` | Dispatcher: `COMMAND_MAP` + `.build(key, **kwargs)` |
-| `Input::WorkflowCommand::*` | `input/workflow_command/*.rb` | ~83 sub-input modules (one per command key) |
-| `Connection::PagesWorkflowCommand` | `connection/pages_workflow_command.rb` | Paginated command log connection |
-
-### Input::WorkflowCommand — dispatcher
-
-`Input::WorkflowCommand` is a pure factory — no instances, only class methods:
-
-```ruby
-# Build a single command hash
-cmd = Input::WorkflowCommand.build(:editPage, name: 'New Title')
-# => { editPage: { name: 'New Title' } }
-
-# Build multiple commands
-cmds = [
-  Input::WorkflowCommand.build(:editPage, name: 'New Title', icon: 'star'),
-  Input::WorkflowCommand.build(:editStage, stageId: 's1', name: 'Phase 1'),
-]
-
-# Execute all commands in one mutation call
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  cmds
-)
-
-raise "Workflow command failed: #{payload.body}" unless payload.success?
-new_patch_ver = payload.patchVer
-```
-
-**Important:** `patchVer` is required and non-optional on `ExecuteWorkflowCommandsInput`.
-Always fetch the current page before calling this mutation.
-
-### `Builder::Page` integration
-
-The low-level mutation class `Mutation::Page::ExecuteWorkflowCommands` exists and is
-functional. `Builder::Page#execute_workflow_commands` is a **deferred item** (see F.4)
-— the convenience wrapper on `Builder::Page` is not yet present.
-
-Until it is wired, call the mutation directly:
-
-```ruby
-payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
-  id:        page_id,
-  patch_ver: page.patchVer,
-  commands:  cmds
-)
-```
-
-### Template mutations
-
-Template structural mutations use the same `executeWorkflowCommands` mutation and the
-same `WorkflowCommandInput` command bus. Engineering has confirmed the back-end is ready.
-
-Template mutations are guarded by an `allow_template_mutations` flag (planned for
-`Builder::Page` — see F.4). Until that guard is implemented, take care when targeting
-template IDs — structural changes to templates affect all pages created from them.
-
-### Payload
-
-`Payload::ExecuteWorkflowCommands` provides:
-
-```ruby
-payload.success?    # => Boolean — true if no errors
-payload.error?      # => Boolean — true if errors array is non-empty
-payload.body        # => raw errors array (for logging)
-payload.patchVer    # => Integer — updated patchVer after commands applied
-payload.item        # => Model::PagesWorkflow — read back the updated workflow state
-```
-
----
-
-## Concerns::Deprecation — warn_once Pattern
-
-`Concerns::Deprecation` provides a process-level warning deduplicator used in this
-and other areas of the gem:
-
-```ruby
-Concerns::Deprecation.warn_once(:some_key, 'This method is deprecated — use X instead.')
-# Prints once to stderr; subsequent calls with the same key are silenced.
-```
-
-The `SCHEMA_VERSION` constant on `Concerns::Deprecation` tracks the same introspection
-snapshot as the workflow command classes.
-
----
-
-## Gap Table — PageInput vs WorkflowCommand
-
-These fields are NOT settable via `UpdatePageInput → page: PageInput` but ARE settable
-via `WorkflowCommand.build(:editPage, ...)`:
-
-| Goal | NOT in PageInput | Use instead |
-|------|------------------|-------------|
-| Change page icon | | `editPage: { icon: 'star' }` |
-| Change theme | | `editPage: { themeId: 'THEME_ID' }` |
-| Enable/disable counter | | `editPage: { counterEnabled: true, counterPrefix: 'REC-' }` |
-| Set counter value | | `editPage: { counter: 42 }` |
-| Show/hide creator field | | `editPage: { showCreator: true }` |
-| Toggle comments | | `editPage: { disableComments: false }` |
-| Enable dashboard import | | `editPage: { enableDashboardImport: true }` |
-| Mobile layout settings | | `editPage: { mobileEnabled: true, useSectionsOnMobile: true }` |
-| Restricted stage display | | `editPage: { showStrategyForRestrictedStages: true }` |
-| Manage folder membership | | `editPage: { addFolders: ['F1'], removeFolders: ['F2'] }` |
-
----
-
-## Gap Table — DataFieldInput vs WorkflowCommand
-
-These field configuration properties are NOT settable via `DataFieldInput` (the per-field
-value update in `updatePage`) but ARE settable via
-`WorkflowCommand.build(:editFieldConfiguration, ...)`:
-
-| Goal | NOT in DataFieldInput | Use instead |
-|------|----------------------|-------------|
-| Rename a field label | | `editFieldConfiguration: { dataFieldId: 'F', label: 'New Name' }` |
-| Set field tooltip/description | | `editFieldConfiguration: { dataFieldId: 'F', tooltip: '...', description: '...' }` |
-| Hide field in view | | `editFieldConfiguration: { dataFieldId: 'F', hideView: true }` |
-| Configure people field type | | `editFieldConfiguration: { dataFieldId: 'F', byType: { people: { singular: true, personSchemaId: 'S' } } }` |
-| Configure select options | | `addSelectFieldOption`, `editSelectFieldOption`, `removeSelectFieldOption` commands |
-| Configure gauge stops | | `addGaugeFieldStop`, `editGaugeFieldStop`, `removeGaugeFieldStop` commands |
-| Configure cross-reference | | `editFieldConfiguration: { dataFieldId: 'F', byType: { crossReference: { registerId: 'R', singleSelectMode: true } } }` |
-| Configure date (show time) | | `editFieldConfiguration: { dataFieldId: 'F', byType: { date: { showTime: true } } }` |
-| Configure image gallery layout | | `editFieldConfiguration: { dataFieldId: 'F', byType: { imageGallery: { layout: 'GRID' } } }` |
-| Set linked field config | | `addLinkedFieldConfig: { dataFieldId: 'F', sourceFieldKey: 'key', crossReferenceId: 'CR' }` |
-
----
-
-## Related Files
-
-```
-lib/ecoportal/api/graphql/base/pages_workflow.rb          ← Base model root
-lib/ecoportal/api/graphql/model/pages_workflow.rb         ← Model with class_resolver wiring
-lib/ecoportal/api/graphql/input/workflow_command.rb       ← Dispatcher + COMMAND_MAP
-lib/ecoportal/api/graphql/input/workflow_command/         ← ~83 sub-input modules
-lib/ecoportal/api/graphql/mutation/page/execute_workflow_commands.rb
-lib/ecoportal/api/graphql/payload/execute_workflow_commands.rb
-lib/ecoportal/api/graphql/fragment/pages_workflow.rb      ← 3 fragments
-lib/ecoportal/api/graphql/concerns/deprecation.rb         ← warn_once
-.ai-assistance/code/workflow-command-guide.md             ← porting guide with full command table
-.ai-assistance/projects/workflow-space/TODO.md            ← W1-W5 phase tracking
-```

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

@@ -1,30 +0,0 @@
-# Conventions — AI Instruction Files
-
-## Rule: every subfolder that contains AI-readable instructions must have its own CLAUDE.md
-
-The root `.ai-assistance/CLAUDE.md` is the entry point only. It does not duplicate rules — it
-references subfolders. Each subfolder owns its own rules.
-
-## Subfolder registry
-
-| Folder | CLAUDE.md purpose |
-|--------|-------------------|
-| `.ai-assistance/` | Startup sequence, env detection, delegation rule |
-| `.ai-assistance/bridge/` | Bridge protocol: file format, task lifecycle, who processes what |
-| `.ai-assistance/capabilities/` | How to read/update capability and connector files |
-| `.ai-assistance/conventions/` | This file — rules for instruction file structure |
-| `.ai-assistance/scripts/` | Index of scripts, when to call each, expected I/O |
-
-## Rules for adding new subfolders
-
-1. Create the folder
-2. Add a `CLAUDE.md` describing its purpose and any rules specific to it
-3. Register it in this file (the table above)
-4. Reference it from the root `.ai-assistance/CLAUDE.md` if startup behaviour is needed
-
-## Rules for CLAUDE.md files
-
-- Be explicit, not implicit — assume the reading agent has no prior context
-- No cross-referencing rules from memory — link to the file
-- Keep each CLAUDE.md focused on its folder only
-- Date-stamp any assumptions so the capabilities-check agent can identify stale content

data/.ai-assistance/conventions/code-working-tree-protocol.md

@@ -1,199 +0,0 @@
-# Code Working Tree Protocol
-
-When Claude Code needs to make changes to files **outside** `bridge/inbox/`, it must
-follow this protocol. This prevents Code's changes from mixing with in-progress CoWork
-edits and ensures a clean, traceable commit history.
-
----
-
-## When this applies
-
-Any time Code intends to modify files in the working tree that are not bridge task files
-(i.e., not `.ai-assistance/bridge/inbox/` or `.ai-assistance/bridge/outbox/`).
-
-This includes: editing source files, updating documentation, changing scripts,
-modifying capabilities files, etc.
-
----
-
-## Protocol
-
-### 0. Check for a lock
-
-```bash
-cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
-```
-
-- **No lock:** proceed to step 1
-- **Lock exists, EXPIRES is in the future:** stop. Tell the user:
-  > "Working tree is locked by [AGENT] ([USER]) since [ACQUIRED], working on: [INTENT].
-  > Expires at [EXPIRES]. Please wait or check if the other session is still active."
-- **Lock exists, EXPIRES is in the past:** stale lock — safe to overwrite, proceed to step 1
-
----
-
-### 1. Acquire the lock
-
-Write `.ai-assistance/bridge/LOCK` with full watermark:
-
-```
-AGENT: code
-USER: [git config user.name, lowercased]
-ACQUIRED: [ISO 8601 now]
-EXPIRES: [ISO 8601 now + 30 minutes]
-INTENT: [one sentence — what you are about to change and why]
-FILES: [comma-separated list of files you plan to modify]
-```
-
-Example:
-```
-AGENT: code
-USER: oscar
-ACQUIRED: 2026-06-04T10:00:00Z
-EXPIRES: 2026-06-04T10:30:00Z
-INTENT: Update gitlab-mcp.md with new PAT scopes and rotation info
-FILES: .ai-assistance/integrations/gitlab-mcp.md
-```
-
----
-
-### 2. Check for unstaged changes that overlap with your planned files
-
-```bash
-git status --short
-```
-
-If the working tree is clean, skip to step 3.
-
-If there are unstaged/staged changes, compare them against the files listed in your LOCK:
-
-```bash
-git diff --name-only HEAD
-git diff --cached --name-only
-```
-
-- **No overlap with your FILES:** proceed — the changes are unrelated and won't pollute history
-- **Overlap with one or more of your FILES:** commit the unstaged changes first.
-  Derive the commit message by running `git diff HEAD` on the overlapping files and
-  writing a short imperative summary of what actually changed — do not use a generic
-  message. Format: `wip: <what changed, e.g. "rename .claude to .ai-assistance across scripts">`
-
-```bash
-git add -A
-git commit -m "wip: <derived from actual diff>"
-```
-
-This keeps Code's subsequent commit clean and ensures both sets of changes build
-on the correct base. On a feature branch, `wip:` commits are fine — squash before MR.
-
----
-
-### 3. Apply your changes
-
-Make the intended file edits. Stay within the scope declared in INTENT and FILES
-when you acquired the lock. If scope expands, update the LOCK file before proceeding.
-
----
-
-### 4. Commit your changes
-
-```bash
-git add -A
-git commit -m "[descriptive message — what Code changed and why]"
-```
-
-Commit message should be specific enough that a teammate can understand the change
-without reading the diff. Example:
-```
-docs: update gitlab-mcp.md scopes and rotation info for new PAT (April 2027 expiry)
-```
-
-**Commit authorship — developer only by default:**
-
-Commits are authored by the developer alone (git's `user.name` / `user.email` config).
-Do NOT add `Co-Authored-By: Claude ...` to commit messages unless the developer
-explicitly requests it.
-
-Rationale: the commit history is the developer's professional record. Co-authorship is
-opt-in, not opt-out. If the developer wants to attribute AI involvement, they can add
-it themselves or ask Claude to include it for a specific commit.
-
-Before adding any co-authorship attribution, ask:
-> "Would you like to add AI co-authorship to this commit, or keep it as your commit alone?"
-
-Default answer if not asked: **developer only**.
-
----
-
-### 5. Release the lock
-
-```bash
-rm .ai-assistance/bridge/LOCK
-```
-
----
-
-## External-fork branch protocol
-
-When the task involves a **fork of an external gem** (not team-managed), an extra check
-applies **before step 1** above:
-
-1. Look up the gem in `.ai-assistance/code/dependencies.md`.
-2. Read the `Git workflow` row. If it says **"ALWAYS use a feature branch"** or
-   **"upstream-contribution only"**, you MUST:
-   - Create a dedicated feature/fix branch (e.g. `feature/<description>`) — NEVER commit to `master`.
-   - If the branch name was not specified by the developer, derive one from the work and
-     **tell the developer what branch you created** before committing anything.
-3. If the `Git workflow` row is absent or ambiguous, **ask the developer** which branch
-   to use before proceeding. Do not guess.
-
-This rule applies even inside background agents — the branch strategy must be resolved
-in the prompt given to the agent, not inferred at runtime.
-
-**Why:** Commits on `master` of an external fork pollute the base from which upstream
-PRs are diffed. A feature branch produces a clean, reviewable diff against upstream's
-`master`.
-
----
-
-## Quick reference
-
-```bash
-# 0. Check lock
-cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
-
-# 1. Acquire lock
-cat > .ai-assistance/bridge/LOCK << EOF
-AGENT: code
-USER: oscar
-ACQUIRED: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
-EXPIRES: $(date -u -d "+30 minutes" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -v+30M +"%Y-%m-%dT%H:%M:%SZ")
-INTENT: <what you are changing>
-FILES: <files>
-EOF
-
-# 2. Check for overlapping unstaged changes
-git diff --name-only HEAD && git diff --cached --name-only
-# If any of those files overlap with your planned FILES → commit them first:
-git add -A && git commit -m "wip: <description of CoWork's in-progress work>"
-# If no overlap → skip, proceed directly
-
-# 3. Apply changes
-# ... make edits ...
-
-# 4. Commit your changes
-git add -A && git commit -m "<descriptive message>"
-
-# 5. Release lock
-rm .ai-assistance/bridge/LOCK
-```
-
----
-
-## Notes
-
-- If Code crashes mid-protocol, the LOCK will expire naturally (30 min timeout)
-- The `wip:` commit prefix signals to teammates that this was an auto-committed
-  in-progress state — safe to squash or amend later
-- This protocol does not apply to bridge task processing (reading inbox, writing outbox)
-  — those are read/write of bridge files only and don't touch the working tree

data/.ai-assistance/conventions/gitignore-rules.md

@@ -1,42 +0,0 @@
-# .gitignore Rules for .ai-assistance/
-
-## What stays local (never commit)
-
-| Pattern | Reason |
-|---------|--------|
-| `bridge/inbox/*.draft.md` | Work-in-progress tasks not ready to share |
-| `bridge/inbox/*.local.md` | Tasks intended only for local Code session |
-| `bridge/LOCK` | Working tree lock — local only, never committed |
-| `capabilities/.env` | Any credential or token file |
-| `scripts/*.env` | Script-level secrets |
-| `scripts/node_modules/` | Dependencies, not source |
-
-## What gets committed
-
-Everything else under `.ai-assistance/` is committed. This includes:
-
-- All `CLAUDE.md` files
-- `bridge/inbox/[username]-[uuid]-[slug].md` — pushed tasks are intentionally shared
-- `bridge/outbox/` — completed results are shared
-- `bridge/archive/` — history is useful, keep it
-- `capabilities/*.md` — shared knowledge
-- `conventions/*.md` — shared rules
-- `scripts/*.sh`, `scripts/*.ts` — shared tooling
-
-## Why archive/ is committed
-
-Completed task pairs in `archive/` are the audit trail of AI-assisted work.
-They answer: what did we ask, what did we get back, when. Keep them.
-Prune manually if the folder grows unwieldy.
-
-## Gitignore entries (copy these to your project root .gitignore)
-
-```
-# AI assistance — local-only files
-.ai-assistance/bridge/inbox/*.draft.md
-.ai-assistance/bridge/inbox/*.local.md
-.ai-assistance/bridge/LOCK
-.ai-assistance/capabilities/.env
-.ai-assistance/scripts/*.env
-.ai-assistance/scripts/node_modules/
-```