Lineage Traceability

Lineage is the mechanism behind FylloCode's end-to-end traceability. A requirement is recorded from creation, discussion, planning, implementation, and archive as one traceable path. The three execution paths define how a change can move. Lineage records what actually happened across that path — whether it took the direct, Plan, or Proposal route.

Core Concept: Subject

One trace in lineage is called a subject. A subject represents one requirement intent and contains:

Field	Description
Origin	task or chat, recording whether the subject started from a task or directly from a chat.
Task snapshot	The linked task reference and snapshot, including source such as local or an engineering system. Chat-origin subjects start empty.
Links	All Chat sessions under this subject. Each session records the Plans and Proposals it produced.

One subject can connect multiple sessions, Plans, and Proposals. If the same task is discussed multiple times and produces multiple changes, they belong to the same subject.

How the Path Is Created

Task --start discussion--> Chat Session --> Plan / Proposal --> Apply & Archive
 |                              |                              |
 +------------- same lineage subject --------------------------+

1. Starting from a Task

When discussion starts from a task card on the Task Board, FylloCode creates or reuses a subject anchored to that task and binds the new session to it. The Chat page shows a source task banner at the top. Reopening the session still shows the banner.

Starting discussion again from the same task appends the new session to the same subject instead of creating a separate one.

2. Starting from Chat

When discussion starts directly from the Chat page, FylloCode creates a chat-origin subject once the conversation produces a final plan. It also shows a card for creating a task, helping you turn the plan into a local task.

If the conversation is only exploratory and does not produce a proposal, it is not counted as task-linked in lineage coverage.

3. Plan and Proposal Auto-Linking

When an Agent creates a plan or a proposal through the create-plan or create-proposal tool from fyllo-specs, the resulting plan slug or proposal changeId is automatically recorded on the subject of that session. No manual linking is required, whether the discussion took the Plan path or the Proposal path. Direct implementation — which calls neither tool — leaves no such link; the subject keeps only the session itself.

4. Creating a Task Later

A chat-origin subject can create a task after the conversation:

• In Chat, you can ask the Agent to propose a local task. It outputs a structured fyllo-action with task.create, and you confirm before FylloCode executes it.

The created task is written back to the same subject. The origin remains chat, but lineage coverage counts it as task-linked. This lets "talk first, then formalize the task" still enter the governance path.

Data Storage

Lineage data is stored entirely in the local project data directory:

• Each subject is an independent JSON file at lineage/subjects/<subjectId>.json.
• A reverse lookup index at lineage/index.json maps task references, session IDs, and proposal changeIds back to subjects. The index can always be rebuilt from subject files.

There is no database and no external upload. Data stays local with the project data.

Where Lineage Is Used

• Chat page: source task banner that identifies which task the session belongs to.
• Project Overview: lineage coverage, recent subjects, and task lookup for active changes are based on lineage projections.
• Work Lineage: browse every subject, filter by state, and inspect Plans, Proposals, and Commits along each Session.
• Archive traceability: after a change is archived, FylloCode can trace from proposal back to session and task to answer "why did this change happen and what was discussed?"

Why This Path Matters

git blame tells you who committed code. Lineage adds three missing answers:

• Which task this change came from and what problem it tried to solve.
• Which discussions happened and which plan they produced.
• Where the tradeoffs and rejected directions were recorded.

In ordinary Agent sessions, this information disappears with the chat window. In FylloCode, it is structured data on one subject and remains queryable months later.