016 — Matching & Recommendation Engine (v1.0)
WST • PRIVATE • AUDITABLE • HUMAN-FIRST
Purpose
The Matching & Recommendation Engine evaluates project units against declared capacity and blind bids, then produces ranked recommendations for project awarding.
It exists to:
reduce bias
improve fit
surface best candidates
preserve human choice
prevent hidden favoritism
The engine recommends.
The project awards.
The system records.
Core Doctrine
Recommendations are advisory, not sovereign
Matching must be explainable
Identity stays hidden during blind evaluation
Scoring must rely on declared facts, not social status
Projects may award outside the top recommendation, but must record why if policy requires
The engine must resist gaming
No recommendation may create execution truth by itself
Engine Position
Capacity Registry
→ Bid Submission
→ Matching & Scoring
→ Recommendation Output
→ Project Award
→ Intent Accepted
→ Execution Queue
Inputs
- Project Unit Contract
Defines what the work needs.
Example inputs:
value_class
unit type
required capabilities
estimated effort
location / region
timing / start window
host charter
- Capacity Registry
Defines what the member can actually provide.
Example inputs:
type
category
capabilities
availability
declared regions
optional reputation metrics
- Blind Bid
Defines willingness and proposed fit.
Example inputs:
bid against specific unit
proposed effort
compensation mode
timing
optional notes/constraints
- Policy Weights
Defines how the engine scores.
These should be explicit and versioned.
Blind Evaluation Doctrine
During recommendation phase, the project should see:
capability summary
fit score
availability fit
optional reputation score
bid terms summary
The project should not see:
member identity
personal name
unrelated status
social rank
anything likely to create bias
Allowed exception:
explicit override modes after blind phase
Scoring Model
Canonical principle
Match Score =
Capability Match
+ Availability Fit
+ Capacity Alignment
+ Delivery Confidence
+ Policy Weighting
- Risk Penalties
Base Score Components
- Capability Match
Measures how well declared capabilities align with unit requirements.
Example factors
exact skill match
category alignment
required capability coverage
Suggested range:
0 to 40
- Availability Fit
Measures whether the bidder can actually do the work in the time needed.
Example factors
available hours
start window fit
schedule alignment
Suggested range:
0 to 20
- Capacity Alignment
Measures whether declared capacity is structurally appropriate.
Example factors
right type: service / equipment / material / funding
sufficient scale
suitable region / delivery mode
Suggested range:
0 to 20
- Delivery Confidence
Optional, lower-weight factor.
Example factors
prior completed units
success rate
reliability signals
Suggested range:
0 to 10
Doctrine
This must not overpower merit or become aristocracy-by-history.
- Policy Weighting
Optional charter or project policy influence.
Example factors
local-first weighting
trusted-network preference
host charter preference
urgent-response mode
Suggested range:
0 to 10
Doctrine
Must be explicit and visible in scoring explanation.
Risk Penalties
These reduce score.
Example penalties
missing required capability
insufficient time
incomplete bid
stale capacity declaration
unresolved past failure state
scope mismatch
Suggested range:
0 to -30
Canonical Score Formula
Example:
Score =
capability_score
+ availability_score
+ capacity_alignment_score
+ delivery_confidence_score
+ policy_score
- risk_penalty
Capped:
minimum 0
maximum 100
Example Weight Profile
{
"profile_id": "MATCH-DEFAULT-V1",
"weights": {
"capability_match": 40,
"availability_fit": 20,
"capacity_alignment": 20,
"delivery_confidence": 10,
"policy_weighting": 10
},
"penalties": {
"missing_required_capability": 20,
"stale_capacity": 10,
"incomplete_bid": 10,
"scope_mismatch": 15
}
}
Recommendation Output
Minimum output:
{
"unit_id": "UNIT-001",
"recommendations": [
{
"bid_id": "BID-0001",
"match_score": 92,
"fit": "HIGH",
"explanation": {
"capability_match": 38,
"availability_fit": 18,
"capacity_alignment": 19,
"delivery_confidence": 7,
"policy_weighting": 10,
"risk_penalty": 0
}
},
{
"bid_id": "BID-0002",
"match_score": 84,
"fit": "HIGH",
"explanation": {
"capability_match": 34,
"availability_fit": 17,
"capacity_alignment": 18,
"delivery_confidence": 8,
"policy_weighting": 7,
"risk_penalty": 0
}
}
],
"computed_at_utc": "2026-04-18T09:00:00Z",
"profile_id": "MATCH-DEFAULT-V1"
}
Fit Bands
Suggested:
90–100 → HIGH
75–89 → GOOD
60–74 → MEDIUM
40–59 → LOW
0–39 → POOR
These are for human reading, not authority.
Recommendation Rules
- Engine recommends, project chooses
The engine does not auto-award in v1.0.
- Highest score is not mandatory
A project may choose another bid, but:
optional reason should be recorded
policy may require justification
This preserves human judgment.
- No recommendation without declared basis
Every score must be decomposable into explainable parts.
No black box.
Tie Handling
If scores are close:
Suggested tie rule
If top candidates are within a narrow margin, such as ≤ 3 points:
mark them as effectively tied
present both as strong recommendations
This avoids fake precision.
Local-First Weighting
Optional policy profile:
{
"policy_weighting": {
"host_charter_member_bonus": 5,
"same_region_bonus": 3
}
}
Doctrine
Allowed, but must be explicit and limited.
This lets you favor local deployment without openly biasing by identity.
Trusted-Network Weighting
Optional, careful use.
Example:
known reliable prior collaborators receive small boost
Doctrine
Must remain subordinate to capability and availability.
Do not let this become crony logic.
Urgency Mode
For urgent units, the engine may temporarily increase:
availability fit
recent readiness
rapid start compatibility
This is useful for emergency response or high-priority local projects.
Anti-Gaming Protections
This is critical.
- Stale capacity penalty
Old, never-updated capacity records should lose score.
- Capability inflation resistance
Self-declared capacity may be weighted cautiously until validated by completed units.
- Reputation cap
Past performance should help, but never dominate.
Suggested rule:
cap delivery confidence to modest weight
- Duplicate bid suppression
A single member should not flood the same unit with many equivalent bids through shadow records.
- Identity blindness
Do not expose member names during scoring.
- Hidden override prohibition
No unseen ranking tampering.
All weight profiles must be explicit and versioned.
Quality Signals
Optional future scoring inputs:
completion rate
on-time rate
peer confirmation
dispute history
fulfillment proof quality
These should be added slowly and carefully.
Failure Rules
If no bids are matchable:
return no recommendation
mark unit as unmet
optionally suggest capacity gap
If input data is incomplete:
score conservatively
flag result as degraded
If scoring profile missing:
fail closed or use default canonical profile
Output Status Modes
Suggested result states:
OK
DEGRADED
NO_MATCH
INSUFFICIENT_DATA
Example:
{
"status": "DEGRADED",
"reason": "capacity freshness unavailable"
}
Suggested Canonical Storage
Profiles
/portal/_data/matching/profiles/
Recommendation output
/portal/_data/matching/recommendations/by_unit/{unit_id}.json
Logs
/portal/_data/matching/logs/
Minimal Functions
Suggested engine functions:
wst_match_unit_load_requirements(string $unitId): array
Load unit requirements
wst_match_unit_load_bids(string $unitId): array
Load blind bids
wst_match_capacity_load(string $capacityId): array
Load capacity record
wst_match_score_bid(array $unit, array $bid, array $capacity, array $profile): array
Return explained score
wst_match_rank_bids(array $scores): array
Return ranked recommendation list
wst_match_recommend(string $unitId, string $profileId = 'MATCH-DEFAULT-V1'): array
Return recommendation output
Example for Your Jonesboro System
Unit:
Survey local water + power needs
Bids:
3 blind submissions
Engine output:
Bid A: 92 HIGH
Bid B: 85 GOOD
Bid C: 78 GOOD
Project sees:
anonymous ranking
capability summaries
fit explanations
Project awards:
top recommendation or another justified choice
Then:
winning bid identity revealed
project association activated
intent accepted
queue begins
Human Override Doctrine
The project may override the recommendation, but should not do so invisibly.
Recommended award record:
{
"unit_id": "UNIT-001",
"selected_bid_id": "BID-0002",
"top_recommended_bid_id": "BID-0001",
"override": true,
"override_reason": "specialized regional knowledge required"
}
This preserves accountability without killing judgment.
Final Principle
The engine should reward fit, not favoritism.
What this unlocks
With this engine in place, your system now has:
blind merit-based matching
explainable recommendations
human-governed awarding
reduced bias
scalable labor/capacity allocation
That is a serious step toward a living project economy.