Phase 3: JEV classification, rules table, editable categories (AUD-69)

Implements FR-3, FR-4, FR-5 and FR-14.

- internal/classify: TypeSafe System One (JEV) HTTP client with the confirmed
  request/response shape, retry with backoff on 429/529/5xx, a plain-text rule
  engine (first match wins, overrides only the named fields), and bounded
  orchestration with a per-run cap.
- internal/store: migration v3 adds an editable `categories` table (name =
  JEV Choice option and classifications key; rename cascades, remove reassigns)
  and seeds a starter rules version once. Classification persistence, coverage,
  and pending/all message queries.
- internal/server: POST /actions/classify and /actions/reclassify, plus the
  FR-14 category editor (GET /categories and add/rename/remove). The triage list
  now groups by the live category list and shows action + confidence.
- CLI: -classify and -classify-all for n8n.
- Docs: docs/phase3-classify.md with the confirmed JEV shape, a live read-only
  classification, and the DoD evidence.

DoD: all 100 stored messages have a non-null category, importance, and suggested
action (0 nulls); JEV picked a newly added/renamed category for 6 real messages
over HTTP. One live JEV call recorded in the phase doc.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
2026-10-11 21:37:38 +11:00
parent bf43b6bbef
commit af3b5e5f0e
27 changed files with 3235 additions and 102 deletions

View File

@@ -108,6 +108,89 @@ func (s *Store) applyMigrations(ctx context.Context) error {
return fmt.Errorf("record schema version 2: %w", err)
}
}
if version < 3 {
// FR-14: seed the default category list and a starter (comment-only)
// rules document. Seeding happens only inside this migration so that a
// category the user removes is not silently re-added on the next start.
if err := s.seedCategories(ctx); err != nil {
return err
}
if err := s.seedRules(ctx); err != nil {
return err
}
if _, err := s.db.ExecContext(ctx,
`INSERT OR IGNORE INTO schema_migrations (version) VALUES (3)`); err != nil {
return fmt.Errorf("record schema version 3: %w", err)
}
}
return nil
}
// defaultCategories are the starter categories from AGENTS.md §13.2. The
// descriptions are shown in the UI and sent to JEV as the Choice rubrics.
var defaultCategories = []struct{ name, description string }{
{"Action", "Needs Sam to do something"},
{"Important", "Worth Sam's attention, but no specific task"},
{"Info", "Informational, no action required"},
{"Spam", "Unwanted, deceptive, or scam mail"},
{"Newsletter", "Bulk mail, digests, and marketing"},
{"Auto-reply", "Automated notifications and receipts"},
}
// seedCategories inserts the built-in categories when the table is empty.
func (s *Store) seedCategories(ctx context.Context) error {
var n int
if err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM categories`).Scan(&n); err != nil {
return fmt.Errorf("count categories: %w", err)
}
if n > 0 {
return nil
}
for i, c := range defaultCategories {
if _, err := s.db.ExecContext(ctx,
`INSERT INTO categories (name, description, position) VALUES (?, ?, ?)`,
c.name, c.description, i+1); err != nil {
return fmt.Errorf("seed category %q: %w", c.name, err)
}
}
return nil
}
// starterRules documents the rule syntax (FR-4/FR-11). The editor that writes
// real rules lands in Phase 6; the classifier already reads whatever is stored.
const starterRules = `# Email Agent rules (FR-4). One rule per line.
#
# <condition> => <effects>
#
# condition: <field> <operator> "<value>", joined with " and ".
# fields: from, to, subject, source, body
# operators: contains, equals, starts_with, ends_with
# a single "*" matches every message (use it as the last line for a default).
#
# effects: comma-separated category=<name>, importance=<low|medium|high>,
# action=<delete|unsubscribe|reply|file|keep>
#
# The first matching rule wins and overrides the JEV classification for the
# fields it names. Category names must exist in the category list.
#
# Examples (remove the leading # to enable):
# from contains "amazon.com" => category=Newsletter, action=unsubscribe
# subject contains "invoice" => category=Action, importance=high, action=file
`
// seedRules stores the starter rules document when no rules exist yet.
func (s *Store) seedRules(ctx context.Context) error {
var n int
if err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM rules`).Scan(&n); err != nil {
return fmt.Errorf("count rules: %w", err)
}
if n > 0 {
return nil
}
if _, err := s.db.ExecContext(ctx,
`INSERT INTO rules (text, version) VALUES (?, ?)`, starterRules, 1); err != nil {
return fmt.Errorf("seed rules: %w", err)
}
return nil
}