feat: add layered context sources

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to creed are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Layered context sources.** Compose cached git organization context with
+  per-repository `.creed/` files; `sync`, `diff`, `validate`, and `doctor` now
+  share the same resolved source path.
+- **Layered migration guide.** Document manifest configuration, pinned refs,
+  authentication, CI drift gating, and non-clobbering pull/push behavior.
+
 ## [0.3.0] — 2026-08-19
 
 The first post-reset feature release. Everything shipped since v0.1.0 lands

README.md

@@ -164,20 +164,42 @@ Paths in `skills` and `config` are relative to `.creed/`. `output_dir` is relati
 to the project root and is guarded so it cannot escape the project with `..` or
 an absolute path.
 
-## Source models
-
-Local source is the default: Creed reads `.creed/` from the current project.
-Git-backed sharing is available through the service `Pull` path: the git remote
-is cloned or reused from cache, then read with the same manifest, skill, and
-config semantics as a local source. The manifest can record the remote URL:
+For organization-wide context, use an ordered layered source. Shared layers are
+read first and the consumer's local `.creed/` layer is always read last:
 
 ```yaml
 source:
-  type: git
+  type: layered
   path: .creed
-  remote: https://github.com/example/context.git
+  layers:
+    - name: org
+      type: git
+      remote: https://github.com/TechGodHQ/agent-context.git
+      path: .creed
+      ref: 0123456789abcdef0123456789abcdef01234567
 ```
 
+A later layer with the same skill or config name overrides the earlier entry.
+Use distinct names when both entries should be emitted. See
+[`docs/layered-context-migration.md`](docs/layered-context-migration.md) for
+migration and CI guidance.
+
+## Source models
+
+Local source is the default: Creed reads `.creed/` from the current project.
+A direct git source remains supported for compatibility. Layered sharing is the
+v0.4 path: the configured git layers are cloned or reused from cache, then
+composed with the local source through the same SourceReader used by `sync`,
+`diff`, `validate`, and `doctor`.
+
+`creed pull <remote>` records the remote as an `org` layer and composes it; it
+never replaces local `.creed/` files. `creed push` is rejected for layered
+sources so shared context changes go through review instead of clobbering the
+central repository.
+
+See [`docs/layered-context-migration.md`](docs/layered-context-migration.md)
+for the full manifest and migration guide.
+
 Git remotes support public HTTPS URLs, private HTTPS URLs with the configured
 service token, and SSH URLs through either `SSH_AUTH_SOCK` or an explicit
 `CREED_GIT_SSH_KEY` path. If the key is passphrase-protected, set
@@ -227,6 +249,7 @@ Creed uses a ports-and-adapters layout:
 - `internal/ports`: source-reader and target-emitter interfaces.
 - `internal/adapters/localfs`: reads `.creed/` and writes target files locally.
 - `internal/adapters/gitremote`: reads `.creed/` from a git remote clone/cache.
+- `internal/adapters/layered`: composes ordered local/git source readers.
 - `internal/usecase`: the sync engine and result model.
 - `internal/service`: the canonical API shared by generated CLI, MCP, and HTTP surfaces.
 - `internal/codegen`: parses the service interface and emits operation descriptors plus

docs/architecture.md

@@ -106,6 +106,8 @@ Implemented adapters:
 - `localfs.Source`: reads `.creed/` in the current project.
 - `gitremote.Source`: clones or reuses a cached git repository, then delegates
   reads to the local filesystem adapter.
+- `layered.Source`: merges ordered local/git readers into one SourceReader; the
+  service appends the consumer's local reader after shared layers.
 
 ## Target emitters
 
@@ -124,12 +126,13 @@ and skips files whose content is already identical.
 
 `internal/usecase.SyncEngine` performs one sync run:
 
-1. Read `.creed/manifest.yaml`.
-2. Resolve either a requested target (`--target`) or all enabled targets.
-3. Validate `output_dir` so emitted paths cannot escape the project root.
-4. Read all manifest-declared skills and config files.
-5. For each target, prepare emitted files from target path metadata.
-6. Emit files, collecting per-file and per-target result data.
+1. Read `.creed/manifest.yaml` and resolve its local/git/layered source graph.
+2. Read every ordered shared layer, then the consumer's local source.
+3. Resolve either a requested target (`--target`) or all enabled targets.
+4. Validate `output_dir` so emitted paths cannot escape the project root.
+5. Read all composed skills and config files.
+6. For each target, prepare emitted files from target path metadata.
+7. Emit files, collecting per-file and per-target result data.
 
 Partial target failures are isolated: one failed target does not prevent the next
 target from running. A top-level error is reserved for failures that prevent the

docs/layered-context-migration.md

@@ -0,0 +1,92 @@
+# Layered context migration
+
+Creed v0.4 can compose a shared organization context repository with the
+repository's own `.creed/` files. The shared layer is emitted first and the
+local repository layer is emitted second, using the same `---` separator that
+Creed uses for ordinary config aggregation.
+
+## Manifest contract
+
+Add an ordered `source.layers` list to the consumer repository's manifest:
+
+```yaml
+version: 1
+source:
+  type: layered
+  path: .creed
+  layers:
+    - name: org
+      type: git
+      remote: https://github.com/TechGodHQ/agent-context.git
+      path: .creed
+      # Prefer a full commit SHA for reproducible CI.
+      ref: 0123456789abcdef0123456789abcdef01234567
+
+targets:
+  - name: codex
+    enabled: true
+    output_dir: .
+config:
+  - name: repo
+    path: config/repo.md
+skills:
+  - name: repo-review
+    path: skills/repo-review.md
+```
+
+`source.layers` is ordered. Creed always appends the consumer's local source
+as the final layer. A layer can be `type: local` for a second local source, or
+`type: git` for a cloned source. `path` is relative to the layer root and
+defaults to `.creed`. `ref` may pin a branch, tag reference, or commit SHA.
+
+The consumer's local `source.path` remains `.creed`; custom `path` values are
+for git or secondary local layers. Pull rejects URLs with embedded credentials,
+queries, or fragments—configure HTTPS tokens or SSH authentication separately.
+
+If two layers declare the same skill or config name, the later layer wins. Use
+distinct names when both pieces of context should be emitted; distinct config
+names are normally preferable for organization rules and repository rules.
+
+## Migration steps
+
+1. Create a central repository containing organization-wide config and skills
+   under `.creed/`, with its own `manifest.yaml`.
+2. Remove duplicated organization entries from each consumer repository only
+   after the central repository has been pushed and its commit SHA recorded.
+3. Add the layered `source` block above to each consumer manifest, retaining
+   the consumer's targets and repository-specific entries.
+4. Run `creed validate`. It fetches every configured layer and checks the
+   referenced remote files as well as local files.
+5. Run `creed sync` and review the generated target files.
+6. Add `creed diff` to CI. It uses the same composed source and exits `1` when
+   generated output drifts, so central-context changes are gated too.
+
+## Pull behavior
+
+`creed pull <remote>` now records the remote as an `org` layer and composes it
+with the local source. It never replaces local `.creed/config/*` or
+`.creed/skills/*`. If the consumer has no manifest yet, pull creates a minimal
+layered manifest so `validate`, `doctor`, and `diff` remain usable afterward.
+
+`creed push` is intentionally rejected for layered sources. Shared context
+should be changed in the central repository through the normal review/PR path;
+blindly copying a consumer `.creed/` directory back to the organization
+repository would reintroduce the v0.3 clobbering failure mode.
+
+## Authentication and caching
+
+- Public and private HTTPS remotes use go-git HTTPS authentication. Configure
+  the service token with the existing `WithGitToken` integration path; tokens
+  are not written into URLs or reports.
+- SSH remotes use `SSH_AUTH_SOCK`, or `CREED_GIT_SSH_KEY` plus
+  `CREED_GIT_SSH_PASSPHRASE` for an explicit key.
+- `WithCacheDir` enables commit-aware clone caching. A pinned commit reuses its
+  cached clone; an unpinned branch is refreshed when its remote HEAD changes.
+- `creed doctor` reports the configured remote with embedded passwords removed.
+
+For CI-secret-backed end-to-end verification, set
+`CREED_RUN_GITHUB_AUTH_INTEGRATION=1` together with
+`CREED_GITHUB_HTTPS_REMOTE`/`CREED_GITHUB_HTTPS_TOKEN` and/or
+`CREED_GITHUB_SSH_REMOTE`. The integration test exercises the complete layered
+service path and never prints or stores the token. SSH mode uses the runner's
+`SSH_AUTH_SOCK` or `CREED_GIT_SSH_KEY` configuration.