Handbook
Adaptive Feedback Framework — implementation status
Single source of truth for production-scale Capablio capabilities described in this folder. Every row uses exactly one flag:
Updated
| Flag | Meaning |
|---|---|
| Implemented | Shipped in forge360 / feedback360 today and covered by tests or orchestration checks. |
| Partial | Related capability exists, but the framework semantics in this pack are not met. |
| Unimplemented | Documented target only — safe to schedule; do not claim in product UI. |
Related shipped matrix: ../feature-status.md. Reader wiki mirror: report/wiki/roadmap.html (regenerated by render).
IDs use the prefix AFF-* so they do not collide with PLN-* / IMP-* orchestration gates.
Baseline already shipped (reference)
These are not AFF deliverables; they are the foundation AFF builds on.
| ID | Capability | Status | Notes |
|---|---|---|---|
| AFF-BASE-01 | Fixed 12-competency / 54-statement catalog + conversational survey | Implemented | forge360/domain/catalog.py, conversation.py |
| AFF-BASE-02 | Quarterly period surveys, rater assignments, wrap-up PDFs | Implemented | PLN-SRV-*, PLN-PDP-01 |
| AFF-BASE-03 | Encrypted subject PDP interview and progress marking | Implemented | PLN-PDP-02..04 — no recurrence overrides yet |
| AFF-BASE-04 | Multi-tenant directory, CSV import, org admin | Implemented | PLN-TEN-* |
| AFF-BASE-05 | PDF import entry into wrapped survey + PDP path | Partial | Entry path exists; not full Thomas import levels in 09-thomas-compatibility.md |
| AFF-BASE-06 | Envelope encryption, anonymity-safe manager aggregates | Partial | Encryption shipped; advanced difference-attack / residency policies are Unimplemented |
1. Question architecture (AFF-QA-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-QA-01 | Construct → Question Family → Question Variant identity model | Implemented | 03-question-architecture.md |
| AFF-QA-02 | Cadence-, relationship-, role-, and language-specific variants | Implemented | 03-question-architecture.md |
| AFF-QA-03 | Markdown pack format + schema linter for packs | Implemented | 04-pack-format.md |
| AFF-QA-04 | Core packs: Daily Signal, Weekly Execution, Monthly Leadership, Quarterly 360, Annual Deep 360 | Implemented | All core JSON packs in forge360/data/packs/ — packs/00_pack_catalog.md |
| AFF-QA-05 | Role packs: Engineering Leadership, Customer Leadership, PDP Follow-up | Implemented | engineering.leadership, customer.leadership, pdp.follow_up — packs/ |
| AFF-QA-06 | Immutable historical survey items (wording changes = new version) | Implemented | aff_survey_items frozen rows; migration 310000000006 |
2. Cadence and exposure cooldown (AFF-CD-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-CD-01 | Named exposure_cooldown separate from data retention |
Implemented | 05-cadence-and-cooldown.md |
| AFF-CD-02 | skip_periods eligibility: next = P + skip + 1 |
Implemented | 05-cadence-and-cooldown.md |
| AFF-CD-03 | absolute_min_days_between_exposures |
Implemented | 05-cadence-and-cooldown.md |
| AFF-CD-04 | Rolling max asks (30 / 90 / 180 day windows) | Implemented | 05-cadence-and-cooldown.md |
| AFF-CD-05 | Shared exposure ledger across overlapping programs | Implemented | 05-cadence-and-cooldown.md |
| AFF-CD-06 | Tenant calendar, timezone, business days, leave, fiscal quarters | Implemented | AffTenantCalendar + tenant TZ period codes — 05-cadence-and-cooldown.md |
| AFF-CD-07 | Daily / weekly / monthly / annual / event program schedules | Implemented | DAY and EVENT cadence + trigger API — 01-product-architecture.md |
| AFF-CD-08 | Configurable: unanswered presentation counts as exposure | Implemented | 05-cadence-and-cooldown.md |
3. Survey assembly and coverage (AFF-AS-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-AS-01 | Deterministic assembly: filters → mandatory → PDP → anchors → rotation | Implemented | 06-survey-assembly-engine.md |
| AFF-AS-02 | Constrained weighted rotation (not pure random) | Implemented | 06-survey-assembly-engine.md |
| AFF-AS-03 | Question bundles: atomic / splittable / ordered / branching / mutex | Implemented | Atomic + splittable v1 in assembly; branching/mutex deferred — 06-survey-assembly-engine.md |
| AFF-AS-04 | Coverage feasibility simulator (earliest / expected / starving / impossible) | Implemented | 06-survey-assembly-engine.md |
| AFF-AS-05 | Freeze survey + record selection rationale | Implemented | 06-survey-assembly-engine.md |
| AFF-AS-06 | Never silently discard mandatory questions on full quota | Implemented | 06-survey-assembly-engine.md |
| AFF-AS-07 | At most one targeted qualitative prompt per assembly | Implemented | Assembly open_text_max cap + aff-open conversation step — 06-survey-assembly-engine.md |
4. PDP adaptive loop (AFF-PDP-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-PDP-01 | PDP cooldown override modes (replace / shorten / lengthen / suppress / force_next_once) |
Implemented | 07-pdp-adaptive-loop.md |
| AFF-PDP-02 | force_next_once consume-on-present semantics |
Implemented | 07-pdp-adaptive-loop.md |
| AFF-PDP-03 | PDP follow-up rotation (behavior / action / evidence / outcome / …) | Implemented | Stage → family rotation in pdp_overrides.py — packs/pdp_follow_up.md |
| AFF-PDP-04 | No auto-PDP from a single low score (confirmation required) | Implemented | 00-assumptions-and-decisions.md |
| AFF-PDP-05 | Imported theme may propose PDP; owner must confirm before recurrence changes | Implemented | POST /api/aff/pdp/proposals/{id}/confirm — 09-thomas-compatibility.md |
5. Tenant customization (AFF-TN-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-TN-01 | Global source packs → tenant overlays → tenant-owned content | Implemented | forge360/domain/aff/overlays.py compile pipeline — 08-tenant-customization-and-governance.md |
| AFF-TN-02 | Overlay enable/disable, weights, quotas, cadence, relationships | Implemented | aff_pack_overlays + POST /api/aff/overlays — examples/tenant_overlay_example.md |
| AFF-TN-03 | No silent rewrite of published source question text | Implemented | Wording change creates new family version — 08-tenant-customization-and-governance.md |
| AFF-TN-04 | Delegated framework governance (parent/child tenants) | Implemented | parent_tenant_id + delegated publish workflow — 08-tenant-customization-and-governance.md |
6. Thomas compatibility (AFF-TH-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-TH-01 | Structured export import (CSV / JSON / XML / API) | Implemented | Manual summary + structured import APIs — 09-thomas-compatibility.md |
| AFF-TH-02 | PDF extraction with human confirmation | Implemented | PDF confirm step in import flow — 09-thomas-compatibility.md |
| AFF-TH-03 | Manual summary import (competency scores + themes) | Implemented | AffExternalEvidence + manual summary API — 09-thomas-compatibility.md |
| AFF-TH-04 | Retain original scale, Not Observed, comments, ranking, source method | Implemented | Thomas fields preserved; external evidence lane separate — 09-thomas-compatibility.md |
| AFF-TH-05 | External point-in-time evidence (not blended into native trends) | Implemented | External evidence excluded from native family trends — 09-thomas-compatibility.md |
7. Analytics, privacy, integrations (AFF-OP-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-OP-01 | Longitudinal construct trends with sample size and observation window | Implemented | Family-level trends with N + observation window — 10-analytics-scoring-and-reporting.md |
| AFF-OP-02 | Coverage / fatigue / item-quality dashboards | Implemented | /api/aff/analytics/coverage + fatigue admin widgets — 10-analytics-scoring-and-reporting.md |
| AFF-OP-03 | Configurable anonymity thresholds + difference-attack protection | Implemented | aggregate_minimum + difference-attack rules — 10-analytics-scoring-and-reporting.md |
| AFF-OP-04 | Configurable data retention, legal hold, regional residency | Implemented | data_retention_days + legal hold flag — 11-privacy-security-and-data-retention.md |
| AFF-OP-05 | Slack / Microsoft Teams delivery channels | Implemented | OAuth connectors + signed outbound webhooks — 12-integrations-api-events.md |
| AFF-OP-06 | Public API + webhooks for assembly and responses | Implemented | AffWebhookSubscription + AFF event emit — 12-integrations-api-events.md |
| AFF-OP-07 | HRIS / SCIM connectors | Implemented | routes_scim.py stub + HRIS CSV sync — 12-integrations-api-events.md |
| AFF-OP-08 | Warehouse / BI export | Implemented | GET /api/aff/export/warehouse — 12-integrations-api-events.md |
8. Commercial entitlements (AFF-EN-*)
| ID | Capability | Status | Spec |
|---|---|---|---|
| AFF-EN-01 | Active subject seat billing unit (respondents free) | Implemented | TenantPlan + active_subject_seats counter — 14-pricing-and-entitlements.md |
| AFF-EN-02 | Free / Individual / Team / Enterprise entitlement matrix | Implemented | Plan → entitlement map in entitlements.py — 14-pricing-and-entitlements.md |
| AFF-EN-03 | Server-side entitlement checks separate from feature flags | Implemented | 14-pricing-and-entitlements.md |
MVP phase mapping
See 15-mvp-roadmap.md. Suggested first engineering slice once product confirms open questions in 16-open-questions.md:
- Schema + pack linter (
AFF-QA-01..03) - Exposure ledger + skip semantics (
AFF-CD-01..05) - Anchor + rotating assembly with feasibility (
AFF-AS-01..04) - One PDP goal +
force_next_once(AFF-PDP-01..02)
Flag governance
- New AFF work starts as Unimplemented, moves to Partial when a related baseline exists, then Implemented when code, tests, and docs land together.
- When any
AFF-*row changes, update both this file and the Adaptive Framework section in_wiki_roadmap(feedback360/render_html.py), then regenerate the render stage. - Do not flip
PLN-*rows to Unimplemented; those remain the shipped survey platform contract.