ADR-0032: Resource Ownership and Sharing

Accepted

Date: 2026-06-25 Depends on: ADR-0031 (Identity Model and RBAC) Followed by: ADR-0033 (Operational Governance)

Context

Almathal generates applications for engineering teams in enterprise organizations. Every generation produces artifacts: a Spec, generated source code, container manifests, test suites, and a governance package. These artifacts have value beyond the individual generation event — they are reused, evolved, shared, and handed off as team membership changes.

Three questions require explicit decisions:

Who owns a generated artifact — the Developer who triggered it, the Team, or the Organization?
How does access to artifacts work when a Developer leaves the organization or changes teams?
How does incomplete or prior work transfer to a new Developer?

Without explicit answers, the platform either defaults to individual ownership (artifacts disappear when a Developer leaves, or are inaccessible to anyone who needs to continue the work) or defaults to fully open access (anyone can see anyone’s work, violating least-privilege). Neither default is correct for an enterprise platform.

Decision

Organizational Ownership of Generated Artifacts

All generated artifacts are owned by the Organization. The Developer who triggered the generation is the creator — recorded in the audit trail for attribution and context — but not the owner. Ownership never transfers to the Developer and never leaves the Organization.

This reflects the reality of employment: code written by an employee on company time is a company asset. Almathal makes this explicit at the platform level rather than leaving it to individual employment contracts to enforce.

Practical consequences:

Artifacts are never deleted when a Developer leaves the Organization
A Developer cannot remove or delete their own generated artifacts (they are Organization assets, not personal files)
Access to artifacts is governed by the Role-Based Access Control model (ADR-0031), not by personal ownership
The generating Developer’s creator attribution persists in the audit trail indefinitely, even after they leave

Creator Attribution

Although Developers do not own their artifacts, their role as creator is recorded and preserved:

Every generated artifact’s audit trail records the user ID of the generating Developer, the generation timestamp, the Spec that drove the generation, and the pipeline results
This attribution survives account deactivation — the creator’s user ID remains in the audit trail even after the account is archived
Attribution is immutable — it cannot be changed or reassigned

Creator attribution serves two purposes: governance (who made what decision, when) and context (when the Team Lead or a new Developer is reading the work, understanding who built it and when helps interpret design choices).

What Constitutes a Generated Artifact

For the purposes of this ADR, the following are platform artifacts owned by the Organization:

Spec — the approved Archetype Spec that drove the generation
Generated source code — all files produced by Scaffolding and Stitching
Saved Spec templates — Specs saved as reusable templates (per ADR-0014)
Governance package — SBOM, provenance records, audit trail, NIST mapping, vulnerability snapshot
Build records — pipeline stage results, verification outcomes, AI invocation logs

Default Access (Recap from ADR-0031)

A generated artifact is accessible by default to:

The generating Developer (their own work)
The Team Lead of the Developer’s Team (all team members’ work)
The Org Technical Lead (all work across the Organization)
The Auditor (governance package and generated code, read-only)
The Platform Admin (via break-glass)

Not accessible by default to:

Other Developers in the same Team (they see their own work only, until shared)
Developers in other Teams

The Team Lead is the sharing authority within a Team. When a Team Lead shares an artifact:

They select the specific artifact (Spec, generated code, or full generation package) and the recipient (one Developer, multiple Developers, or the whole Team)
The recipient gains read access to the shared artifact
Sharing is explicit and logged — the audit trail records who shared what with whom and when
Sharing does not transfer ownership
The Team Lead can revoke sharing at any time

Developers cannot share their own artifacts with other Developers directly. The Team Lead is the sharing authority. This preserves the principle that artifact access changes are governed decisions, not individual choices.

The Spec as Primary Handoff Artifact

The Spec is the single most important artifact for handoff scenarios. It contains:

The Archetype and version used
All resolved Slot selections (which Adapters and Modules)
All Variation Point values (entity definitions, configuration choices, integration selections)
The locked component versions (for reproducibility)
The Seam contracts that drove the Stitcher’s work

A developer reading the Spec understands what was designed — the intent, the decisions, the data model — even if they did not participate in creating it. The Spec is the design document that survives the individual who authored it.

Spec reader UI — the Spec is stored as structured JSON but must be presented to humans as a readable document. The platform renders the Spec in the same human-readable format used during Build Approval (the Briefing Generator output from ADR-0012). The Spec reader view shows entity definitions, Slot selections, Variation Point values, and version choices in a form a developer can read without knowledge of the underlying JSON schema. This is a required product UI feature for handoff to work in practice.

Developer Offboarding

When a Developer leaves the Organization or is deactivated:

Account state: The Developer’s account is archived, not deleted. The archived account retains the user ID and profile for audit trail resolution — future readers of the audit trail can identify who created an artifact even after the account is inactive. The archived account cannot log in, cannot generate, and cannot access the platform.

Artifact state: All generated artifacts created by the departing Developer remain exactly where they are, accessible per the normal RBAC model. Nothing is reassigned, moved, or deleted.

In-progress work: The Spec for any in-progress or incomplete generation is preserved. The Team Lead can access the Spec and share it with whoever will continue the work.

No forced ownership transfer: There is nothing to transfer — the Organization always owned the artifacts. The Team Lead simply shares the relevant Spec with the incoming Developer.

Incomplete Work Handoff

“Incomplete work” in Almathal is not uncommitted code in a repository — it is one of three distinct states, each with a different handoff approach:

State 1 — Spec created, generation never ran: The design exists but nothing was built. Handoff: Team Lead shares the Spec with the new Developer. New Developer reviews the Spec via the Spec reader, optionally modifies it, and generates. The generation runs fresh from the Spec.

State 2 — Generation failed mid-pipeline: The generation ran but failed during Scaffolding, Stitching, or Build Verification. The Spec is preserved. Any partially-produced artifacts from the failed run are available for diagnosis but are not delivered artifacts. Handoff: Team Lead shares the Spec with the new Developer. The new Developer addresses whatever caused the failure (Adapter version conflict, Seam contract error, etc.) and re-runs the generation from the same Spec.

State 3 — Generation completed, feature set is incomplete: The app was generated successfully and is deployed or ready for deployment, but only covers a portion of the intended scope (for example, 70% of the planned entities or features). This is not an incomplete generation — it is a complete generation of an incomplete Spec. Handoff: Team Lead shares the existing Spec with the new Developer. The new Developer creates a new Spec version (adding the missing entities, Seams, or configuration) and generates the next version of the app. The prior generation’s Spec is the starting point, not a failed artifact.

In all three states, the Spec is the handoff artifact and the Team Lead is the sharing authority.

Saved Spec Templates and Reuse

Saved Spec templates (per ADR-0014) function as reusable patterns at the Team or Organization level:

A Developer can save their approved Spec as a template for their own use
A Team Lead can promote a Spec to a Team template, making it available to all Team members
An Org Technical Lead can promote a Team template to an Organization template, making it available across all Teams

This promotion chain allows successful patterns to propagate across the organization. If one team builds a well-designed internal admin tool, their Spec becomes the starting point for the next team building a similar tool — without requiring the second team to design from scratch.

Template usage is tracked in the observability dashboard per ADR-0033: which templates are most used, how generated apps evolved from a common template base.

Developer Changes Teams

When a Developer moves from Team A to Team B within the same Organization:

Their generated artifacts remain associated with Team A (where they were created) and accessible to Team A’s Team Lead
The Developer’s access to their own prior work in Team A is removed (they are no longer on that Team)
If the Team Lead of Team A wants the Developer’s prior work to be accessible to them in Team B, the Team Lead explicitly shares specific artifacts with the Developer in their new Team
The Developer’s new work in Team B is associated with Team B

This preserves team-level data boundaries. A Developer who moves teams does not carry their prior team’s codebase with them by default.

Rationale

Organizational ownership reflects how enterprise software development actually works. Code written by an employee belongs to the company. Making this explicit at the platform level removes ambiguity and prevents edge cases where a Developer might feel they have personal rights over generated artifacts.

Creator attribution without ownership serves the legitimate need for context and accountability. Knowing who built something and when — even after that person has left — is valuable for governance, code review, and institutional knowledge. Separating attribution from ownership gives both without conflating them.

The Spec as handoff artifact follows naturally from the platform’s architecture. The Spec is already the complete description of what was designed and why. It is version-locked, human-readable via the Spec reader, and reusable as a template (ADR-0014). Making it the explicit handoff mechanism requires no new machinery — only explicit acknowledgment of what the Spec already is.

Team Lead as sharing authority maintains the principle that access changes are governed decisions, not individual choices. A Developer sharing their own work directly would bypass the oversight layer that the Team Lead provides. Requiring the Team Lead to share preserves the access control model without making sharing burdensome (the Team Lead can share with the whole team in one action).

Account archiving instead of deletion preserves audit trail integrity. Deleted accounts break historical audit records. Archived accounts keep the user ID resolvable in perpetuity while preventing future access.

Future Considerations

Spec reader UI — the platform must render Specs as human-readable documents in the same format as the Build Approval summary. This is a required product UI feature before handoff is practical. It is a product design concern, not an ADR concern; it is flagged here so it appears on the product backlog.

Spec version history — when a Spec template is used as the basis for multiple successive generations (evolving an app over time), a version history of the Spec would allow the Team Lead and Org Technical Lead to see how the design evolved. This is an observability feature noted for ADR-0033.

Partial generation artifact preservation — currently, failed generation artifacts are available for diagnosis but their retention period and format are not specified. A future decision should define how long failed generation artifacts are retained and what form they take.

Cross-team Spec sharing — this ADR covers sharing within a Team (Team Lead shares with Developers) and promotion to Organization templates (Org Technical Lead promotes). Direct sharing between Team Leads of different Teams is not addressed. If two Teams want to collaborate on a shared Spec, the current path is promotion to an Organization template. A future ADR may address direct cross-team collaboration if the use case is validated by customers.

References

ADR-0014: Save Approved Specs as Reusable Templates — the Spec template mechanism that enables the handoff model
ADR-0028: Almathal AI Governance Posture — creator attribution is part of the audit trail requirements established there
ADR-0031: Identity Model and RBAC — the RBAC model that governs who can access artifacts; this ADR operates within those access boundaries
ADR-0033: Operational Governance — template usage tracking and Spec version history are observability features addressed there