Telling forge which parts of a repository are yours — one file (`forge project disown`, `--absent`), whole areas forge must never write (`scaffold.exclude` in forge.yaml), and the files a feature pinned off leaves behind (`forge generate`'s orphan report, `forge project prune --orphans`). Use when adopting forge in an existing repo, when forge writes somewhere it should not, or after switching a feature off.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Ownership?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/reliant-labs-ownership)
---
name: migration/ownership
description: Telling forge which parts of a repository are yours — one file (`forge project disown`, `--absent`), whole areas forge must never write (`scaffold.exclude` in forge.yaml), and the files a feature pinned off leaves behind (`forge generate`'s orphan report, `forge project prune --orphans`). Use when adopting forge in an existing repo, when forge writes somewhere it should not, or after switching a feature off.
applies: any
---
# Ownership: what forge may write
Every path in a forge project is one of three things:
| Kind | Marked by | Forge's behaviour |
|---|---|---|
| Generated (Tier-1) | `// Code generated by forge` + `// forge:hash=…` | rewritten every run; a hand-edit stops the run (the stomp guard) |
| Scaffolded once ("yours") | a birth record in `.forge/scaffolded/` | written once, never again; deleting it sticks |
| The project's | nothing — forge never wrote it, or you took it | never written |
A hand-edit of a generated file aborts regeneration until you move the change
to an extension point or take the one-way door, `forge project disown <path>
--reason "…"`. Deleting a scaffold sticks (`.forge/scaffolded/` records the
birth); `forge project rescaffold <path>` brings one back. A scaffold the
project must never have — even one whose birth breaks the generate it is born
in, which rolls it back with its record — is declined with `--absent`, a
decline a failed generate keeps.
Four switches move a path into the last row. Each is a declaration in the
repository, so it holds in every clone and for every agent.
| You want | Do | Scope |
|---|---|---|
| Keep a generated file and edit it | `forge project disown <path> --reason "…"` | one file, after forge wrote it |
| Never have a scaffold at all | `forge project disown <path> --absent --reason "…"` | one file, before it is born |
| Keep forge out of a whole area | `scaffold.exclude` in forge.yaml | globs |
| Stop a whole forge piece | `features: {<name>: false}` (`forge project features` lists them) | a feature |
## scaffold.exclude — areas forge never writes
For a team adopting forge in a repository that already has its own frontend,
deploy workflow or docs:
```yaml
scaffold:
exclude:
- frontends/web/ # a trailing / is the whole directory
- .github/workflows/deploy.yml
- docs/** # ** is any depth; patterns are anchored at the project root
```
- `forge generate`, every `forge scaffold`, `forge project upgrade` (including
`--force`) and `forge project rescaffold` leave a matching path exactly as it
is: a file there is untouched, an absent one is never created, and nothing
there is deleted by the stale-file sweep.
- Each run reports what it declined, once per path, in its normal output:
`↷ frontends/web/src/hooks/item-hooks.ts skipped (scaffold.exclude: frontends/web/**)`
(five per glob, then a count; `-v` lists them all).
- It is enforced, not advisory. Every run that holds the generate lock
captures the excluded files first and puts back anything it changed,
created or deleted there before it exits — including writes by an external
tool. Paths a `generate.hooks` entry declares in `writes:` are the project's
own output and exempt.
- Nothing it undoes is lost: the guard cannot tell forge's write from yours or
another agent's made while the run held the lock, so it never deletes or
overwrites. A created or changed file is moved (one rename) under
`.forge/exclude-guard/<run>/`, named in the output, and a pre-run version is
written back only into a free path: a file saved there again meanwhile is
left as it is and reported.
- `.git/`, `.forge/`, `node_modules/` and `.next/` are outside the guarantee:
the guard never descends them (it neither captures nor undoes anything
there). An entry naming a path inside one fails the load; exclude the source
tree around it instead.
- A bad glob (`/abs`, `../x`, `a**`) fails the forge.yaml load, naming the entry.
- Unlike a disowned file, deleting an excluded one does not hand it back: the
glob, not the file, carries the decision. Remove the glob to let forge write
there again.
- `forge project scaffolded` lists the globs, and marks ledger entries they
cover `EXCLUDED`.
### What cannot be excluded on its own
Generated code that other generated code imports is refused, with the
dependent named, rather than left to rot out of step:
| Excluding | Fails because | Do instead |
|---|---|---|
| `gen/**` | every handler, the generated mounts and the hooks import the stubs | `features: {codegen: false}` |
| `<fe>/src/gen/` without `<fe>/src/hooks/` | the generated hooks import the stubs | exclude both, or the whole frontend `<fe>/` |
| one `*_gen.go` whose package has another, un-excluded `*_gen.go` | the package is generated together | exclude the package directory |
| an absent `*_gen.go` beside hand-written code | nothing would create what that code calls | exclude the package, or write the file |
| the ORM's generated files | the stores are generated against them | `//forge:no-orm` in the ORM package |
An excluded generated file that already exists, in a package nothing else of
which is regenerated, is simply the project's to maintain — like a disowned one.
## Orphans — what a feature pinned off leaves behind
Pinning a feature off stops forge writing its outputs; it does not delete what
forge wrote before. A full `forge generate` lists those orphans:
```
🗂 3 orphaned file(s) — written by an earlier run; no step writes them while features.observability is pinned off in forge.yaml:
- deploy/observability/dashboards/api.json
- deploy/observability/dashboards/db.json (edited — prune keeps it)
- deploy/observability/alerts/api.yaml
Remove the 2 unmodified one(s): forge project prune --orphans (--dry-run to preview)
```
`forge project prune --orphans [--dry-run]` deletes only files whose bytes are
still exactly what forge rendered — the embedded `forge:hash` marker (or the
certificate under `.forge/hashes/`) must still verify. An edited, excluded or
disowned file is listed and kept, whatever the flags. The list lives in
`.forge/orphans.json` (per checkout, not committed) with the forge.yaml it was
computed against; prune refuses a list made against a different forge.yaml, so
run `forge generate` first after switching a feature back on.
Scaffold-once files ("yours") are never orphans: they were the project's from
birth.