Engineering Knowledge

Purpose

Fairway engineering knowledge is a project-owned, agent-maintained synthesis of software architecture, product domains, operational lessons, decisions, and open questions. It lets human and agent contributors build understanding over time instead of re-deriving it from raw repositories, task histories, and runtime artifacts for every question.

The model follows the LLM-wiki pattern of immutable or authoritative sources, a maintained Markdown synthesis layer, and a project schema that governs ingest, query, and lint. Fairway supplies the reusable lifecycle, provenance, and validation framework. Each consumer repository owns its knowledge content.

Product Boundary

Fairway is not a generic wiki host, transcript warehouse, vector database, or source-of-truth replacement. Its contribution is the engineering control contract around project knowledge:

• source registration and provenance;
• bounded ingest and page maintenance;
• deterministic structure and safety lint;
• stale, contradiction, orphan, and promotion findings;
• task-aware context selection;
• explicit movement between working memory, derived knowledge, and canonical documentation.

Knowledge pages are derived and non-canonical unless a project explicitly promotes their content through its normal documentation review process.

Learned Context Increment

Fairway should make a completed task's reusable lesson easy to retain without turning the provider transcript into memory. The supported flow is:

durable task facts
  -> bounded lesson proposal
  -> normal Markdown review
  -> verified knowledge page
  -> optional derived retrieval index
  -> bounded task or cold-start selection

The proposal may summarize task decisions, evidence, reviews, outcomes, and commit associations already present in the Fairway store. Every material claim must identify those durable facts. Raw prompts, reasoning traces, transcripts, tool bodies, and uncited generated conclusions are excluded. Capture is preview-first; apply creates only a normal Git diff and grants no review, promotion, or execution authority.

The useful unit is a short lesson with a clear reuse boundary, not a task history dump. A maintained lesson should answer:

• what was learned;
• when the lesson applies and when it does not;
• which failed or superseded approach matters;
• what observation or evidence changed the decision; and
• which source facts a future contributor must re-check.

Retrieval tiers

Retrieval remains useful without a model or index:

1. deterministic lexical selection from reviewed Markdown and task metadata;
2. optional local semantic similarity over a rebuildable index; and
3. hybrid ranking that retains lexical matches and uses semantic similarity to improve ordering or recover vocabulary mismatches.

The semantic index is a cache. It stores page identity, content digest, embedding-model identity, and vectors derived from safe bounded page text. It does not replace Markdown, copy Fairway authority, or make a page verified. Deleting it loses performance only. A missing, stale, incompatible, or failed index must fall back to deterministic lexical query and report that fallback. Embedding generation is an explicit local adapter boundary rather than a required Fairway dependency.

Cold-start composition

When the selected track is also a Fairway task, cold-start may derive knowledge terms from its title, domain, layer, acceptance boundary, source paths, target paths, and curated track memory. Explicit topics remain available to narrow or override that selection. Execution memory renders first under its existing budget. Learned context has a separate budget and cannot displace current task state, blockers, stop conditions, authority labels, freshness, or provenance.

Portable exchange

A portable knowledge bundle contains reviewed Markdown, the source manifest, a bundle manifest, and SHA-256 checksums. It may include a clearly labelled derived index. Export does not upgrade authority. Import validates paths, sizes, checksums, metadata, and citations in preview mode before proposing any Git diff. External status, authority, verification, or promotion fields are untrusted until the receiving project revalidates them against its own sources and Fairway store.

Measurement before automation

The GPUaaS pilot is the first qualification boundary. It measures retrieval relevance, missed reusable lessons, packet bytes, stale findings, maintenance effort, and incorrect authority choices. Those observations decide whether automatic capture suggestions or default semantic retrieval are justified; task volume, token volume, and generated-page count are not success measures.

Ownership Split

Owner	Responsibility
Fairway product	Schema, commands, validation, provenance, packets, lifecycle, metrics, and reusable templates
Consumer project	Source selection, knowledge pages, domain taxonomy, promotion targets, access policy, and review expectations
Git and canonical docs	Authoritative implementation and approved engineering truth
Fairway runtime store	Task, decision, evidence, review, and execution facts referenced by knowledge pages

Project knowledge lives in the consumer repository so it follows the code, remains portable without a Fairway service, and can be reviewed with normal Git history.

Default Project Layout

doc/agent-wiki/
├── README.md
├── index.md
├── current-state.md
├── sources.yaml
├── architecture/
├── product-domains/
├── environments/
├── decisions/
├── operations/
├── incidents-and-lessons/
├── open-questions.md
└── log.md

Projects may rename the root, but index.md, open-questions.md, and log.md retain their semantic roles:

• index.md is content-oriented navigation and page metadata;
• open-questions.md contains unresolved contradictions and knowledge gaps;
• log.md is the bounded chronological ingest/query/lint record.

Working memory is not stored in this directory. It may be an ingest source or a promotion candidate after verification.

Page Contract

Every maintained page includes bounded frontmatter:

---
knowledge_version: 1
title: Node trust model
status: verified
owner: platform-security
last_verified: 2026-07-22
review_by: 2026-10-22
source_sha: b3b346cd3499bc2ef69dbff28d28890228e11d73
sources:
  - class: architecture
    path: doc/architecture/node-trust.md
  - class: fairway-decision
    fairway:
      kind: decision
      id: "123"
  - class: fairway-evidence
    fairway:
      kind: evidence
      id: "456"
supersedes: []
---

Allowed initial status values are:

Status	Meaning
draft	Derived content not yet checked against all cited sources
verified	Checked against the named sources and source revision
stale	Source changes or age require re-verification
conflicted	Cited authorities disagree and the contradiction is unresolved
superseded	Replaced by a linked page or canonical document

verified means source-grounded within the declared scope. It does not mean the synthesis is correct, complete, approved architecture, accepted risk, compliance, or release readiness. Deterministic validation can prove that the named sources exist and have not changed; it cannot prove that a derived conclusion interpreted those sources correctly. Material conclusions still require normal human review at the boundary where they influence a decision.

Source Classes

The project knowledge root contains a sources.yaml manifest that registers source classes, authority, and allowed file roots:

knowledge_sources_version: 1
classes:
  project-file:
    kind: project_file
    authority: operational
    roots:
      - docs
      - doc/api
      - doc/architecture
      - doc/operations
      - doc/product
  architecture-decision:
    kind: project_file
    authority: canonical
    roots:
      - doc/architecture
  fairway-decision:
    kind: fairway
    authority: operational
    fairway_kind: decision
    requires_store_validation: true
  fairway-evidence:
    kind: fairway
    authority: evidence
    fairway_kind: evidence
    requires_store_validation: true

The generated project-file class is deliberately operational because broad documentation roots commonly contain a mix of canonical contracts, proposed decisions, target-state models, and unassessed implementation notes. A project must add a narrower canonical class, such as architecture-decision, before promoting source-grounded synthesis to verified canonical authority. Source frontmatter remains part of semantic review; deterministic lint cannot infer authority from arbitrary document metadata.

project_file sources must remain under a configured root and cannot cite the knowledge tree itself or legacy tmp-ux working memory as canonical authority. Fairway references must resolve in the current project's coordinator store. Fairway records source references and digests, not unrestricted copies of source content in its database.

Operations

Ingest

An ingest reads one bounded source set, proposes page changes, updates the index, and records provenance. It never changes canonical source documents. Agent-generated changes remain a normal Git diff subject to project review.

Query

A query starts from index.md, selects relevant pages, and includes citations to their source records. Useful answers can be proposed as new derived pages, but they remain draft until checked against primary sources.

Lint

Lint reports:

• invalid metadata or unsafe paths;
• missing or inaccessible cited sources;
• source revisions newer than page verification;
• pages past their review_by date;
• orphan pages and broken links;
• duplicate page identities;
• conflicting claims marked by ingest or reviewers;
• unbounded pages or logs;
• unverified content cited as sole support for another verified page;
• sensitive content and secret-pattern findings;
• promotion targets that are missing or stale.

Deterministic findings are separated from model-suggested semantic findings. The latter are advisory until a person or configured review accepts them.

Lint is part of the normal project quality loop, not an optional cleanup sweep. Each page has an owner and review_by date. Projects run deterministic lint in their configured local or CI documentation gate. Errors fail knowledge lint. Warnings remain advisory by default and become CI-blocking only when the caller uses knowledge lint --fail-on-warning. The owner must refresh, supersede, archive, or explicitly retain each overdue or stale page.

For a source class configured as canonical, source-document frontmatter is an additional authority constraint. source_of_truth: false is a hard contradiction and fails lint. implementation_state: not-assessed remains usable as canonical design evidence but produces a warning so target-state language is not mistaken for implementation proof. Sources without frontmatter retain their configured class.

Promote

Stable knowledge may be promoted into canonical documentation. Promotion requires a target path, reviewed Git commit, and links back to source facts. Fairway marks the derived page promoted or superseded only after that commit is recorded. Promotion never occurs silently.

Proposed Command Direction

fairway knowledge init
fairway knowledge status
fairway knowledge ingest --source <name-or-path> [--apply]
fairway knowledge query --topic <text> --format packet
fairway knowledge lint
fairway knowledge lint --fail-on-warning
fairway knowledge promote <page> --target <canonical-path>
fairway knowledge archive <page> --reason <text>

init, status, and deterministic lint form the first implementation slice. Ingest starts as preview plus reviewed file changes. Semantic retrieval, graph projection, and automated maintenance are later capabilities, not MVP dependencies.

Relationship To Working Memory

Fairway task facts and project sources
                 |
                 v
          Fairway track memory
       (durable operating context)
                 |
        verified cross-task value
                 v
          engineering knowledge
          (derived and maintained)
                 |
        stable approved contract
                 v
       canonical project documentation

The two features remain separate:

• Working Memory optimizes immediate execution continuity.
• Engineering Knowledge optimizes accumulated project understanding.

Knowledge must not become the place where an active task is claimed, blocked, approved, or completed.

Cold-Start Composition

A provider cold start uses one bounded composed packet rather than independently loading both stores:

1. fairway memory cold-start supplies the selected track's objective, current state, blockers, decisions, evidence, and next action.
2. The memory packet names zero or more knowledge topics relevant to that objective.
3. fairway knowledge query --format packet contributes only the selected pages and their provenance within a separate knowledge budget.
4. Duplicate source references are rendered once, with the higher authority label preserved.

Query packets report the current repository_revision and a source_freshness label for every selected page. A page is either current at the repository revision, current at its recorded source revision after unrelated repository changes, stale because cited bytes changed, or unverifiable. This keeps an older but content-current citation from being misreported as stale while still exposing the exact source SHA.

For shared Fairway evidence, the composed JSON contract uses the knowledge source as the single rendered identity. That source carries memory_referenced: true and retains the highest authority selected across its page citations. The embedded track-memory copy omits the corresponding raw source_evidence_ids entry. Evidence referenced only by memory remains in the memory packet, and evidence referenced only by knowledge remains in knowledge provenance.

Execution memory is required for task resumption. Knowledge is optional context for domain understanding and must not crowd out the objective, blocker, stop condition, or next action.

Cold-Start And Query Acceptance

A new contributor with repository and Fairway access should be able to:

1. find the knowledge index without prior conversation;
2. identify relevant pages for a named task or domain;
3. distinguish canonical sources, verified synthesis, drafts, and conflicts;
4. follow citations to source files, commits, decisions, and evidence;
5. avoid loading the complete project corpus into the provider context;
6. identify stale pages before relying on them;
7. propose, review, and record a correction without overwriting history.

The pilot measures answer grounding, context size, source lookup time, contradictions found, stale claims, maintenance time, repeated investigation, and incorrect authority choices.

Security And Privacy

• Source roots and promotion targets are project-relative and path validated.
• Symlinks and paths escaping configured roots are rejected.
• Raw prompts, transcripts, tool bodies, credentials, auth material, private keys, and unrestricted runtime dumps are excluded.
• Pages cite safe evidence references rather than embedding sensitive content.
• Generated text is scanned before write, packet rendering, export, and promotion.
• Project access rules apply to knowledge retrieval; Fairway does not widen repository or evidence access.

MVP And Deferred Scope

The MVP includes:

• project manifest and scaffold;
• page metadata and index contract;
• deterministic status and lint;
• provenance references;
• working-memory promotion proposal;
• bounded task/provider context packet;
• GPUaaS cold-start pilot.

Deferred until measured need:

• embeddings or a vector database;
• hosted knowledge service;
• cross-project semantic search;
• automatic writes triggered by every commit;
• graph database projection;
• autonomous conflict resolution or canonical-doc promotion.

At moderate scale, Markdown, Git, explicit indexes, and repository search are the preferred implementation. More infrastructure requires evidence that the simple model no longer meets retrieval or maintenance goals.