# Data Lifecycle Contracts

> How SA identifies gate fields and cross-component column-write contracts in the data model, and documents them in docs/architecture.md §6 so BE/FE Dev know which columns each task may write. Prevents the class of bug where the "ORM convenience" pattern (stamping a timestamp on every upsert) silently breaks downstream skip / eligibility / rate-limit gates that read the same column.

- **Type:** Skill
- **Install:** `agentstack add skill-evolplus-talos-data-lifecycle-contracts`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [evolplus](https://agentstack.voostack.com/s/evolplus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [evolplus](https://github.com/evolplus)
- **Source:** https://github.com/evolplus/talos/tree/main/skills/data-lifecycle-contracts

## Install

```sh
agentstack add skill-evolplus-talos-data-lifecycle-contracts
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

2. **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).

3. **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.

4. **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.

5. **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 updated_at."** ORM convenience patterns (UPDATE SET updated_at = 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](https://github.com/evolplus)
- **Source:** [evolplus/talos](https://github.com/evolplus/talos)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-evolplus-talos-data-lifecycle-contracts
- Seller: https://agentstack.voostack.com/s/evolplus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.