intent

README

intent Package

Intent attribution and resolution utilities for mapping pull requests and issues to labelled intent records.

Overview

The intent package resolves the intent behind a pull request or issue by inspecting labels, closing issues, and explicit metadata. It produces IntentRecord values that classify attribution status and source, allowing downstream consumers to route work items or report on coverage.

Resolution is performed by a Resolver, which holds a label matcher function and a version string. The resolver applies a priority chain:

1. Explicit intent metadata (PullRequestData.ExplicitIntent) — used as-is.
2. A single closing issue — resolved from the issue's labels.
3. PR labels — used as an artifact fallback when no closing issues are present.
4. No supported sources — returns an AttributionUnlinked record.

Public API

Types

Type	Kind	Description
AttributionStatus	string	Classifies the outcome of intent attribution
AttributionSource	string	Identifies the data source used for attribution
IntentRecord	struct	Holds the attribution result for a pull request or issue
RootReference	struct	Represents a referenced issue or artifact root (node ID, type, URL, labels)
PullRequestData	struct	Input data for pull request resolution (node ID, URL, labels, explicit intent, closing issues)
Resolver	struct	Stateless resolver that maps labels to intent records

AttributionStatus constants

Constant	Value	Description
AttributionMapped	"mapped"	Labels matched a known intent category
AttributionUnmapped	"unmapped"	Labels were present but matched no category
AttributionUnlinked	"unlinked"	No supported intent source was found
AttributionAmbiguous	"ambiguous"	Multiple competing sources were found
AttributionSuggested	"suggested"	Attribution was inferred by suggestion (not confirmed)

AttributionSource constants

Constant	Value	Description
SourceExplicitMetadata	"explicit_metadata"	Explicitly provided intent metadata
SourceClosingIssue	"closing_issue"	Derived from a closing issue
SourceParentIssue	"parent_issue"	Derived from a parent issue
SourceReferencedIssue	"referenced_issue"	Derived from a referenced issue
SourceProject	"project"	Derived from a project assignment
SourceMilestone	"milestone"	Derived from a milestone assignment
SourceIssueLabels	"issue_labels"	Derived from labels on an issue
SourceArtifactLabels	"artifact_labels"	Derived from labels on the artifact (pull request)
SourceSuggestion	"suggestion"	Derived from a suggestion
SourceNone	"none"	No source was used

Resolver methods

Method	Signature	Description
ResolvePullRequest	func (r Resolver) ResolvePullRequest(pr PullRequestData) IntentRecord	Resolves intent for a pull request using explicit intent, closing issues, or PR labels
ResolveIssue	func (r Resolver) ResolveIssue(nodeID, url string, labels []string) IntentRecord	Resolves intent for an issue using its labels

Usage Examples

resolver := intent.Resolver{
    ResolverVersion: "v1",
    MatchLabels: func(labels []string) []string {
        for _, l := range labels {
            if l == "security" {
                return []string{l}
            }
        }
        return nil
    },
}

record := resolver.ResolvePullRequest(intent.PullRequestData{
    NodeID: "PR_kwDOAAABCD4",
    URL:    "https://github.com/owner/repo/pull/42",
    Labels: []string{"security"},
})

fmt.Println(record.Status) // "mapped"
fmt.Println(record.Source) // "artifact_labels"

Resolving an issue

record := resolver.ResolveIssue(
    "I_kwDOAAABCQ4",
    "https://github.com/owner/repo/issues/1",
    []string{"security"},
)

fmt.Println(record.Status) // "mapped"
fmt.Println(record.Source) // "issue_labels"

Dependencies

Internal:

• github.com/github/gh-aw/pkg/logger — debug logging for resolver and policy evaluation

External:

• None beyond the Go standard library (slices).

Thread Safety

Resolver holds no mutable state and is safe for concurrent use. IntentRecord values are returned by value and do not share mutable state with the caller.

---

This specification is automatically maintained by the spec-extractor workflow.

Documentation

Index

• type AttributionSource
• type AttributionStatus
• type ExecutionPolicy
• type IntentRecord
• type PolicyCompiler
• type PolicyCondition
• type PolicyRule
• type PullRequestData
• type RepositoryContext
• type Resolver
  • func (r Resolver) ResolveIssue(nodeID, url string, labels []string) IntentRecord
  • func (r Resolver) ResolvePullRequest(pr PullRequestData) IntentRecord
• type RootReference

Types

type AttributionSource

type AttributionSource string

const (
	SourceExplicitMetadata AttributionSource = "explicit_metadata"
	SourceClosingIssue     AttributionSource = "closing_issue"
	SourceParentIssue      AttributionSource = "parent_issue"
	SourceReferencedIssue  AttributionSource = "referenced_issue"
	SourceProject          AttributionSource = "project"
	SourceMilestone        AttributionSource = "milestone"
	SourceIssueLabels      AttributionSource = "issue_labels"
	SourceArtifactLabels   AttributionSource = "artifact_labels"
	SourceSuggestion       AttributionSource = "suggestion"
	SourceNone             AttributionSource = "none"
)

type AttributionStatus

type AttributionStatus string

const (
	AttributionMapped    AttributionStatus = "mapped"
	AttributionUnmapped  AttributionStatus = "unmapped"
	AttributionUnlinked  AttributionStatus = "unlinked"
	AttributionAmbiguous AttributionStatus = "ambiguous"
	AttributionSuggested AttributionStatus = "suggested"
)

type ExecutionPolicy

type ExecutionPolicy struct {
	Autonomy string `json:"autonomy"`

	// AllowedTools controls which tools the agent may call.
	// nil means unrestricted; []string{} (non-nil empty) means deny-all; non-empty
	// means restricted to the listed tools. JSON omitempty cannot preserve the
	// nil-vs-empty distinction; callers must check AllowedTools != nil at runtime.
	AllowedTools []string `json:"allowed_tools,omitempty"`
	DeniedTools  []string `json:"denied_tools,omitempty"`

	WriteScope string `json:"write_scope"`

	RequiredChecks []string `json:"required_checks,omitempty"`

	HumanApprovalRequired bool `json:"human_approval_required"`

	// AutoMergeAllowed uses a pointer so that an unset rule fragment (nil) is
	// distinguishable from an explicit denial (false). The merge logic only applies
	// the AND (more-restrictive) step when at least one side has an explicit value.
	// nil means the rule did not express a preference; false is an explicit denial;
	// true is an explicit grant.
	AutoMergeAllowed *bool `json:"auto_merge_allowed,omitempty"`

	MaxAttempts int `json:"max_attempts"`

	RuleIDs []string `json:"rule_ids,omitempty"`
}

ExecutionPolicy governs what an agent may do for a given intent.

WARNING: PolicyCompiler is advisory only. All fields except Autonomy are compiled and recorded for audit but are NOT yet wired into runtime enforcement. Do not rely on this policy to gate actual tool calls or merge operations until Authorizer.AuthorizeTool is implemented and integrated into the execution path.

type IntentRecord

type IntentRecord struct {
	Status AttributionStatus `json:"status"`
	Source AttributionSource `json:"source"`

	RootNodeID string `json:"root_node_id,omitempty"`
	RootType   string `json:"root_type,omitempty"`
	RootURL    string `json:"root_url,omitempty"`

	Labels []string `json:"labels,omitempty"`

	Rule            string `json:"rule,omitempty"`
	ResolverVersion string `json:"resolver_version,omitempty"`
}

type PolicyCompiler

type PolicyCompiler struct {
	Rules []PolicyRule
}

PolicyCompiler holds policy rules for callers that still exchange policy compiler configuration data.

WARNING: the compiled policy is advisory only. Runtime enforcement is not yet wired to the orchestrator — see the intent-attribution-agent-governance spec for the required follow-up before treating compiled policies as a security gate.

type PolicyCondition

type PolicyCondition struct {
	Domain   string `json:"domain,omitempty"`
	Priority string `json:"priority,omitempty"`
	Risk     string `json:"risk,omitempty"`
	Org      string `json:"org,omitempty"`
}

PolicyCondition describes when a rule applies.

type PolicyRule

type PolicyRule struct {
	ID    string          `json:"id"`
	Scope string          `json:"scope,omitempty"` // "organization", "repository", "intent", or "workflow"
	When  PolicyCondition `json:"when"`
	Set   ExecutionPolicy `json:"set"`
}

PolicyRule pairs a match condition with a policy fragment to apply.

type PullRequestData

type PullRequestData struct {
	NodeID         string
	URL            string
	Labels         []string
	ExplicitIntent *IntentRecord
	ClosingIssues  []RootReference
}

type RepositoryContext

type RepositoryContext struct {
	Owner      string `json:"owner,omitempty"`
	Name       string `json:"name,omitempty"`
	Visibility string `json:"visibility,omitempty"` // "public" or "private"
	Org        string `json:"org,omitempty"`
}

RepositoryContext carries repository-level context used when matching policy rules.

type Resolver

type Resolver struct {
	ResolverVersion string
	MatchLabels     func(labels []string) []string
}

func (Resolver) ResolveIssue

func (r Resolver) ResolveIssue(nodeID, url string, labels []string) IntentRecord

func (Resolver) ResolvePullRequest

func (r Resolver) ResolvePullRequest(pr PullRequestData) IntentRecord

type RootReference

type RootReference struct {
	NodeID string
	Type   string
	URL    string
	Labels []string
}