chore(workspace): absorb post-merge lane commits and the render-drift fix

.agents/INSTRUCTION_SURFACE.md

@@ -0,0 +1,52 @@
+# FLEXT Agent Surface Registry
+
+**Reviewed:** 2026-07-15
+
+**Scope:** ownership, activation, and drift control
+
+The machine-readable declaration is [`provider.toml`](provider.toml). This file
+explains ownership only; it never duplicates the declared skill list or domain
+rules.
+
+## Owners
+
+| Concern | Canonical owner |
+| --- | --- |
+| Universal conduct | managed universal block in [`AGENTS.md`](../AGENTS.md) |
+| FLEXT workspace routing | [`docs/GOVERNANCE.md`](../docs/GOVERNANCE.md) |
+| Provider identity and exported paths | [`provider.toml`](provider.toml) |
+| Session entry point | [`commands/flext-law.md`](commands/flext-law.md) |
+| Task procedure | frontmatter and content of the selected `skills/*/SKILL.md` |
+| Structural codemod inventory | provider referenced by `provider.toml` |
+| Architecture decisions | [`docs/architecture/adr/README.md`](../docs/architecture/adr/README.md) |
+
+## Activation Contract
+
+- `flext-core`-validated project metadata is the only project-type detector.
+- The provider activates only when the normalized dependency set contains the
+  marker declared in `provider.marker_distribution`.
+- Only `surfaces.always` loads at activation. The context router selects the
+  smallest relevant subset of `surfaces.on_demand`.
+- Provider consumers expose workspace-local references to these files; they do
+  not own copies of FLEXT content.
+
+## Anti-Drift Contract
+
+Every change must either update the owner when reality changes or verify that
+the impacted owner is still current. In the same change:
+
+1. Add, rename, or remove a skill path in `provider.toml` with its `SKILL.md`.
+2. Update docs and agent pointers when an owner or behavior changes.
+3. Remove superseded prose, aliases, copies, and catalog entries.
+4. Keep codemod rule IDs only in the referenced codemod provider.
+
+Counts are derived from the provider declaration and filesystem; never maintain
+a prose count. Tests and checks validate declarations and behavior, but are
+never a source of truth.
+
+## Validation
+
+Validation must prove that every declared path exists, every local `SKILL.md` is
+declared exactly once, the always-loaded set contains only the context router,
+and referenced provider manifests are valid. Record the command, exit code, and
+decisive output in the active workspace-root Bead.

.agents/README.md

@@ -0,0 +1,23 @@
+# FLEXT Agent Provider
+
+This directory is the Git-tracked FLEXT provider consumed by agent managers.
+It owns project-specific agent surfaces, not universal agent behavior.
+
+## Canonical Owners
+
+- [`provider.toml`](provider.toml) — provider identity, activation marker,
+  router, exported skill paths, and codemod provider path.
+- [`commands/flext-law.md`](commands/flext-law.md) — compact session router.
+- [`skills/*/SKILL.md`](skills/) — on-demand procedures and trigger metadata.
+- [`INSTRUCTION_SURFACE.md`](INSTRUCTION_SURFACE.md) — human-readable ownership
+  and drift contract.
+- [`docs/GOVERNANCE.md`](../docs/GOVERNANCE.md) — workspace concern routing.
+
+The structural codemod provider referenced by `provider.toml` owns codemod rule
+IDs and artifacts. Static enforcement policy remains with its validated domain
+declarations; neither surface duplicates the other.
+
+When reality changes, update its owner and every affected docs, skill, agent,
+catalog, and consumer pointer in the same change. If behavior did not change,
+verify those surfaces are current. Tests and checks validate the owners; they
+never define provider identity, domain behavior, config, or fundamental rules.

.agents/commands/flext-law.md

@@ -0,0 +1,5 @@
+# FLEXT Law session
+
+This session is bound to the Gas Town rig `flext`. Run `gt prime` first.
+Read `.agents/skills/flext-context-routing/SKILL.md` and follow its composition.
+Do not resolve `flext-law` by unqualified catalog name.

.agents/coordination/tasks.md

@@ -0,0 +1,13 @@
+# FLEXT Coordination Tasks
+
+This file is not a task board.
+
+Use Beads (`bd`) for ownership, status, dependencies, leases, validation
+evidence, and subagent coordination. Do not add rows here.
+
+Legacy rows migrated on 2026-06-07:
+
+- `strict-recovery-001`: stale expired lease; current work is represented by
+  `mro-hbj4.4`, `mro-nwc.14`, and related Beads.
+- `strict-recovery-002`: security scan coverage is represented by
+  `mro-uqji.6.8.6`.

.agents/prompts/continuation-monopoly.md

@@ -0,0 +1,63 @@
+# Continuation Prompt: FLEXT Fix-Forward Monopoly
+
+You are taking exclusive execution ownership of `/home/marlonsc/flext` until
+the assigned work reaches a demonstrably healthy end state. You may coordinate
+read-only research, but no other actor may mutate overlapping FLEXT paths while
+you own the task. Preserve all pre-existing work as provenance; do not reset,
+restore, clean, stash, rebase, normalize branches, or rewrite history.
+
+Read, in order:
+
+1. `/home/marlonsc/.agents/AGENTS.md`
+2. `/home/marlonsc/.agents/UNIVERSAL_CORE.md`
+3. `/home/marlonsc/flext/AGENTS.md`
+4. `/home/marlonsc/flext/.agents/skills/flext-law/SKILL.md`
+5. `/home/marlonsc/.agents/skills/inviolable-rules/SKILL.md`
+6. `/home/marlonsc/.agents/skills/make-check/SKILL.md`
+7. `/home/marlonsc/.agents/skills/verification-loop/SKILL.md`
+<!-- Why: cutover to exact global generic skills after the local flext-inviolable-rules removal (mro-1o6t.1.1) -->
+
+## Operating contract
+
+- Work only on `0.12.0-dev`; `0.20.0-dev` is read-only comparison evidence.
+- Use Beads as the sole work tracker. Start with `bd ready --json`, inspect
+  `bd show <id> --json`, claim the selected Bead, and record evidence there.
+- Use only root `make` commands for FLEXT validation. Never use direct tool
+  commands to bypass the project dispatcher.
+- Keep the implementation focused on the assigned live Bead. Do not perform
+  branch equalization, broad fixture cleanup, bulk Bead changes, archive
+  restoration, or governance migration unless the live Bead explicitly owns it.
+- Archives and `agentes-legacy` are evidence only. Do not copy or activate
+  their contents without an explicit current governing decision.
+
+## Non-negotiable healthy-task rule
+
+The project must not be left broken or in unowned WIP at the end of any task.
+After the final code/configuration edit, and before marking a Bead complete,
+you must prove all of the following from `/home/marlonsc/flext`:
+
+```bash
+make check CHECK_GATES=lint,pyrefly
+make check PROJECT=<affected-project> CHECK_GATES=pyright,mypy
+make test PROJECT=<affected-project>
+```
+
+Run supported targeted Make tests first, then the required project-level gates.
+If the change crosses packages, generated files, fixtures, configuration, or
+public facades, widen the scope. Manually use the changed public surface
+(Make/CLI for workspace behavior, import/driver for libraries, or live service
+surface where applicable).
+
+A required non-zero result is a blocker, not a successful handoff. Fix it
+forward, rerun every invalidated gate, or create one narrow linked Bead for a
+genuine external blocker and leave the current Bead in progress. Never lower
+coverage, skip gates, suppress diagnostics, or classify a failure as baseline
+without fresh reproducible evidence and an owner.
+
+## Required final report
+
+Do not finish until you can report: active/closed Bead IDs; changed and
+preserved paths; manual-QA behavior; global Ruff/Pyrefly result; affected-scope
+Pyright, mypy, and pytest results; remaining external blockers; and the final
+root plus affected-submodule Git status. Commit or push only with explicit user
+authorization and explicit pathspecs.

.agents/provider.toml

@@ -0,0 +1,12 @@
+source_project_id = "flext-sh/flext"
+marker_distribution = "flext-core"
+router_skill = "flext-context-routing"
+session_command = ".agents/commands/flext-law.md"
+codemod_provider = "flext-infra/src/flext_infra/codemod/sgconfig.yml"
+marketplaces_key = "extraKnownMarketplaces"
+enabled_plugins_key = "enabledPlugins"
+required_surfaces = ["flext-infra/src/flext_infra/codemod/sgconfig.yml"]
+
+[surfaces]
+always = [".agents/skills/flext-context-routing/SKILL.md"]
+on_demand = [".agents/skills/flext-law/SKILL.md"]

.agents/skills/beads/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: beads
+description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.
+---
+
+# Beads
+
+Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.
+
+## First Step
+
+Run:
+
+```bash
+bd prime
+```
+
+If that prints nothing, check whether the repository has an active Beads workspace:
+
+```bash
+bd where
+```
+
+## Preferred Route
+
+Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.
+
+## Core CLI Workflow
+
+1. Find work:
+
+```bash
+bd ready
+bd list --status=open
+bd list --status=in_progress
+```
+
+2. Inspect before editing:
+
+```bash
+bd show <id>
+```
+
+3. Claim work atomically:
+
+```bash
+bd update <id> --claim
+```
+
+4. Create durable follow-up work when implementation reveals new tasks:
+
+```bash
+bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
+```
+
+5. Close completed work:
+
+```bash
+bd close <id> --reason="Completed"
+```
+
+## What Belongs In Beads
+
+Use Beads for:
+
+- shared project tasks
+- blockers and dependencies
+- discovered follow-up work
+- work that must survive thread reset, compaction, or handoff
+- status that another person or agent should be able to resume
+
+Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.
+
+## Rules
+
+- Do not create markdown TODO files as the source of truth when Beads is available.
+- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.
+- Prefer `--json` when parsing `bd` output programmatically.
+- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.
+- Do not auto-close or mutate tasks unless the work is actually complete.

.agents/skills/beads/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Beads"
+  short_description: "Project task tracking with bd"
+  default_prompt: "Use $beads to inspect ready work and manage durable project tasks."

.agents/skills/code-navigation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: code-navigation
+description: 'Use this skill to use when navigating code, searching for symbols, finding
+  references, or exploring codebase structure. ALWAYS prefer scope commands over grep,
+  find, or reading files. Returns structural intelligence (class sketches, caller
+  chains, dependency graphs) in ~200 tokens instead of. DO NOT USE FOR: questions
+  unrelated to code-navigation creating projects or architecture from scratch'
+license: MIT
+metadata:
+  version: 1.0.0
+---
+
+# Scope — Code Intelligence for LLM Agents
+
+**UTILITY SKILL**
+
+## USE FOR
+
+- Requests about code navigation.
+- Workflows described in this skill.
+- Operator tasks within this scope.
+
+## DO NOT USE FOR
+
+- questions unrelated to code-navigation.
+- creating projects or architecture from scratch.
+
+## Workflow
+
+1. Understand.
+2. Execute.
+3. Validate.
+
+## Critical rules
+
+- Prefer canonical sources.
+- Require evidence.
+
+## Example
+
+**Input:** a request.
+**Output:** a concise response.
+
+## Troubleshooting
+
+- Unclear scope → ask.

.agents/skills/code-navigation/evals/evals.json

@@ -0,0 +1,39 @@
+{
+  "skill_name": "code-navigation",
+  "evals": [
+    {
+      "id": "scope-status-check",
+      "prompt": "Is Scope CLI available in this project? How should I start exploring the codebase structure?",
+      "expected_output": "Run `scope status` first to check if `.scope/` exists. If yes, use `scope map` for architecture overview. If not, initialize with `scope init`. Do not use grep or find for structural navigation.",
+      "files": [],
+      "assertions": [
+        "mentions `scope status` as first step",
+        "mentions `scope map` for architecture overview",
+        "does NOT suggest using grep or find for structural navigation",
+        "mentions .scope/ directory"
+      ]
+    },
+    {
+      "id": "find-class-callers",
+      "prompt": "Find all places that call the `parse_entry` function in flext-ldif.",
+      "expected_output": "Use `scope callers parse_entry` to get the caller chain in ~200 tokens. Do not use grep or rg for this.",
+      "files": [],
+      "assertions": [
+        "uses `scope callers` command",
+        "does NOT recommend grepping source files",
+        "output is structural, not raw text search"
+      ]
+    },
+    {
+      "id": "class-structure-without-reading",
+      "prompt": "What methods does FlextLdifModels have? I don't want to read the whole file.",
+      "expected_output": "Use `scope sketch FlextLdifModels` to get a class outline with method signatures in ~200 tokens without reading the full source file.",
+      "files": [],
+      "assertions": [
+        "uses `scope sketch` or equivalent structural command",
+        "explicitly avoids reading the full file",
+        "returns method signatures without body content"
+      ]
+    }
+  ]
+}

.agents/skills/flext-agent-integration/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: flext-agent-integration
+description: Integrate the FLEXT provider with an agent manager or audit its projection lifecycle. Use for provider discovery, workspace-local skill exposure, and stale projection removal. Do not use for FLEXT domain implementation or generic agent configuration.
+license: MIT
+metadata:
+  version: 2.0.0
+---
+
+# FLEXT Agent Integration
+
+Use this skill at the provider boundary. Domain behavior remains in the
+on-demand skill that owns it.
+
+## Workflow
+
+1. Read `.agents/provider.toml` as the provider declaration.
+2. Detect eligibility only from `flext-core`-validated project metadata and the
+   declared `marker_distribution`.
+3. Expose the router and listed skills as workspace-local references to this
+   repository; do not copy their content into the manager.
+4. Load only `surfaces.always` at activation. Let `flext-context-routing`
+   select entries from `surfaces.on_demand`.
+5. Delegate structural rewrite configuration to the codemod provider referenced
+   by `.agents/provider.toml`; never duplicate its rule IDs.
+6. On deactivation or catalog change, remove only references previously managed
+   by this provider and verify no stale projection remains.
+
+## Critical rules
+
+- The provider declaration owns availability; skill frontmatter owns routing
+  intent; the referenced file owns implementation guidance.
+- No machine-specific tool inventory, global FLEXT copy, compatibility alias,
+  or second catalog is allowed.
+- Tests and checks are validators, never SSOT.
+- Missing, duplicate, escaping, or unlisted paths block projection.
+
+## Example
+
+**Input:** an agent manager enters a project whose validated dependencies include
+`flext-core`.
+
+**Output:** expose this provider locally, load `flext-context-routing`, and defer
+all other skills until task intent selects them.
+
+## Troubleshooting
+
+- Marker mismatch: keep the provider inactive and report the validated metadata.
+- Projection collision: stop and report both owners; never overwrite an
+  unmanaged surface.
+- Catalog drift: repair the declaration or owner before exposing the provider.