Data Lifecycle Contracts

Data Lifecycle Contracts

When to use

You are the SA authoring docs/architecture.md (in design or extract mode). Your data model has columns that are written by one component and read by another to gate behavior. This skill prescribes how to identify those columns and document their write-ownership contract so downstream developers don't accidentally break the gate.

The motivating bug: A repository-sync service stamped last_synced_at = CURRENT_TIMESTAMP on every upsert during the discovery phase (a natural ORM-convenience pattern). The downstream WorkerPool's skip check read the same column to decide whether to re-process a repo: now - last_synced_at | ` | | | | ` |

Authoring procedure

1. Enumerate candidate columns by walking the data model + applying the detection heuristic above. Aim for a small, focused list — most data-model columns are NOT gate fields. A typical project has 3–15 gate fields total.

1. For each candidate, identify owners. Owner = the component(s) authorized to write under the documented condition. Multiple owners is common (e.g., last_synced_at is written by both Branch Detection AND MR Collection, after successful per-repo data collection).

1. State the write condition precisely. Not "during data sync" but "AFTER successful per-repo data collection (Main Flow steps 5–8 of FR-003 complete without error)." Vague conditions don't bind BE Dev to a specific implementation point; precise conditions do.

1. Name every consumer. WorkerPool's skip check, scheduler's eligibility filter, authz middleware, etc. If you can't name a consumer, the column might not be a gate field — re-check the detection heuristic.

1. Document gate semantics. The exact condition under which the read changes behavior. E.g., now - last_synced_at 5min → mark crashed | Per-repo task workers (T-011/T-012/T-013) MUST NOT mutate collection_runs.status. Pool owns the run lifecycle; per-repo failures aggregate via event emission, not direct column writes. |

Each row encodes what was implicit in the SRS + architecture before. With §6 present, the Agent Generator extracts each row into BE Dev's `## Project Specialization` as a write-prohibition constraint:

```markdown
### Gate-field write constraints (from architecture.md §6)

For T-011 (Repository Sync Service) implementation:

- MUST NOT write to `repositories.last_synced_at`. This column is owned by T-012 and T-013, written AFTER successful per-repo data collection. T-011 only writes structural metadata: `name`, `path_with_namespace`, `gitlab_group_id`, `is_active`. The ORM-convenience pattern of stamping a timestamp on every upsert MUST be suppressed for this column.
- MAY write to `repositories.is_active` (T-011 is the owner of the active/inactive lifecycle per §6).
- MUST NOT write to `collection_runs.status` (Worker-pool-owned).

That's the kind of guardrail BE Dev needs at dispatch time. Without it, the bug is inevitable; with it, the implementation is constrained correctly.

Common pitfalls

• Treating a gate field as "just an updatedat." ORM convenience patterns (UPDATE SET updatedat = NOW() on every mutation) silently break gates. If a column is a gate, it is NOT a general-purpose timestamp — it has a specific write semantic that the gate depends on.
• Owner = "the service that touches the row most often." Owner = "the service whose write semantic matches what the reader expects." Frequency is irrelevant.
• Forgetting the precise write condition. "During the sync flow" is too vague. "After FR-003 Main Flow steps 5–8 complete without error" is precise enough to constrain BE Dev's code placement.
• Omitting the other-writer constraint. Without "T-011 MUST NOT write this column" stated explicitly, BE Dev sees no prohibition and stamps it.
• Documenting only timestamps. State enums, eligibility flags, idempotency keys, version columns are all candidates. Don't filter to "timestamp columns."
• Putting it in C3 component descriptions instead of §6. C3 prose ("upserts repositories table") doesn't bind column-level semantics. §6's table format is unambiguous.

Hard rules

• §6 is mandatory for any data model with at least one gate field. N/A is acceptable ONLY when the architecture genuinely has no cross-component column writes (rare — usually a sign you haven't applied the detection heuristic carefully enough).
• Every row's other-writer constraint is mandatory. It's the row that prevents the bug.
• Cross-reference from per-FR Data Effects. Each FR that writes a column listed in §6 must reference the §6 row in its Data Effects sub-section. This makes the contract visible at FR-level for QA-Author + Code Reviewer.
• Code Reviewer's lens-driven review checks §6 compliance. A PR that writes a §6 column without being the declared owner is flagged.
• Updates to §6 are architecture changes. Adding / removing rows or changing owners reverts SRS Status per .claude/rules/change-synchronization.md §7 (architecture change triggers downstream re-check).

References

• [.claude/agents/_templates/_artifacts/architecture-template.md](../../agents/templates/artifacts/architecture-template.md) §6 — canonical table format.
• [.claude/skills/sa-architecture-design/](../sa-architecture-design/SKILL.md) — design-mode producer of architecture data contracts.
• [.claude/agents/_templates/_artifacts/frs-template.md](../../agents/templates/artifacts/frs-template.md) — Data Effects sub-section per FR cross-references §6.
• [.claude/agents/_templates/be-dev.md](../../agents/_templates/be-dev.md) — consumer of the propagated constraints in ## Project Specialization.
• [.claude/agents/_templates/fe-dev.md](../../agents/_templates/fe-dev.md) — same, for client-side cache columns with similar gating semantics.
• [.claude/agents/_meta/agent-generator.md](../../agents/_meta/agent-generator.md) — the extraction step that pulls §6 into BE/FE Dev specialization.
• [.claude/agents/_non-sdlc/code-reviewer.md](../../agents/_non-sdlc/code-reviewer.md) — review checklist gains a §6-compliance item.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: evolplus
• Source: evolplus/talos
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.