eco-helpers 3.2.16 → 3.2.22

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/sync_readiness.rb

@@ -0,0 +1,178 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Sync-readiness monitoring.
+    #
+    # Given a register subset (its entries) and the register's ACTIVE template, report which entries
+    # CAN sync vs which cannot — where "can sync" means: every field the template marks REQUIRED is
+    # present on the entry with a non-empty value AND typed correctly (the entry field's type matches
+    # the template field's type). This is the pre-flight an integration runs before pushing entries
+    # downstream, and the drift-detection the customer-facing integrations mandate needs.
+    #
+    # Operates on raw docs (template doc + entry docs) so it is session-less and offline-runnable:
+    #   * template doc: the JSON the gem returns for a template (stages/sections/dataFields).
+    #   * entry docs:   each register entry as { 'id' =>, 'fields' => [ {id/label/type/value}, ... ] }
+    #     (or anything exposing the same shape). A field is matched to a template field by id first,
+    #     then by label — mirroring how the pairing engine falls back.
+    #
+    #   monitor = SyncReadiness.new(template_doc: tpl, entries: [e1, e2, ...])
+    #   monitor.ready         # => [EntryReadiness(ready: true), ...]
+    #   monitor.not_ready     # => [EntryReadiness(ready: false, ...), ...]
+    #   monitor.summary       # => { total:, ready:, not_ready: }
+    #   monitor.report        # => human summary
+    class SyncReadiness
+      # Per-entry readiness verdict.
+      EntryReadiness = Struct.new(:entry_id, :ready, :missing_required, :type_mismatches,
+                                  keyword_init: true) do
+        def ready?
+          ready ? true : false
+        end
+
+        def reasons
+          out = Array(missing_required).map { |m| "missing required '#{m}'" }
+          Array(type_mismatches).each do |m|
+            out << "type mismatch '#{m[:label]}' (want #{m[:expected]}, got #{m[:actual]})"
+          end
+          out
+        end
+
+        def to_h
+          { entry_id: entry_id, ready: ready?, missing_required: Array(missing_required),
+            type_mismatches: Array(type_mismatches) }
+        end
+      end
+
+      attr_reader :entries
+
+      # @param template_doc [Hash] the active template doc.
+      # @param entries [Array<Hash,#id>] register entry docs to assess.
+      def initialize(template_doc:, entries:)
+        @template_doc = template_doc || {}
+        @entries      = Array(entries)
+      end
+
+      def verdicts
+        @verdicts ||= @entries.map { |entry| assess(entry) }
+      end
+
+      def ready
+        verdicts.select(&:ready?)
+      end
+
+      def not_ready
+        verdicts.reject(&:ready?)
+      end
+
+      def summary
+        { total: verdicts.size, ready: ready.size, not_ready: not_ready.size }
+      end
+
+      def to_h
+        { summary: summary, entries: verdicts.map(&:to_h) }
+      end
+
+      def report
+        lines = ["SYNC READINESS: #{summary[:ready]}/#{summary[:total]} entries ready"]
+        not_ready.each do |v|
+          lines << "  * entry #{v.entry_id}: NOT READY"
+          v.reasons.each { |r| lines << "      - #{r}" }
+        end
+        lines.join("\n")
+      end
+
+      private
+
+      # The template fields, indexed by id and by (downcased) label, carrying type + required.
+      def template_fields
+        @template_fields ||= begin
+          out = { by_id: {}, by_label: {} }
+          each_template_field do |f|
+            spec = { id: f['id'], label: f['label'], type: field_type(f), required: !!f['required'] }
+            out[:by_id][f['id']] = spec if f['id']
+            out[:by_label][label_key(f['label'])] = spec if f['label']
+          end
+          out
+        end
+      end
+
+      def required_fields
+        @required_fields ||= template_fields[:by_id].values.select { |s| s[:required] }.
+          +(template_fields[:by_label].values.select { |s| s[:required] }).
+          uniq { |s| s[:id] || s[:label] }
+      end
+
+      def assess(entry)
+        entry_fields = index_entry_fields(entry)
+        missing      = []
+        mismatches   = []
+
+        required_fields.each do |spec|
+          efield = entry_fields[:by_id][spec[:id]] || entry_fields[:by_label][label_key(spec[:label])]
+          if efield.nil? || value_empty?(efield[:value])
+            missing << spec[:label]
+          elsif spec[:type] && efield[:type] && spec[:type] != efield[:type]
+            mismatches << { label: spec[:label], expected: spec[:type], actual: efield[:type] }
+          end
+        end
+
+        EntryReadiness.new(
+          entry_id:         entry_id(entry),
+          ready:            missing.empty? && mismatches.empty?,
+          missing_required: missing,
+          type_mismatches:  mismatches
+        )
+      end
+
+      def index_entry_fields(entry)
+        out = { by_id: {}, by_label: {} }
+        entry_field_docs(entry).each do |f|
+          spec = { id: f['id'] || f[:id], label: f['label'] || f[:label],
+                   type: field_type(f), value: f['value'] || f[:value] }
+          out[:by_id][spec[:id]]                    = spec if spec[:id]
+          out[:by_label][label_key(spec[:label])]   = spec if spec[:label]
+        end
+        out
+      end
+
+      def entry_field_docs(entry)
+        return Array(entry['fields'] || entry[:fields]) if entry.is_a?(Hash)
+        return entry.components.to_a if entry.respond_to?(:components)
+
+        []
+      end
+
+      def entry_id(entry)
+        return entry['id'] || entry[:id] if entry.is_a?(Hash)
+
+        entry.respond_to?(:id) ? entry.id : nil
+      end
+
+      def each_template_field(&block)
+        Array(@template_doc['stages']).each do |st|
+          Array(st['sections']).each do |sec|
+            fields_of(sec).each(&block)
+          end
+        end
+      end
+
+      def fields_of(section)
+        Array(section['dataFields']) + Array(section['leftDataFields']) + Array(section['rightDataFields'])
+      end
+
+      def field_type(field)
+        field['__typename'] || field['type'] || field[:type]
+      end
+
+      def label_key(label)
+        label.to_s.strip.downcase
+      end
+
+      def value_empty?(value)
+        return true if value.nil?
+        return value.strip.empty? if value.is_a?(String)
+        return value.empty? if value.respond_to?(:empty?)
+
+        false
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/verifier.rb

@@ -0,0 +1,141 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Pluggable post-deploy verification interface.
+    #
+    # The deploy loop wants to run the freshly-deployed template through a check framework (ideally the
+    # `ecoportal-qa` gem's check runner). But `ecoportal-qa` is NOT a hard dependency of eco-helpers,
+    # so we do not `require` it here. Instead the loop calls a small `Verifier` interface; a concrete
+    # verifier is injected. When `ecoportal-qa` IS on the load path, `QaVerifier` wires it in; when it
+    # isn't, `NullVerifier` (always-pass, records that qa was unavailable) keeps the loop runnable
+    # offline.
+    #
+    # A verifier receives the post-deploy template doc and returns a `Verdict`.
+    #
+    #   verdict = Verifier.default.verify(post_deploy_doc)
+    #   verdict.pass?      # => true/false
+    #   verdict.findings   # => [ {severity:, message:}, ... ]
+    class Verifier
+      # A verification verdict. `pass?` is the gate; `findings` carries per-check detail.
+      Verdict = Struct.new(:pass, :findings, :verifier, keyword_init: true) do
+        def pass?
+          pass ? true : false
+        end
+
+        def failures
+          Array(findings).select { |f| %i[error fail].include?((f[:severity] || f['severity'])&.to_sym) }
+        end
+
+        def to_h
+          { pass: pass?, verifier: verifier, findings: Array(findings) }
+        end
+
+        def report
+          head = "VERIFY (#{verifier}): #{pass? ? 'PASS' : 'FAIL'}"
+          return head if Array(findings).empty?
+
+          ([head] + Array(findings).map do |f|
+            "  - [#{f[:severity] || f['severity']}] #{f[:message] || f['message']}"
+          end).join("\n")
+        end
+      end
+
+      # The verifier the loop uses when none is injected: qa if available, else the null verifier.
+      def self.default
+        qa_available? ? QaVerifier.new : NullVerifier.new
+      end
+
+      # Is the ecoportal-qa check framework loadable?
+      def self.qa_available?
+        return @qa_available unless @qa_available.nil?
+
+        @qa_available = begin
+          require 'ecoportal/qa'
+          defined?(::Ecoportal::QA) ? true : false
+        rescue LoadError
+          false
+        end
+      end
+
+      # Reset the memoised availability probe (used by specs that stub the load path).
+      def self.reset_qa_probe!
+        @qa_available = nil
+      end
+
+      # Subclass / duck-type contract: return a Verdict for the given template doc.
+      def verify(_template_doc)
+        raise NotImplementedError, "#{self.class} must implement #verify(template_doc)"
+      end
+
+      # Always-pass verifier used when no real check framework is wired in. It is honest about it:
+      # the verdict records that qa was unavailable so a report never falsely claims "qa verified".
+      class NullVerifier < Verifier
+        def verify(_template_doc)
+          Verdict.new(
+            pass:     true,
+            verifier: 'null',
+            findings: [{ severity: :info, message: 'ecoportal-qa not available; no checks run' }]
+          )
+        end
+      end
+
+      # Adapter onto the ecoportal-qa check runner. Kept dependency-free at load time — it only touches
+      # `Ecoportal::QA` inside #verify, so requiring this file never forces the qa gem. The exact qa
+      # runner API is intentionally accessed through a single seam (`run_qa`) so it is easy to correct
+      # once the qa public surface stabilises (see TODO).
+      #
+      # TODO(qa-integration): the qa check-runner public API is still moving (see the qa repo's
+      # PHASE3-SCOPE.md). This adapter assumes a `check_set.run(doc)`-style entry returning objects
+      # responding to `#pass?` and `#findings`. Confirm and adjust `run_qa` when qa is pinned as a dep.
+      class QaVerifier < Verifier
+        def initialize(check_set: nil)
+          super()
+          @check_set = check_set
+        end
+
+        def verify(template_doc)
+          result = run_qa(template_doc)
+          Verdict.new(pass: result_pass?(result), verifier: 'ecoportal-qa', findings: result_findings(result))
+        rescue StandardError => e
+          Verdict.new(pass: false, verifier: 'ecoportal-qa',
+                      findings: [{ severity: :error, message: "qa verification raised: #{e.message}" }])
+        end
+
+        private
+
+        # SINGLE integration seam — the one place that knows the qa runner shape.
+        def run_qa(template_doc)
+          set = @check_set || default_check_set
+          set.run(template_doc)
+        end
+
+        def default_check_set
+          raise NotImplementedError, 'no qa check_set injected and no default wired' unless defined?(::Ecoportal::QA)
+
+          # Placeholder: the concrete constructor is confirmed once qa is a pinned dependency.
+          if ::Ecoportal::QA.respond_to?(:default_check_set)
+            ::Ecoportal::QA.default_check_set
+          else
+            (raise NotImplementedError,
+                   'qa default check set not available')
+          end
+        end
+
+        def result_pass?(result)
+          return result.pass? if result.respond_to?(:pass?)
+
+          Array(result).all? { |r| r.respond_to?(:pass?) ? r.pass? : true }
+        end
+
+        def result_findings(result)
+          source = result.respond_to?(:findings) ? result.findings : result
+          Array(source).map do |f|
+            next f if f.is_a?(Hash)
+
+            { severity: (f.respond_to?(:severity) ? f.severity : :info),
+              message:  (f.respond_to?(:message) ? f.message : f.to_s) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy.rb

@@ -0,0 +1,21 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  # Phase 5: deploy → verify → monitor loop for template (workflow) changes.
+  #
+  # Consumes a gem `Ecoportal::API::GraphQL::Diff::Deploy` command batch (from
+  # `Diff::Deploy.from_versions(...)`), dry-run applies it (live behind an explicit `commit:` flag),
+  # confirms the applied delta matches the intended delta via a pre/post self-version diff
+  # (`Diff::VersionDiff`), verifies the result through a pluggable `Verifier` (ecoportal-qa when
+  # present), and reports register sync-readiness against the deployed template.
+  #
+  # All components are session-less and offline-runnable against fixtures — the live seams (apply /
+  # re-read) are injected. See each file's header. Dry-run is the DEFAULT.
+  module Deploy
+  end
+end
+
+require_relative 'deploy/applier'
+require_relative 'deploy/recording_executor'
+require_relative 'deploy/drift_report'
+require_relative 'deploy/verifier'
+require_relative 'deploy/sync_readiness'
+require_relative 'deploy/loop'

data/lib/eco/api/usecases/graphql/samples/pages/template.rb

@@ -0,0 +1,11 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Template (workflow) build-from-scratch + (later) diff-and-update samples.
+  # See ecoportal-api-graphql/.ai-assistance/projects/template-maintenance/.
+  module Template
+  end
+end
+
+require_relative 'template/command_emitter'
+require_relative 'template/base'
+require_relative 'template/csv_build'
+require_relative 'template/deploy'

data/lib/eco/api/usecases/graphql/samples/pages.rb

@@ -4,4 +4,6 @@ module Eco::API::UseCases::GraphQL::Samples
 end
 
 require_relative 'pages/page'
+require_relative 'pages/register'
 require_relative 'pages/org_page'
+require_relative 'pages/template'

data/lib/eco/api/usecases/ooze_samples/register_update_case.rb

@@ -54,7 +54,10 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
     return unless (pending = queue_shift(ooze_id))
 
     update_ooze(pending).tap do |result|
-      if result.is_a?(Ecoportal::API::Common::Response)
+      # Duck-type, not is_a?: the GraphQL Compat::Response responds to success?/status but is
+      # NOT an Ecoportal::API::Common::Response, so is_a? silently skipped every GraphQL update
+      # (updated/failed stuck at 0). false/nil returns (dry-run / no-op) still fall through.
+      if result.respond_to?(:success?)
         if result.success?
           @updated_oozes += 1
         else
@@ -188,7 +191,8 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
   def update_oozes(batched_oozes = batch_queue)
     batched_oozes.each do |ooze|
       update_ooze(ooze).tap do |result|
-        if result.is_a?(Ecoportal::API::Common::Response)
+        # Duck-type, not is_a? — see #before_loading_new_target (GraphQL Compat::Response).
+        if result.respond_to?(:success?)
           if result.success?
             @updated_oozes += 1
           else

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.2.16'.freeze
+  VERSION = '3.2.22'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.2.16
+  version: 3.2.22
 platform: ruby
 authors:
 - Oscar Segura
@@ -262,7 +262,7 @@ dependencies:
         version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.9
+        version: 1.3.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -272,7 +272,7 @@ dependencies:
         version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.9
+        version: 1.3.14
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-v2
   requirement: !ruby/object:Gem::Requirement
@@ -282,7 +282,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.1
+        version: 3.3.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -292,7 +292,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.1
+        version: 3.3.3
 - !ruby/object:Gem::Dependency
   name: ed25519
   requirement: !ruby/object:Gem::Requirement
@@ -541,29 +541,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".ai-assistance/conventions/code-working-tree-protocol.md"
-- ".ai-assistance/scripts/token-logger.js"
-- ".ai-assistance/scripts/token-report.ts"
-- ".ai-assistance/scripts/token-session-start.js"
-- ".ai-assistance/skills/ep-ai-manager/SKILL.md"
-- ".ai-assistance/skills/ruby-scripting/SKILL.md"
-- ".ai-assistance/standards-version.json"
-- ".ai-assistance/token-budget.json"
-- ".claude/settings.json"
-- ".gitignore"
-- ".idea/.gitignore"
-- ".markdownlint.json"
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
-- ".yardopts"
 - CHANGELOG.md
-- CLAUDE.md
-- Gemfile
 - LICENSE
 - README.md
-- Rakefile
-- eco-helpers.gemspec
 - lib/eco-helpers.rb
 - lib/eco/api.rb
 - lib/eco/api/common.rb
@@ -844,6 +824,9 @@ files:
 - lib/eco/api/usecases/graphql/compat/ooze_redirect/dirty_array.rb
 - lib/eco/api/usecases/graphql/compat/ooze_redirect/field_patches.rb
 - lib/eco/api/usecases/graphql/compat/ooze_redirect/force_compat.rb
+- lib/eco/api/usecases/graphql/compat/parity/comparison.rb
+- lib/eco/api/usecases/graphql/compat/parity/harness.rb
+- lib/eco/api/usecases/graphql/compat/parity/run_result.rb
 - lib/eco/api/usecases/graphql/helpers.rb
 - lib/eco/api/usecases/graphql/helpers/CLAUDE.md
 - lib/eco/api/usecases/graphql/helpers/base.rb
@@ -877,6 +860,14 @@ files:
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap.rb
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_map.rb
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_set.rb
+- lib/eco/api/usecases/graphql/helpers/pages.rb
+- lib/eco/api/usecases/graphql/helpers/pages/copying.rb
+- lib/eco/api/usecases/graphql/helpers/pages/creatable.rb
+- lib/eco/api/usecases/graphql/helpers/pages/filters.rb
+- lib/eco/api/usecases/graphql/helpers/pages/ooze_handlers.rb
+- lib/eco/api/usecases/graphql/helpers/pages/rescuable.rb
+- lib/eco/api/usecases/graphql/helpers/pages/shortcuts.rb
+- lib/eco/api/usecases/graphql/helpers/pages/typed_fields_pairing.rb
 - lib/eco/api/usecases/graphql/samples.rb
 - lib/eco/api/usecases/graphql/samples/CLAUDE.md
 - lib/eco/api/usecases/graphql/samples/contractors.rb
@@ -913,6 +904,24 @@ files:
 - lib/eco/api/usecases/graphql/samples/pages/page.rb
 - lib/eco/api/usecases/graphql/samples/pages/page/base.rb
 - lib/eco/api/usecases/graphql/samples/pages/page/dsl.rb
+- lib/eco/api/usecases/graphql/samples/pages/register.rb
+- lib/eco/api/usecases/graphql/samples/pages/register/base.rb
+- lib/eco/api/usecases/graphql/samples/pages/register/migration_case.rb
+- lib/eco/api/usecases/graphql/samples/pages/register/target_oozes_update_case.rb
+- lib/eco/api/usecases/graphql/samples/pages/template.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/base.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/command_emitter.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build/builder.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build/format_map.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/csv_build/parser.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/applier.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/drift_report.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/loop.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/recording_executor.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/sync_readiness.rb
+- lib/eco/api/usecases/graphql/samples/pages/template/deploy/verifier.rb
 - lib/eco/api/usecases/graphql/utils.rb
 - lib/eco/api/usecases/graphql/utils/sftp.rb
 - lib/eco/api/usecases/lib.rb

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

@@ -1,176 +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
-```
-
----
-
-## 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