3. Patch Engine
Forge patches are structured bulk operations stored as markdown notes.
A patch contains a fenced YAML block describing the operations Forge should apply.
Before making changes, Forge:
- dry-runs the patch
- previews the changes
- shows a confirmation modal
- applies changes only after confirmation
This keeps patch workflows reviewable and safer than large manual edits.
Current patch note:
A-I/Forge/Engine/Patches/vault-patch.md
Patch Note Structure
A Forge patch is a normal markdown note.
Forge only reads the fenced YAML block.
Everything else in the note exists for human explanation and operational context.
Example:
# Vault Patch
```yaml
meta:
description: Normalize project notes
schema_version: "1.0"
operations:
- op: normalize_tags
target_pattern: "Projects/**/*.md"
```
This makes patches:
- reviewable
- editable
- searchable
- syncable
- auditable
inside the vault itself.
Targeting Files
Patch operations can target:
| Key | Use |
|---|---|
target | One exact file path |
target_pattern | Multiple files using a glob-like pattern |
Example:
target_pattern: "Projects/**/*.md"
If no files match, Forge reports the operation as an error.
Scoped Targets
Any patch operation can add scope to narrow matched files before the operation runs.
Example:
- op: add_tag
target_pattern: "Work/**/*.md"
scope:
updated_since: 2026-06-01
missing_tag: context/work
tag: context/work
This operation only applies to matched files whose frontmatter updated date is on or after the scoped date and which do not already have the tag.
Supported scope keys:
| Key | Meaning |
|---|---|
updated_since | Require frontmatter updated on or after this date |
updated_before | Require frontmatter updated on or before this date |
created_since | Require frontmatter created on or after this date |
created_before | Require frontmatter created on or before this date |
updated_field | Override the frontmatter field used by updated_since |
file_modified_since | Require filesystem modified time on or after this date |
file_modified_before | Require filesystem modified time on or before this date |
file_created_since | Require filesystem created time on or after this date |
file_created_before | Require filesystem created time on or before this date |
field_equals | Require frontmatter fields to match values |
field_not_equals | Require frontmatter fields not to match values |
field_present | Require frontmatter fields to be present and non-empty |
field_missing | Require frontmatter fields to be missing or empty |
has_tag | Require tags to be present |
missing_tag | Require tags to be absent |
path_in | Require the path to match one of these exact paths or glob patterns |
path_not_in | Exclude exact paths or glob patterns |
type_in | Shorthand for frontmatter type matching one of these values |
status_in | Shorthand for frontmatter status matching one of these values |
limit | Apply only to the first N files that pass scope |
When multiple scope keys are set, all must match.
Date-only values use local time and are inclusive.
Examples:
scope:
updated_since: 2026-06-01
updated_before: 2026-07-01
type_in:
- note
- project
field_equals:
status: active
field_missing:
- archived
has_tag: work
missing_tag: context/work
path_not_in:
- "Work/Archive/**"
limit: 25
Supported Operations
| Operation | Required Keys | What It Does |
|---|---|---|
set_field | target/target_pattern, field, value or value_from | Adds or updates a frontmatter field |
remove_field | target/target_pattern, field | Removes a frontmatter field |
add_tag | target/target_pattern, tag | Adds a tag if missing |
remove_tag | target/target_pattern, tag | Removes a tag if present |
replace_tag | target/target_pattern, old_tag, new_tag | Replaces one tag with another |
normalize_tags | target/target_pattern | Sorts and deduplicates tags |
compute_field | target/target_pattern, field, strategy | Computes values from metadata or activity |
sort_frontmatter | target/target_pattern | Reorders frontmatter consistently |
move_note | target/target_pattern, source_root, destination_folder | Moves notes while preserving relative paths |
Patch operations are intentionally explicit.
Forge favors predictable behavior over hidden automation.
set_field Examples
Literal Values
Example:
- op: set_field
target: "Notes/Home.md"
field: status
value: active
This writes:
status: active
into the note frontmatter.
Derived Values
Fields can also be generated dynamically from file metadata.
Example:
- op: set_field
target_pattern: "Projects/**/*.md"
field: domain
value_from: path
path_segment_index: 0
lowercase: true
This can derive metadata automatically from vault structure.
Useful for:
- domains
- project groups
- ownership
- folder-based organization
Supported value_from Sources
| Value | Result |
|---|---|
filename | Example Note.md |
basename | Example Note |
folder | Immediate parent folder |
parent_folder | Parent of the immediate parent folder |
path | Path segment using path_segment_index |
Optional transforms include:
trim_prefixtrim_suffixlowercaseuppercase
Conditional Operations
set_field supports:
whenonly_if_missing
Example:
- op: set_field
target_pattern: "Projects/**/*.md"
field: status
value: active
only_if_missing: true
when:
field: type
equals: project
This operation only applies when:
type: project
already exists.
Conditional logic helps patches remain safer and more targeted.
Compute Strategies
compute_field supports several built-in strategies.
| Strategy | Options | Meaning |
|---|---|---|
file_created_time | format | Writes file created date |
file_modified_time | format | Writes file modified date |
recent_activity | days, value_if_true, skip_if | Writes values based on recent activity |
Date formatting currently uses:
yyyy-MM-dd
Moving Notes
move_note moves notes while preserving their structure below a source root.
Example use cases:
- reorganizing projects
- splitting vault areas
- restructuring archives
- moving operational systems
Optional keys:
| Key | Meaning |
|---|---|
frontmatter | Merge frontmatter before moving |
strip_frontmatter | Remove frontmatter before moving |
Do not combine:
frontmatterstrip_frontmatter
in the same operation.
Dry Runs and Safety
Patch execution always begins with a dry run.
Forge previews:
- targeted files
- planned changes
- affected operations
- backup locations
before writing anything.
Backups, Reports, and Restore
Confirmed patch runs can generate:
- backups
- reports
- restore manifests
- applied patch copies
Typical locations:
A-I/Forge/Engine/Patches/Backups
A-I/Forge/Engine/Patches/Reports
A-I/Forge/Engine/Patches/Applied
Use:
Forge: Restore Patch Run
to restore files from a previous manifest.
Recommended Patch Workflow
A safe patch workflow usually looks like this:
- Run Vault Lint
- Review findings
- Build a small patch
- Dry-run the patch
- Review changes
- Apply the patch
- Re-run lint
Small patches are usually easier to review and safer to undo.
Why Patches Matter
Patches make vault maintenance repeatable.
Instead of manually editing hundreds of notes, you can:
- standardize metadata
- migrate structures
- normalize tags
- repair inconsistencies
- reorganize folders
- update workflows
using reviewable operational notes.
This becomes especially useful in:
- long-lived vaults
- shared systems
- large project repositories
- research systems
- evolving templates
