generate

Documentation

Overview

Package generate renders the one managed agent guidance region from canonical operation metadata. It owns no workflow semantics of its own: commands come from the operation registry, and everything else is one shared prose template.

Index

• Constants
• func Clean(root, name string) error
• func Destination(root, name string) (string, error)
• func Drift(root string) (bool, string, error)
• type Guidance
  • func Render() (Guidance, error)
• type Result
  • func Refresh(root string) (Result, error)

Constants

const GuidanceFile = "AGENTS.md"

GuidanceFile is the only managed generation target. It is an allowlist of one: cleanup and refresh refuse every other name rather than deleting by pattern.

Functions

func Clean

func Clean(root, name string) error

Clean removes one managed file, and only when the file is nothing but a managed region whose declared hash still identifies its bytes. A file holding user text, or one whose managed bytes were edited, is left untouched: cleanup deletes proven managed content, never a guess.

func Destination

func Destination(root, name string) (string, error)

Destination resolves one managed target inside the project. It refuses traversal, absolute names, and any symlink on the resolved path, so a generated file can never be written or removed outside the selected project.

func Drift

func Drift(root string) (bool, string, error)

Drift reports whether the installed managed region is the current one. It is the parity check that runs before refresh; its only repair is refresh.

Types

type Guidance

type Guidance struct {
	Version int
	Hash    string
	Body    string
}

Guidance is one rendered managed region. Hash identifies Body exactly, so a consumer can prove freshness without re-rendering and a hand edit is visible.

func Render

func Render() (Guidance, error)

Render projects the agent-visible registry through the shared prose template. It is deterministic: registry order, no clock, no environment, no network.

type Result

type Result struct {
	Path    string
	Version int
	Hash    string
	// Changed is false when the file already held exactly this managed region,
	// which makes refresh idempotent and safe to run from a parity check.
	Changed bool
}

Result reports one refresh outcome.

func Refresh

func Refresh(root string) (Result, error)

Refresh replaces exactly the managed region and preserves every surrounding byte. The write is atomic, so an interruption leaves the old complete region or the new one, never half of either.