Documentation

Concepts / Ownership

Keep your facts in the right place.

Cumaru separates shared framework instructions from the knowledge and decisions your project owns.

Ownership is explicit

The configured tree can mark an entry with framework: true. That marker belongs to the entry; it does not automatically mark all children. A framework-owned directory can contain adopter-owned knowledge.

For example, a domain can ship the rules for a specs pillar while the individual project specs remain yours. Inspect the installed configuration and the selected domain rather than inferring ownership from a path name.

Source: update's ownership rules.

Tag bodies preserve local context

Framework-owned Markdown can contain named semantic tags. The material inside their balanced opening and closing markers is adopter data. The surrounding canonical prose can receive framework updates.

For example, the root tag in domain.md can hold confirmed project context:

<!-- cumaru:root -->
The API serves the customer portal.
Keep existing client integrations compatible.
<!-- /cumaru:root -->

This text is an example, not a default for your project. Record your own confirmed facts. Use cumaru tag to inspect and replace tag bodies; keep canonical framework instructions outside the tags intact.

Sources: project context and semantic tags.

A refresh respects a specific boundary

Ordinary content update selects entries explicitly marked framework-owned in both the installed and source configurations. It refreshes canonical content and restores local tag bodies. Local-only files and unowned entries are not ordinary content-update targets.

Moving project prose outside a protected tag in a framework-owned file does not turn it into adopter-owned content. Put durable facts in the domain's own knowledge pillar, or local context in its declared tags.

Adapter refresh and configuration reconciliation are separate operations. Configuration reconciliation reports a candidate; the agent must review the choices. Do not treat every update mode as the same operation.

Source: the update contract.

Paths and prose use different operations

  • Use cumaru fs to create, copy, move, or remove paths under .cumaru/.
  • Use cumaru tag for declared semantic tag bodies.
  • Edit ordinary adopter-owned prose with an editor and validate the result.

These operations do not grant lifecycle authority. Removing a completed plan still requires the domain's acceptance, recovery, and close-out gates.

Sources: filesystem operations and the SDLC Light close workflow.

Next: distinguish roles, skills, and disciplines.