id: folder-contract kind: architecture title: Source Projection Contract status: active #
Source Projection Contract #
A Charter project is not equivalent to one local repository or one spec/ directory. A local controller selects any number of files, folders, or repositories and maps them into stable project sources.
./spec/**/*.md is the useful zero-configuration default for Charter's own repository. It is not the runtime boundary.
Examples:
charter source add ./spec --include '**/*.md'
charter source add ../product-docs --include 'architecture/**/*.md'
charter source add ~/notes/decision.md
charter source add ~/code/service-a --include 'README.md' --include 'docs/**/*.md'
Selections and absolute paths are machine-local controller state. Shared Jazz rows contain a stable source id, portable display name, source kind, relative projection path, normalized content, and provenance. Another controller may map the same source ids to entirely different local paths or choose not to materialize them.
Frontmatter #
A Markdown source document may include YAML frontmatter:
---
id: stable-document-id
title: Human Title
kind: architecture | decision | task | glossary | note | experience
status: draft | active | accepted | archived
---
Known fields:
id: stable document identity.title: human-readable title.kind: broad document category.status: lifecycle state.owners: people or agents responsible for the document.depends_on: other document ids.supersedes: prior document ids.
Identity #
The importer uses frontmatter.id when present. If id is missing, it derives identity from the stable source id plus the path relative to that source root.
Path-derived ids are convenient for scratch documents but bad for stable specs. A rename can become a delete plus create unless content identity or source-adapter metadata establishes continuity. Stable documents should pin id before meaningful work depends on them.
Absolute paths never define shared identity.
Human authority #
Markdown is one human-editable projection. Jazz rows are the durable coordination surface.
Agents may propose changes, annotate documents, and execute accepted work. They should not silently become the author of record for product intent. If an agent writes back through a local source projection, the resulting event must carry agent provenance and the local controller must confirm that the write still targets the selected source version.
Source adapters #
The first adapter is filesystem Markdown. The source contract also permits Git worktrees, API-backed documents, and future rich editors.
Adapters own transport and source-specific operations. Charter owns selection, stable identity, normalized content, versions, freshness, packets, and provenance. A Git adapter may inspect commits, refs, diffs, and working-tree state through Git; those are not silently promoted into Jazz branch semantics.