project

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 20, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package project ties config, catalog, render, and manifest together to sync rendered files into a project and check them for drift.

Index

Constants

View Source 
const BridgeTrancheComplete = true

BridgeTrancheComplete blocks publication while the two-plan current-state bridge tranche is only partially implemented. Plans 1 and 2 have both landed (migration readiness, attestation, and ordinary-command refusal are all present), so the tranche is complete and publication is unblocked.

View Source 
const Version = "0.18.0"

Version is the awf release version - the single version authority (ADR-0049): gate comparisons, the lock stamp, the bootstrap pin, and the CLI output all read this const.

Variables

This section is empty.

Functions

func CatalogNames 

func CatalogNames(cat *catalog.Catalog, singular string) ([]string, bool)

CatalogNames returns the catalog pool for a singular CLI kind; ok is false for a kind with no catalog pool (domains).

func CollisionsAt added in v0.6.0 

func CollisionsAt(root string, planned []string) ([]string, error)

CollisionsAt filters planned project-relative paths to those that already exist under root and are not recorded in root's lock (not awf-managed). Split from InitCollisions so init's pre-prompt probe can plan outputs in a throwaway scaffold and test them against the real root; the ADR-0016 collision semantics are unchanged.

func DeriveDocTitle added in v0.15.0 

func DeriveDocTitle(name string) string

DeriveDocTitle turns a local doc name into a display title: the last path segment, hyphens to spaces, each word capitalized, empty words (from a trailing or double hyphen) dropped. "guides/release-steps" → "Release Steps". awf new doc seeds the sidecar with it, and synthesis falls back to it when the sidecar omits data.title.

func EnabledNames 

func EnabledNames(c *config.Config, singular string) ([]string, bool)

EnabledNames returns the config enable array for a singular CLI kind.

func HookNames added in v0.6.0 

func HookNames() []string

HookNames returns the git-hook payload names the hooks singleton renders (ADR-0048), for CLI surfaces that enumerate them (the KnownTargets pattern).

func Kinds 

func Kinds() []string

Kinds returns the singular CLI kind tokens in display order.

func KnownTargets added in v0.4.0 

func KnownTargets() []string

KnownTargets returns the known adapter names in sorted order. The bespoke `awf {enable,disable,list} target` path validates against this set (inv: target-cli). invariant: target-cli

func NeededVars added in v0.13.0 

func NeededVars(trim *config.CatalogTrim) (map[string]bool, error)

NeededVars returns the var names referenced by the templates the scaffolded enabled set will render: the enable arrays scaffoldSelection derives, the always-on singletons (agents-doc + plain), and the default-enabled hook payloads. Init's interactive path prompts only for these (ADR-0086 Decision 6); the scaffold still seeds the full catalog union as empty keys (ADR-0022 unchanged), and an explicit --set/answers value is honored regardless.

func NormalizeContextPaths added in v0.18.0 

func NormalizeContextPaths(paths []string) []string

NormalizeContextPaths slash-normalizes, path-cleans, de-duplicates, and sorts the queried paths so the assembly is deterministic.

func PluralKind 

func PluralKind(singular string) (string, bool)

PluralKind maps a singular CLI kind token to its config enable-array key.

func PotentialVarConsumers added in v0.14.0 

func PotentialVarConsumers() (map[string][]string, error)

PotentialVarConsumers inverts the full catalog's raw template sources into var → sorted consumer labels: the dormant-hint side of the consumption graph (ADR-0088). Raw-source scanning is sound because no partial references .vars - guarded by a test beside the reference's goldens.

func ScaffoldConfig 

func ScaffoldConfig(prefix string, vars map[string]string, trim *config.CatalogTrim, scopes []string) ([]byte, []string, error)

ScaffoldConfig generates the bytes of a .awf/config.yaml that enables the workflow-core skills and docs (ADR-0022) and every agent in the embedded catalog (as flat name arrays), and pre-populates the vars block with the union of all {{ .vars.X }} names referenced by every catalog template. Each var is seeded with an empty string so that strict render (missingkey=zero + <no value> check) does not fail on sync, and so a later `awf enable` of an opt-in skill renders cleanly. It also seeds the self-pinning bootstrap (ADR-0040) and the git-hook payloads (ADR-0048) enabled by default, and writes a resolved commit-scope list to audit.allowedScopes (ADR-0051). The second return value lists the closure additions beyond a trim's explicit selection (kind-prefixed, e.g. "skill reviewing-plan-resync"), empty for the untrimmed default.

func ScaffoldVarRefs added in v0.14.0 

func ScaffoldVarRefs(kind string) ([]string, error)

ScaffoldVarRefs returns the vars referenced by the base template a new local artifact of kind ("skill"/"agent") renders from - `awf new`'s seeding surface (ADR-0087 Decision 4). Parts are raw (ADR-0034), so the base template is a local artifact's only var channel; today both bases are varless and this returns empty, but a future base gaining a var reference is seeded correct by construction.

func Uninstall 

func Uninstall(root string) (int, error)

Uninstall removes awf's generated footprint from root: every file recorded in the lock, the directories left empty by their removal, and the now-stale lock itself. It leaves the authored .awf/ config in place and returns the count of files removed. It is a free function (not a *Project method) so a broken config.yaml does not block uninstall - only the lock and root are needed. touches-invariant: uninstall-removes-lock-entries - lock-tracked file removal; proof in install_test.go

Types

type ADRRef added in v0.16.0 

type ADRRef struct {
	Number string `json:"number"`
	Title  string `json:"title"`
	Status string `json:"status"`
	Path   string `json:"path"`
}

ADRRef is an ADR surfaced in a context tier. Title is the human title with the "ADR-NNNN: " prefix stripped (Number carries it). The per-ADR declared-slug echo was dropped by ADR-0104 (the flat ## Invariants block carries the path-present slugs; the per-ADR list only duplicated it).

type AgentDialect added in v0.18.0 

type AgentDialect string

AgentDialect names the target-native encoding for rendered agents. 

const (
	MarkdownAgentDialect AgentDialect = "markdown"
	TOMLAgentDialect     AgentDialect = "toml"
	PlainAgentDialect    AgentDialect = "plain"
)

type Backup added in v0.3.0 

type Backup struct {
	Path  string // project-relative file that was overwritten
	Bak   string // project-relative backup copy (.awf-bak[.N])
	Index bool   // the file is the generated ADR/domain index (ownership-takeover note)
}

Backup records a foreign file preserved before sync overwrote its path.

type BridgeOutput added in v0.18.0 

type BridgeOutput struct {
	Path             string
	Bytes            []byte
	Mode             uint32
	Policy           OutputPolicy
	DependencyHashes []string
	Reservation      bool
	Deletion         bool
}

BridgeOutput is the migration-safe read-only projection of one output-plan node or legacy-output deletion. It exposes no writer capability.

type Capability added in v0.18.0 

type Capability string

Capability is an awf-owned template capability. It is deliberately closed: targets cannot inject arbitrary template data. 

const CapabilitySubagentTools Capability = "subagent-tools"

type Change added in v0.13.0 

type Change struct {
	Path  string
	Cause string
}

Change records a sync-written file whose rendered output differs from the prior lock's, with the cause the lock's hashes can attribute: "template" (the upstream template source moved), "config" (the project's effective inputs - vars, sidecar, parts - moved), "template+config" (both), "internal" (hashes unmoved: a non-hashed input such as the binary's version stamp), "regenerated" (a generated index, which carries no hashes to attribute), or "added" (no prior entry). The provenance triage signal for reviewing a large sync diff - upstream churn vs the project's own inputs.

type ContextResult added in v0.16.0 

type ContextResult struct {
	Paths      []string       `json:"paths"`
	Domains    []DomainRef    `json:"domains"`
	Invariants []InvariantRef `json:"invariants"`
	Governing  []ADRRef       `json:"governing"`  // Tier 1: invariants backed under the query
	Related    []ADRRef       `json:"related"`    // Tier 2: precise-tag or related: linked
	Pitfalls   []PitfallRef   `json:"pitfalls"`   // Tier 2: precise-tag match
	Plans      []PlanRef      `json:"plans"`      // linked to a Tier-1/Tier-2 ADR
	Background int            `json:"background"` // Tier 3: collapsed domain-ADR count
	Unowned    []string       `json:"unowned"`
}

ContextResult is the read-only context awf holds for a set of repo-relative paths: their owning domains (each with the rendered current-state pointer), the invariant slugs backed under those paths, the ADRs related via the owning domains, and any queried path matching no configured domain.

type DomainRef added in v0.16.0 

type DomainRef struct {
	Name         string `json:"name"`
	CurrentState string `json:"currentState"`
}

DomainRef is an owning domain and its rendered current-state doc path, derived by convention (never a sidecar field - ADR-0086).

type InvariantRef added in v0.18.0 

type InvariantRef struct {
	Slug    string   `json:"slug"`
	Class   string   `json:"class,omitempty"`
	Verify  string   `json:"verify,omitempty"`
	Touches []string `json:"touches,omitempty"`
}

InvariantRef is an invariant slug surfaced as present under a queried path (ADR-0106). Class labels a governing (declared) invariant backed or unbacked; it is empty for a slug present under the path but declared by no Implemented ADR. Verify carries an unbacked governing invariant's `Verify:` guidance; Touches carries the site notes from any `touches-invariant:` marker under the query. Both renderings derive from this one value (context-output-parity).

type Layout 

type Layout struct {
	DocsDir    string
	ADRDir     string
	ActiveMd   string
	PlansDir   string
	Docs       map[string]string // name -> output path; present iff enabled (inv: layout-docs-enabled-only)
	DomainsDir string
}

Layout is the fixed, awf-given docs layout derived from cfg.DocsDir, in typed form for Go consumers. These paths are not configurable through vars. templateMap projects it into the .layout template namespace (templates read a map, not unexported struct fields) and into the per-file ConfigHash. The mandatory-singleton paths are not struct fields: they derive from the catalog doc collection in templateMap (ADR-0061).

type OutputNode added in v0.18.0 

type OutputNode struct {
	Path                string
	Recipe              OutputRecipe
	Policy              OutputPolicy
	Declarers           []string
	DeclarerProjections []string
	DependsOn           []string
	Reservation         bool
	// contains filtered or unexported fields
}

OutputNode is one path in the deterministic internal output plan. A node is either a write or a reservation; reservations protect local artifacts but are never written or entered in the lock manifest.

type OutputPlan added in v0.18.0 

type OutputPlan struct{ Nodes []OutputNode }

OutputPlan is the single desired-output authority consumed by rendering, sync, manifest/prune, checks, and planned-output reporting.

type OutputPolicy added in v0.18.0 

type OutputPolicy struct {
	ValidateFrontmatter bool
	ScanReferences      bool
	ScanSkillReferences bool
	Regenerate          bool
	LocalValidation     bool
}

OutputPolicy declares lifecycle behavior for a planned path. It is data on the node, not an inference made by sync or check from a template name or suffix.

type OutputRecipe added in v0.18.0 

type OutputRecipe struct {
	TemplateID, TemplateHash, ConfigHash string
	Policy                               OutputPolicy
	Encoder                              AgentDialect
	Provenance                           string
}

OutputRecipe is the normalized, output-affecting declaration used for collision diagnostics and configuration hashes. Target identity is kept on OutputNode declarers rather than here, so compatible shared outputs coalesce.

type PitfallRef added in v0.18.0 

type PitfallRef struct {
	Title string   `json:"title"`
	Tags  []string `json:"tags"`
	Path  string   `json:"path"`
}

PitfallRef is a pitfall surfaced because it shares a precise tag with the query (ADR-0104 Tier 2). Path is the docsDir-rooted pitfalls doc; Tags are the entry's own tags.

type PlanOp added in v0.12.0 

type PlanOp struct {
	Node       catalog.Node
	Enable     bool
	RequiredBy string
}

PlanOp is one enable-array change in a resolver plan (ADR-0081 Decision 2). RequiredBy carries provenance: the artifact demanding the op ("" for the node the user named).

type PlanRef added in v0.18.0 

type PlanRef struct {
	Filename string `json:"filename"`
	Path     string `json:"path"`
	Status   string `json:"status"`
	ADRs     []int  `json:"adrs"`
}

PlanRef is a plan surfaced because its adrs: links an ADR reported for the query. Path is docsDir-rooted; ADRs are the linked ADR numbers.

type Project 

type Project struct {
	Root    string
	Cfg     *config.Config
	Cat     *catalog.Catalog
	Targets []Target
	// contains filtered or unexported fields
}

func Open 

func Open(root string) (*Project, error)

func (*Project) AdvisoryNotes added in v0.10.0 

func (p *Project) AdvisoryNotes() ([]string, error)

AdvisoryNotes returns the non-failing render advisories in print order - the ADR-0045 unset-var notes, the ADR-0070 stub notes, then the ADR-0083 part- marker notes - computed from one RenderAll pass plus the domain-doc generation, which renders outside it.

func (*Project) Audit 

func (p *Project) Audit(base, head string) ([]audit.Finding, int, error)

Audit runs the process-conformance audit (ADR-0017) over the caller-supplied commit range. No config key supplies a base: the range is always explicit (ADR-0127 Decision 3).

func (*Project) BackupFile 

func (p *Project) BackupFile(rel string) (string, error)

BackupFile copies a colliding project-relative file to a free <path>.awf-bak[.N] sibling (never clobbering a prior backup) and returns the backup's project-relative path. touches-invariant: init-force-backs-up - forced-collision backup copy; proof in run_test.go

func (*Project) BridgeProjection added in v0.18.0 

func (p *Project) BridgeProjection(terminal bool) ([]BridgeOutput, error)

BridgeProjection returns the ordinary prepared output view, or the terminal view that reserves deletion of legacy ADR indexes without introducing their current-state replacements.

func (*Project) Check 

func (p *Project) Check() ([]manifest.Drift, error)

func (*Project) CheckInvariants 

func (p *Project) CheckInvariants() ([]invariants.Finding, []invariants.Note, error)

CheckInvariants reports Implemented-ADR invariant backing findings (per the ADR-0105 two-marker model and the project's configured invariant sources) under the project root, alongside the non-failing advisory notes.

func (*Project) ConfigReferenceModel added in v0.14.0 

func (p *Project) ConfigReferenceModel() (map[string]any, error)

ConfigReferenceModel computes the reference's four collections (configKeys, varEntries, sidecarFields, dataKeys) with live project state - the `awf config` command's data source, sharing the doc's builder.

func (*Project) ContextFor added in v0.16.0 

func (p *Project) ContextFor(paths []string) (ContextResult, error)

ContextFor assembles the read-only context for paths. It reads only committed state (domain sidecars, ADR files, source markers) and writes nothing.

func (*Project) Corpus added in v0.18.0 

func (p *Project) Corpus() (adr.Corpus, error)

Corpus returns the project's parsed ADR corpus, loading it on first use within the current invocation and reusing it for the rest of that invocation (ADR-0130 item 1). Threading one view is what collapses the eight-or-so per-check parses a single awf check used to perform.

The cache is per-INVOCATION, not per-Project: every public operation that reads ADRs calls beginInvocation first. A Project outlives a single call, and Check's whole contract is to compare rendered output against the decisions directory as it is on disk right now - so a corpus held across calls would make a Check following a Sync miss an ADR written in between, silently blinding the drift oracle rather than merely serving a stale read.

func (*Project) InitCollisions 

func (p *Project) InitCollisions() ([]string, error)

InitCollisions returns planned output paths that already exist on disk and are not recorded in the prior lock (i.e. not awf-managed). An awf-managed path that already exists is not a collision - re-init is idempotent.

func (*Project) NewADR added in v0.6.0 

func (p *Project) NewADR(title string) (string, error)

NewADR scaffolds a new ADR file under the project's decisions dir: the next sequential number, the rendered template with its title/date filled in and marker comments stripped, refusing to overwrite an existing file. Mirrors the CheckInvariants/Audit pattern - cmd/awf reaches this only through this exported method, never internal/project.Layout directly.

func (*Project) NewPlan added in v0.18.0 

func (p *Project) NewPlan(title string) (string, error)

NewPlan scaffolds a new plan under docsDir/plans from the rendered plans template. Mirrors NewADR minus sequential numbering (ADR-0098).

func (*Project) OutputPlan added in v0.18.0 

func (p *Project) OutputPlan() (*OutputPlan, error)

OutputPlan compiles all output producers. Generated nodes are constructed in dependency order; config reference observes ordinary/domain metadata but is deliberately excluded from its own input.

func (*Project) PlannedOutputs 

func (p *Project) PlannedOutputs() ([]string, error)

PlannedOutputs returns plan write paths, excluding local reservations.

func (*Project) QueryTopic added in v0.18.0 

func (p *Project) QueryTopic(selector string, opts topic.QueryOptions) (topic.QueryResult, error)

QueryTopic assembles one read-only active topic or claim projection. The invocation reset keeps the ADR and topic views coherent with the current working tree; the bridge migration can insert its lock refusal before the first Topics call without changing the query model.

func (*Project) RenderAll 

func (p *Project) RenderAll() ([]RenderedFile, error)

RenderAll renders only plan write nodes in deterministic path order.

func (*Project) ResolveDisable added in v0.16.0 

func (p *Project) ResolveDisable(kind, name string) []PlanOp

ResolveDisable plans disabling (kind, name): the node plus every enabled, non-local artifact that transitively requires it (reverse closure, fixed point over direct edges). Local-sidecar artifacts have no catalog edges demanded of them, mirroring the validator's skip. invariant: remove-refuses-dependents

func (*Project) ResolveEnable added in v0.16.0 

func (p *Project) ResolveEnable(kind, name string) []PlanOp

ResolveEnable plans enabling (kind, name): the node plus its missing forward closure. An already-enabled dependency is skipped along with its subtree - the open-time validation invariant guarantees enabled implies closed. invariant: add-applies-closure-plan

func (*Project) SyncReport added in v0.3.0 

func (p *Project) SyncReport() ([]Backup, []Change, []string, error)

SyncReport renders and writes the project, additionally backing up any foreign file (on disk but absent from the start-of-sync lock) before overwriting it, and returning those backups (ADR-0035) plus the per-file provenance of output that changed against the prior lock and the lock-relative paths of the files its prune actually removed (both path-sorted; a file whose output is byte-identical, and a first sync with no prior lock, report no change - a routine re-sync stays silent).

func (*Project) Topics added in v0.18.0 

func (p *Project) Topics() (topic.Corpus, error)

func (*Project) Uncovered added in v0.18.0 

func (p *Project) Uncovered(tracked, scanRoots []string) (UncoveredResult, error)

Uncovered assembles the domain-coverage report over the tracked paths. It writes nothing and reads only the domain sidecars. scanRoots restrict the report to tracked paths at or beneath them, matched on slash-separated segment boundaries (a directory subtree), not raw string prefixes; empty scanRoots scans everything. touches-invariant: uncovered-lists-unowned-unignored - unowned-path reporting; proof in context_test.go touches-invariant: uncovered-collapses-directories - fully-uncovered directory collapse; proof in context_test.go

type RenderedFile 

type RenderedFile struct {
	Path         string
	Content      string
	TemplateID   string
	TemplateHash string
	ConfigHash   string
	// RegenChecked excludes this file from the frozen-OutputHash compare; its
	// drift is checked by regeneration instead (ADR-0100). Set on the generated
	// indexes and on any file carrying an in-place-editable section.
	RegenChecked bool
	// Policy declares all lifecycle checks for this path. It replaces
	// template-name and filename inference at plan consumers.
	Policy OutputPolicy
	// Declarer identifies the producer requesting this output.
	Declarer           string
	DeclarerProjection string
	Encoder            AgentDialect
	Provenance         render.CommentStyle
	// contains filtered or unexported fields
}

type Target 

type Target struct {
	Name           string
	SkillDir       string // dir holding rendered skills, e.g. ".claude/skills"
	AgentDir       string // dir holding rendered agents, e.g. ".claude/agents"
	AgentSuffix    string // agent filename suffix, including its extension
	AgentDialect   AgentDialect
	BridgeFile     string // adapter bridge file at repo root, "" if none
	BridgeTemplate string
	// Capabilities is the closed capability declaration exposed through the
	// fixed targetTemplateData projection.
	Capabilities []Capability
	Outputs      []TargetOutput
}

Target places adapter (tool-specific) artifacts for one runtime. Neutral artifacts (AGENTS.md, docs, domains) are not target-scoped (ADR-0016).

func (Target) AgentPath 

func (t Target) AgentPath(name string) string

AgentPath is the output path for a rendered agent under this target.

func (Target) SkillPath 

func (t Target) SkillPath(prefix, name string) string

SkillPath is the output path for a rendered skill under this target.

type TargetOutput added in v0.18.0 

type TargetOutput struct {
	Path           string
	TemplateID     string
	Encoder        AgentDialect
	Provenance     render.CommentStyle
	Policy         OutputPolicy
	PolicyDeclared bool
}

TargetOutput declares a target-owned non-catalog output such as a project extension.

type UncoveredResult added in v0.18.0 

type UncoveredResult struct {
	ScanRoots []string `json:"scanRoots"`
	Entries   []string `json:"entries"`
}

UncoveredResult is the read-only domain-coverage report for a set of scan roots: the git-tracked paths matched by no configured domain glob, with a fully-uncovered directory collapsed to its topmost node (a trailing-slash entry). ScanRoots echoes the requested roots (empty = whole repository).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.