docs(11): capture phase context
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
# Phase 11: Synthesis and Config Layer - Context
|
||||
|
||||
**Gathered:** 2026-03-27
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Add ClassFreqConfigs entries for all 18 new classes in AllClasses() plus 3 LDAP/Kerberos/Syslog classes (adding them to AllClasses() too). Update `PrintConfig` to output classes grouped by family with section header comments. Add `[groups]` TOML config support for users to reassign protocols to different sound families. Fix all broken synth/config tests.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### ClassFreqConfigs Entries
|
||||
- **D-01:** Add ClassFreqConfigs entries for all 18 new classes currently in AllClasses(). Use Hz values, waveforms, pans, and groups from the Phase 9 frequency allocation table comment in `synth/config.go` lines 74-110. Use `WaveformPresetHarmonics()` for all new entries (not hand-tuned harmonics).
|
||||
- **D-02:** Add ClassLDAP, ClassKerberos, ClassSyslog to AllClasses() in `classify/types.go`. Create ClassFreqConfigs entries for them using `autoAssignFreq`-derived Hz values (FNV hash in [2500, 4000] Hz range). Their group is "Infrastructure", waveform is Triangle (matching the Infrastructure family pattern).
|
||||
- **D-03:** After D-01 and D-02, AllClasses() returns 35 entries (32 + 3). TestAllClassesCount updated to 35.
|
||||
|
||||
### PrintConfig Group Headers (GRP-02)
|
||||
- **D-04:** PrintConfig groups classes by their Group field value. Each group gets a comment header line: `# <Group>` followed by a blank line, then all classes in that group. Groups are ordered: Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP, Unknown.
|
||||
- **D-05:** Within each group, classes are ordered by ascending BaseHz (matching the frequency allocation table order).
|
||||
- **D-06:** User-defined classes (not in AllClasses but in FreqCfgs) are emitted after all built-in groups under a "# User-defined" section header.
|
||||
|
||||
### TOML Groups Config (GRP-03)
|
||||
- **D-07:** Users define group reassignments in TOML with a `[groups]` table using simple key-value pairs: `IMAP = "Web"` reassigns IMAP from Mail to Web group. The key is the TrafficClass string value, the value is the target group name.
|
||||
- **D-08:** Group reassignment only affects `--print-config` output grouping and the Group field in FreqConfig. It does NOT change frequency, waveform, or pan — those stay as designed. PrintConfig reflects the reassignment.
|
||||
- **D-09:** Unknown group names in `[groups]` config are accepted (user can invent custom group names). Unknown class names produce a warning (same pattern as `[sounds.X]` with unknown class).
|
||||
|
||||
### Claude's Discretion
|
||||
- Exact Hz values for LDAP, Kerberos, Syslog (computed from autoAssignFreq FNV hash)
|
||||
- Pan positions for LDAP, Kerberos, Syslog
|
||||
- Test structure for new ClassFreqConfigs entries and PrintConfig group output
|
||||
- Whether to add `[groups]` to rawConfig struct as `map[string]string` or a custom type
|
||||
- How to handle group reassignment in the merge/load pipeline
|
||||
|
||||
### Folded Todos
|
||||
- **"Expand Traffic Classes"** (from `.planning/todos/pending/001-expand-traffic-classes.md`) — Phase 11 completes the synthesis side of this request. Constants/rules were added in Phase 10; now all classes get sound configurations.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Synth Package (primary modification target)
|
||||
- `synth/config.go` — `ClassFreqConfigs` map (add 21 new entries), frequency allocation table comment (lines 74-110), `FreqConfig` struct, `WaveformPresetHarmonics` function
|
||||
- `synth/config_test.go` — `TestAllClassesHaveConfig`, `TestClassFreqConfigsMatchAllClasses`, `TestFrequenciesInRange`, `TestFrequenciesUnique`, `TestNewBankHas14Layers`
|
||||
|
||||
### Config Package (PrintConfig + groups)
|
||||
- `config/config.go` — `PrintConfig` function (lines 270-336), `rawConfig` struct (line 38-41), `LoadResult` struct, `merge` function, `autoAssignFreq` function, `addAutoFreqEntries`
|
||||
- `config/config_test.go` — `TestLoadAllDefaultsPresent`, `TestPrintConfigOutput`
|
||||
|
||||
### Classification Package (AllClasses update)
|
||||
- `classify/types.go` — AllClasses() function, TrafficClass constants (add LDAP/Kerberos/Syslog to AllClasses())
|
||||
- `classify/classifier_test.go` — `TestAllClassesCount` (update from 32 to 35)
|
||||
|
||||
### Requirements
|
||||
- `.planning/REQUIREMENTS.md` — GRP-02, GRP-03
|
||||
- `.planning/ROADMAP.md` — Phase 11 success criteria
|
||||
|
||||
### Prior Phase Context
|
||||
- `.planning/phases/09-frequency-design-and-group-architecture/09-CONTEXT.md` — Frequency design decisions, waveform-per-family strategy
|
||||
- `.planning/phases/10-classification-layer/10-CONTEXT.md` — PROTO-08 frequency strategy (D-01: autoAssignFreq for LDAP/Kerberos/Syslog)
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `WaveformPresetHarmonics(wt, baseHz, sampleRate)` — generates harmonics for any waveform at any frequency; use for all 21 new ClassFreqConfigs entries
|
||||
- `autoAssignFreq(className)` — FNV hash into [2500, 4000] Hz; use for LDAP/Kerberos/Syslog Hz values
|
||||
- `classAnnotation(cls, cfg, autoClasses)` — already handles "default", "override", "auto-assigned" annotations
|
||||
- `copyDefaults()` and `merge()` — existing config merge pipeline to extend with group support
|
||||
|
||||
### Established Patterns
|
||||
- ClassFreqConfigs entries follow: `classify.ClassX: {BaseHz, WaveformType, Harmonics: WaveformPresetHarmonics(...), Pan, Group}` pattern
|
||||
- PrintConfig iterates AllClasses() for built-ins, then sorts user-defined separately
|
||||
- rawConfig uses TOML struct tags for decoding; adding `[groups]` follows same pattern
|
||||
- SoundOverride uses pointer fields for partial overrides
|
||||
|
||||
### Integration Points
|
||||
- `config.Load()` returns `LoadResult` with `FreqCfgs` map — group reassignments must be applied before returning
|
||||
- `PrintConfig` reads `FreqCfgs` and `AllClasses()` — group headers derived from `FreqConfig.Group` field
|
||||
- `NewBank()` in `synth/bank.go` creates layers from `ClassFreqConfigs` — all new entries will get synthesis layers automatically
|
||||
- `TestNewBankHas14Layers` in `synth/bank_test.go` — name is stale, needs update to reflect 35 classes
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The frequency allocation table comment in `synth/config.go` (lines 74-110) is the authoritative source for all Hz, waveform, group, and pan values for the 18 table-designed classes
|
||||
- LDAP/Kerberos/Syslog get Infrastructure group + Triangle waveform (matching existing Infrastructure family) but their Hz comes from autoAssignFreq, not the table
|
||||
- PrintConfig currently has no group awareness — it just lists all classes in AllClasses() order. The refactor adds group-based iteration with comment headers
|
||||
- `go test ./...` must pass fully after Phase 11 — this is the first time since Phase 10 that the full test suite should be green
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope.
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 11-synthesis-and-config-layer*
|
||||
*Context gathered: 2026-03-27*
|
||||
@@ -0,0 +1,62 @@
|
||||
# Phase 11: Synthesis and Config Layer - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-03-27
|
||||
**Phase:** 11-synthesis-and-config-layer
|
||||
**Areas discussed:** Group header format, TOML groups schema, LDAP/Kerberos/Syslog handling
|
||||
**Mode:** --auto (all decisions auto-selected)
|
||||
|
||||
---
|
||||
|
||||
## Group Header Format in PrintConfig
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Comment headers with blank line separator | `# Mail` followed by blank line, then classes. Matches existing comment patterns. | ✓ |
|
||||
| Section dividers with dashes | `# --- Mail ---` style separator | |
|
||||
| No headers (flat list) | Keep current flat listing, rely on frequency ordering | |
|
||||
|
||||
**User's choice:** [auto] Comment headers with blank line separator (recommended default)
|
||||
**Notes:** Matches existing `# Classification rules` comment pattern in PrintConfig output
|
||||
|
||||
---
|
||||
|
||||
## TOML Groups Config Schema
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Simple key-value map | `[groups]` with `IMAP = "Web"` pairs. Simplest approach. | ✓ |
|
||||
| Nested table | `[groups.Mail]` with `members = ["IMAP", "POP3"]` — more structured but heavier | |
|
||||
| Array of tables | `[[groups]]` with name/members fields — most flexible but overkill | |
|
||||
|
||||
**User's choice:** [auto] Simple key-value map (recommended default)
|
||||
**Notes:** Consistent with existing `[sounds.X]` pattern. Key = class name, value = target group.
|
||||
|
||||
---
|
||||
|
||||
## LDAP/Kerberos/Syslog Handling
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Add to AllClasses() + ClassFreqConfigs | Complete the full set, fix broken tests. autoAssignFreq-derived Hz. | ✓ |
|
||||
| Keep out of AllClasses() | Leave as constants-only, no synthesis. Tests remain broken. | |
|
||||
| Add to ClassFreqConfigs only | Add configs but don't add to AllClasses(). Partial fix. | |
|
||||
|
||||
**User's choice:** [auto] Add to AllClasses() + ClassFreqConfigs (recommended default)
|
||||
**Notes:** Completes the full 35-class set. Fixes TestAllClassesHaveConfig and related tests.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Exact Hz values for LDAP/Kerberos/Syslog (autoAssignFreq FNV hash)
|
||||
- Pan positions for LDAP/Kerberos/Syslog
|
||||
- Test structure and naming updates
|
||||
- rawConfig struct extension for `[groups]`
|
||||
- Group reassignment pipeline in merge/load
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope.
|
||||
Reference in New Issue
Block a user