Contribution & Scoped Work Flow

The Contribution & Scoped Work Flow within the flext-tap-ldif project defines a rigorous framework for engineering conduct, development cycles, and multi-agent coordination. It ensures that all modifications—whether performed by human developers or AI agents—adhere to the "Universal Agent Law," which prioritizes root-cause solutions, strict typing, and immediate landing of verified scoped work.

This workflow is integrated with the project's quality gates and Singer-based data extraction logic, maintaining a zero-debt baseline while managing complex operations like LDIF file discovery and incremental state management.

Sources: AGENTS.md:6-15, README.md:38-41

Universal Engineering Conduct

All contributions are governed by the Universal Agent Law, a set of inviolable rules designed for high-integrity engineering. This law binds all participants to fix root causes rather than implementing workarounds or stubs.

Core Principles

• Zero-Tolerance / Strict-Total: Developers must fix the root cause of any issue encountered during their task and remove superseded code in the same cycle. No "dead code" or "legacy branches" are permitted to bypass quality gates.
• Fix-Forward-Only: In a multi-agent environment, reverting state is forbidden as it destroys in-flight work. Participants must accept the current tree state and fix forward.
• Evidence-Based Completion: A task is only "Done" when the complete chain is validated with objective evidence, including commands, exit codes, and specific output lines.

Sources: AGENTS.md:18-35, AGENTS.md:58-64

Technical Requirements

The project enforces strict technical standards through its configuration and the Agent Law:

• Restrictive Typing: Use of Any or unchecked casts is forbidden. Type errors must be fixed at the source.
• SSOT (Single Source of Truth): One authoritative source per fact must be used, with no duplication.
• SOLID & YAGNI: Standard object-oriented principles are enforced, and speculative parameters or single-implementation abstractions are removed.

Sources: AGENTS.md:81-84, AGENTS.md:87-95, pyproject.toml:139-160

Scoped Work Execution Flow

The workflow for implementing features or fixes follows a deterministic cycle from planning to landing.

Execution Cycle

1. Scope Definition: Developers must stay strictly within the requested scope, mentioning unrelated issues but not touching them.
2. Blocked-Operation Protocol: If a tool or command is blocked (e.g., security sandbox), the participant must stop, diagnose, and hand the exact command to the user for manual execution.
3. Validation: All work must pass canonical make verbs: check, test, val, and docs.
4. Immediate Landing: Verified work must be landed immediately via git add, commit, and fast-forward push using explicit pathspecs.

Sources: AGENTS.md:50-56, AGENTS.md:70-79, AGENTS.md:97-104, README.md:38-41

Multi-Agent Coordination

When multiple agents share a working tree, coordination is managed through a committed task board.

The diagram shows the lifecycle of a task from initial claim to final landing, emphasizing the loop for fixing root causes and immediate landing of verified work.
Sources: AGENTS.md:106-113, AGENTS.md:18-24

System Architecture & Data Flow

The "Scoped Work" often involves interacting with the core tap logic, which processes LDIF files into Singer records.

LDIF Processing Flow

The Processor class handles file discovery and record generation using the flext-ldif library.

Sources: src/flext_tap_ldif/_utilities/processor.py:16-19, src/flext_tap_ldif/_utilities/entries_stream.py:15-18, src/flext_tap_ldif/_utilities/state_management.py:12-14

Sequence of Data Extraction

This diagram illustrates the interaction between the Tap, the EntriesStream, the File Processor, and State Management during a sync cycle.
Sources: src/flext_tap_ldif/_utilities/processor.py:59-64, src/flext_tap_ldif/_utilities/entries_stream.py:28-40, src/flext_tap_ldif/_utilities/state_management.py:18-31

Quality Gates and Standards

Contributions are not considered "Done" until they pass specific quality gates defined in the project's configuration.

• Linting & Formatting: Enforced via ruff and black.
• Typing: Strict mypy and pyright checks (e.g., reportUnnecessaryCast = "error").
• Testing: Minimum coverage thresholds and strict markers (unit, integration, e.g.) via pytest.

[tool.coverage.report]
fail_under = 20
precision = 2

[tool.pyright]
typeCheckingMode = "strict"
reportUnusedImport = "error"

Sources: pyproject.toml:102-105, pyproject.toml:292-296, README.md:38-41

Conclusion

The Contribution & Scoped Work Flow is a high-discipline framework that ensures the flext-tap-ldif repository remains maintainable and error-free. By mandating root-cause fixes and immediate landing of verified work, it prevents technical debt and coordination conflicts in complex, multi-agent development environments.

Sources: AGENTS.md:10-15, AGENTS.md:106-113