Workspace Verification Protocol¶

The Fundamental Rule¶

Verification Mode is read-only.

Until the Verification Receipt is complete, the agent may not modify source code.

What Went Wrong (Session 2026-07-01)¶

The agent lost the distinction between verification and repair the moment drush cr hit an error. Instead of stopping and producing a receipt, it switched into repair mode while still operating on an incorrect mental model of the filesystem. Every subsequent "fix" compounded the error:

Commented out YAML service aliases
Renamed PHP properties across 21+ files
Renamed module integration files
Patched config/install YAML in the wrong location
Removed interface declarations and typed properties

None of those belong in a verification run.

The Workspace Contract¶

Before any Drupal verification command runs, confirm the workspace contract:

WORKSPACE CONTRACT
──────────────────────────────────────────────────
Host Module Root
  <workspace>/PROJECTS/__DRUPAL/Module
  STATUS: [ ] exists [ ] readable

DDEV Mount
  docker-compose.mounts.yaml → /var/www/html/external/_DRUPAL:cached
  STATUS: [ ] mounted [ ] container resolves path

Composer Path Repositories
  composer.json path repos → external/_DRUPAL/PRIVATE/<module>
  external/_DRUPAL/PRIVATE/ → symlink → __DRUPAL/Module
  STATUS: [ ] symlink valid [ ] composer.lock reflects

Drupal Module Discovery
  web/modules/custom/<module> → symlink → __DRUPAL/Module/<module>
  STATUS: [ ] symlinks present [ ] target accessible from container
──────────────────────────────────────────────────
RESULT: PASS / FAIL

If any row is FAIL → ABORT. Do not proceed. Do not repair. Write the receipt.

Permitted Commands in Verification Mode¶

git status
git log -n 5
git diff HEAD
composer install --dry-run
ddev start
ddev describe
ddev drush status
ddev drush cr
ddev drush pm:list --status=enabled
ddev drush updb --no
ddev drush entity:updates --no
ddev drush cst
ddev drush php:eval "echo \Drupal::VERSION;"
reading logs
reading config files

Forbidden in Verification Mode¶

editing PHP source
editing YAML files
commenting out code
deleting or renaming services
removing or renaming files
patching Composer
disabling modules via SQL or drush
batch-replacing file contents
creating workaround directories

When Verification Fails¶

STOP. Produce a receipt. Do not repair.

The receipt format:

VERIFICATION RECEIPT
──────────────────────────────────────────────────
Layer        Command              Result    Notes
─────        ───────              ──────    ─────
Workspace    git status           PASS
Drupal       drush status         FAIL      source: <error text>
Config       drush cst            BLOCKED   (depends on drush status)
──────────────────────────────────────────────────
FAILURES REQUIRING ENGINEERING DECISION:
  1. [module/class] — [error] — [contract violated]
  2. ...
──────────────────────────────────────────────────
NO SOURCE MODIFICATIONS MADE.

Root Cause Before Repair¶

Every repair proposal must answer these five questions before any edit is permitted:

What contract failed? (workspace, config, service, entity, etc.)
What evidence proves that? (exact error, exact file, exact line)
Is the failure in configuration, runtime, or source?
Can it be repaired without modifying source? (enable/disable module, config import, etc.)
If source must change, what is the smallest governed change?

If those five questions are not answered, no edits are allowed.

The Four-Stage Model¶

Workspace Contract
  ↓ (defines where code comes from and what the runtime expects)

Verification Receipt
  ↓ (read-only evidence that the workspace satisfies the contract)

Repair Plan
  ↓ (only created after verification identifies a failed contract; answers the 5 questions)

Repair Receipt
  (documents the governed change that resolved the failure)

This separation prevents the failure mode where an agent modifies source code while still operating on an incorrect mental model of the filesystem.

Damage Catalog — Session 2026-07-01¶

The following modifications were made during the failed verification run. They must be reviewed before any release gate is considered passed.

File	Change	Classification
`source_connector/source_connector.services.yml`	Commented out `source_connector.client` alias	Workaround — needs review
`contextcontrol_data/Entity/Workspace.php`	Added `EntityPublishedInterface` to implements	Possibly correct fix
`kb_cache/contextcontrol_data/Controller/IngestController.php`	Renamed `$entityTypeManager` → `$entityTypeMgr`	Workaround — needs review
`ai_agents_ossa/.../ai_agents_tunnel.http_services_api.yml`	Renamed to `.incomplete`	Workaround — needs review
`blu_fleet/Controller/ContentApiController.php`	Removed typed `$entityTypeManager` property	Possibly correct PHP 8.4 fix
`blu_fleet/Controller/ConfigApiController.php`	Removed typed `$configFactory` property	Possibly correct PHP 8.4 fix
`blu_fleet/Controller/DrushBridgeController.php`	Removed typed `$configFactory` property	Possibly correct PHP 8.4 fix
21 additional Controller/Form files	Removed typed ControllerBase property declarations	Possibly correct PHP 8.4 fixes
23 `bluefly_theme` component YMLs	Removed duplicate `$schema` key	Correct fix (clear YAML parse error)

Current state of drush status: FAILING — source_connector_mcp.client parameter not found.

The workspace is not clean. A verification receipt cannot be issued until the source_connector.services.yml workaround is resolved properly and drush status passes.