rulesfs

type DirSource ¶

type DirSource struct {
	// Dir is the directory to scan. An empty or absent Dir yields no rules.
	Dir string
	// Label is an optional human-readable name for this source (e.g.
	// "project(.mecatl)", "user(xdg)"), surfaced in diagnostics (it prefixes
	// each Discovered entry's Detail). It does not affect discovery.
	Label string
	// Tier is the admission tier stamped onto every rule this source produces
	// (prompt.Rule.Origin on the port). ResolveSources sets it per conventional
	// location; a zero Tier defaults to prompt.RuleOriginUser (a
	// hand-constructed source is a personal location).
	Tier prompt.RuleOrigin
}

DirSource is the local-OS-filesystem implementation of RuleSource: it produces the rules laid out as <Dir>/<name>.md (flat files) under a single directory.

func (s DirSource) Rules(_ context.Context) ([]Discovered, []SkipError, error)

type Discovered ¶

type Discovered struct {
	Rule   Rule
	Detail string
}

Discovered is one discovered rule together with its adapter-private locator string. The PORT value object (prompt.Rule) carries no path/dir/root concept; Detail is the NON-PORT diagnostics channel a reviewer traces a rule back through — "<label>: <path>" for a filesystem source, "driver: <target>" for a remote driver. It never crosses the prompt.RulesSource port.

type FSSource ¶

type FSSource struct {
	// contains filtered or unexported fields
}

FSSource is the FILESYSTEM implementation of the prompt.RulesSource port: a snapshot of the rules discovered from the composed Source list (the conventional project + user locations). The port carries no path/dir/root concept; the locator business the composition layer's diagnostics still need is exposed as adapter-public NON-PORT methods (Discovered/Detail), mirroring the agentfs FSSource split.

SNAPSHOT SEMANTICS: discovery runs ONCE at construction (NewMultiSource over the given sources) and the rules are retained in memory, so ListRules is stable for the life of the source — the build-once trust-gate invariant (an untrusted workspace's project tier is gated at SOURCE CONSTRUCTION, in ResolveSources).

func (s *FSSource) Detail(name string) (string, bool)

func (s *FSSource) Discovered() []Discovered

func (s *FSSource) ListRules(_ context.Context) ([]prompt.Rule, error)

type MultiSource ¶

type MultiSource struct {
	// contains filtered or unexported fields
}

MultiSource composes an ORDERED list of Sources into one, with a defined precedence on name collisions and aggregated diagnostics.

PRECEDENCE (collision rule): EARLIER sources win. When two sources both produce a rule with the same effective name, the one from the earlier source is kept and the later one is SHADOWED — dropped, with a SkipError notice. Callers order the slice highest-precedence-first; ResolveSources builds it as project > user.

A fatal error from ANY source is returned immediately (with the diagnostics gathered so far). Output is sorted by name for deterministic, cache-stable ordering.

func NewMultiSource(sources ...RuleSource) MultiSource

func (m MultiSource) Rules(ctx context.Context) ([]Discovered, []SkipError, error)

type ResolveEnv ¶

type ResolveEnv struct {
	Getenv      func(string) string
	UserHomeDir func() (string, error)
}

ResolveEnv abstracts the process environment so a resolver is testable with a fake home / XDG, without touching the real one. The composition root binds OSEnv (the real os funcs); tests pass a fake.

trimmed to the fields this adapter uses; the root xdgconfig.ResolveEnv also carries ReadFile for permconfig/soul.

mirrors internal/adapter/xdgconfig.ResolveEnv EXACTLY (minus ReadFile) — keep byte-identical; carried because engine must not import the root module (fstools precedent, #269).

type ResolveOptions ¶

type ResolveOptions struct {
	// Conventional, when true, admits the built-in conventional project- and
	// user-level locations. Always true in production; the field exists so a
	// test can resolve a single lane (or none) in isolation.
	Conventional bool
	// Workspace is the session workspace root used to resolve the project-level
	// conventional paths. Only consulted when Conventional is true and non-empty.
	Workspace string
	// IncludeProjectTier, when true, admits the PROJECT-tier conventional locations
	// (<workspace>/.mecatl/rules, <workspace>/.claude/rules). The composition layer
	// sets it false when the workspace is UNTRUSTED (the Workspace-Trust fold) so
	// a cloned repo's project rules cannot steer the model before the operator
	// trusts it; the user-tier sources stay active regardless. It gates ONLY the
	// project tier. Mirrors agentfs.ResolveOptions.IncludeProjectTier.
	//
	// ZERO-VALUE NOTE: false by default; callers set it explicitly. Composition
	// uses the folded trust bool. Only Conventional==true makes the project tier
	// eligible.
	IncludeProjectTier bool
}

ResolveOptions configures the known-path resolver. There is NO explicit tier (issue #329 operator amendment: conventional discovery is the ONLY admission path, always-on in production). Conventional exists so tests can disable the lanes; the zero value resolves NOTHING.

type Rule ¶

type Rule = prompt.Rule

Rule is the pure value object for one rule, re-aliased from engine/prompt so the adapter and the port speak one type (the agentfs.AgentDef precedent).

type RuleSource ¶

type RuleSource interface {
	Rules(ctx context.Context) ([]Discovered, []SkipError, error)
}

RuleSource is the pluggable EXTENSIBILITY POINT for where rules come from. A Source produces a set of Discovered entries (the Rule value object + its adapter-private Detail) together with non-fatal diagnostics (SkipError), and a fatal error only for a genuine infrastructure fault that prevented the source from being consulted at all.

It is the verbatim shape of agentfs.AgentSource: the local-OS-filesystem layout (DirSource) is just ONE implementation; an embedded default set or a remote registry would satisfy the same interface and slot in via MultiSource without touching the consumer or the Rule value object.

Rules(ctx) returns:

• the discovered rules (deterministically ordered by the implementation),
• the non-fatal diagnostics (skipped/duplicate/truncated/shadowed entries),
• a non-nil error ONLY for a hard fault. An absent source (e.g. a missing directory) is "no rules", not an error.

func ResolveSources(opts ResolveOptions) []RuleSource

project: <workspace>/.mecatl/rules, <workspace>/.claude/rules   [highest]
  > user: $XDG_CONFIG_HOME/mecatl/rules (or ~/.config/mecatl/rules),
          ~/.claude/rules                                       [lowest]

type SkipError ¶

type SkipError struct {
	// Path is the <name>.md the problem was found at.
	Path string
	// Reason is a short, human-readable description of the problem.
	Reason string
	// Fatal reports whether the rule was DROPPED (true) or KEPT-but-ADJUSTED
	// (false, the zero value). See the type doc-comment.
	Fatal bool
}

SkipError records one diagnostic from discovery. It carries a structural two-way split via Fatal — NOT a string-matched one — so the composition root can word the log honestly instead of overloading "skipped":

• Fatal == true: the rule was DROPPED (excluded from the set). Causes: it could not be read, its frontmatter was malformed, a duplicate name within a directory, or it was SHADOWED by a higher-precedence source.
• Fatal == false (the zero value): the rule was KEPT but ADJUSTED — a non-fatal modification was applied (its body was truncated to the cap). The rule is still in the set.

Discovery keeps scanning rather than aborting and returns the collected diagnostics so the composition root can surface them. A SkipError is never returned as a Source's fatal error.

func (e SkipError) Error() string