docs: Document contract task population [doc-updater]

[james-in-a-box]

Update documentation to reflect the new contract task population feature introduced in #274.

Changes

• STRUCTURE.md: Added populate-contract-tasks.py to the action directory listing
• action/README.md: Added script entry with description
• sdlc-pipeline.md:
  • Added "Task Population" section explaining when/how tasks are extracted from plan documents
  • Added script references to "Key Files" table

Context

The populate-contract-tasks.py script was introduced in commit 5f6ccd9 to automate the extraction of tasks from plan documents into contract JSON before the implement phase begins. This bridges the gap between plan approval and implementation by:

1. Fetching the plan comment from the GitHub issue
2. Parsing [TASK-X-Y] markers using the plan parser
3. Populating the contract with phases, tasks, and acceptance criteria
4. Validating against the contract schema

This is a significant new component in the SDLC pipeline that was not previously documented.

Triggered by: 5f6ccd9

Authored-by: egg

[james-in-a-box]

Agent-mode design review: No concerns.

The documented feature (populate-contract-tasks.py) is a pre-processing step that populates structured task data before the implementing agent runs—this is helpful orientation, not problematic pre-fetching. The structured output (contract JSON) is for machine consumption by downstream pipeline steps, which is the appropriate use case per the guidelines.

— Authored by egg

[james-in-a-box]

egg agent-mode-design completed. View run logs

[james-in-a-box]

Documentation Review

This PR adds documentation for the populate-contract-tasks.py script introduced in #274. I've verified that the referenced files exist and the documentation broadly reflects the actual implementation.

Minor Inaccuracy

In docs/guides/sdlc-pipeline.md, the Task Population section states:

4. Validates the contract against the JSON schema

This is not precisely accurate. The script uses Pydantic model validation (Contract.model_validate()), not JSON schema validation. While the Pydantic models are designed to match the JSON schema in .egg/schemas/contract.schema.json, they are not the same thing.

Suggested fix:

4. Validates the contract using Pydantic models

Or if you want to keep the JSON schema reference:

4. Validates the contract against the Pydantic models (which correspond to the JSON schema)

This is a minor documentation clarity issue and does not block approval.

Verification

• ✓ action/populate-contract-tasks.py exists in the codebase
• ✓ shared/egg_contracts/plan_parser.py exists in the codebase
• ✓ The script behavior described matches the actual implementation
• ✓ File structure additions are placed correctly in alphabetical/logical order
• ✓ Referenced commit 5f6ccd9 exists and introduces this feature

— Authored by egg

[james-in-a-box]

Review Complete

This documentation PR accurately reflects the contract task population feature introduced in #274.

Verification performed:

• Confirmed action/populate-contract-tasks.py exists and matches the documented behavior
• Confirmed shared/egg_contracts/plan_parser.py exists
• Verified the script fetches issue comments, parses [TASK-X-Y] markers, and writes to the contract JSON
• Checked file structure additions are correctly placed

Finding (non-blocking): See my earlier comment about the "JSON schema" wording. The script uses Pydantic model validation, not JSON schema validation. This is a minor documentation clarity issue.

Recommendation: Ready for merge. The documentation accurately describes the feature's purpose and workflow.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

[james-in-a-box]

Review Complete - LGTM ✓

Documentation accurately reflects the contract task population feature introduced in commit 5f6ccd9.

Review notes:

• ✅ Verified populate-contract-tasks.py exists on main
• ✅ Verified plan_parser.py exists in shared/egg_contracts/
• ✅ Documentation correctly describes the workflow (fetch plan → parse → populate → validate)
• ✅ Key Files table appropriately updated with new script references
• ✅ STRUCTURE.md listing matches actual directory structure

— Authored by egg