# RepoKey PL-PS Handoff

RepoKey PL-PS Handoff generates PS-facing PL handoff artifacts from Vivado/RepoKey context.

The product boundary is PL-side only:

- Reuse existing RepoKey/Vivado context instead of rescanning the project from scratch.
- Trace PS-visible GP/HP/IRQ paths to the RTL modules and IP blocks that implement the real function.
- Generate Excel, Markdown, JSON, evidence, AI reading guides, and PS delivery workbooks.
- Preserve engineer/AI semantic feedback without overwriting tool-owned hard facts.

## Core Method

The project uses the "follow the vine to find the melon" classification method.

- Vine: a PS-visible path from Zynq GP/HP/IRQ through interconnect, DataMover, BRAM controller, xlconcat, and RTL ports.
- Melon: the real business function at the end of that path, such as GP0 wave table, GP1 status/control, BC wave-control registers, DDR data regions, or interrupts.
- Classification: front Excel sheets are grouped by business melon, not by internal `control_id` or BD cell.

The tool narrows evidence and reading paths so semantic extraction can happen efficiently. The default user-facing output is the final semantic handoff, not a separate context-only workbook. AI inference must stay distinguishable from hard BD/RTL facts.

## Output Rule

Default runs should produce one final semantic output set:

```text
context -> semantic extraction/enrichment -> final control_handoff.xlsx + ps_delivery.xlsx
```

Do not present a separate "context-only" workbook as a normal deliverable. Context-only or raw extraction artifacts are for extractor debugging only, and should live under an explicit debug output directory when needed.

## Main Outputs

`control_handoff.xlsx` is the PL iteration and review workbook.

Important sheets:

- `AXI地址`
- `GP0波位表`
- `GP0字段位`
- `GP1控制状态`
- `PC参考系数`
- `MTD窗系数`
- `BC波控`
- `DDR数据区`
- `中断`
- `旧表对齐`
- `AI取舍建议`
- `人工审核`

`ps_delivery.xlsx` is the PS delivery workbook. It contains only the business-facing sheets from `AXI地址` through `中断`.

## Run

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff pl2ps <vivado-project-or-xpr> `
  --output real_outputs\demo `
  --summary-json
```

Default final outputs:

- `control_handoff.xlsx`
- `ps_delivery.xlsx`
- `control_handoff.md`
- `control_handoff.json`
- `evidence.md`
- `ai_reading_guide.md`

## Legacy Excel Merge

Old Excel workbooks are treated as another vine/melon evidence source. The tool compares old and current tables, AI performs a pre-review, and only unresolved differences are sent to the PL engineer in Excel.

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff compare-legacy `
  current\control_handoff.json `
  old\ps_register_map.xlsx `
  --output legacy_current_compare.json
```

Comparison statuses:

- `same_vine_same_melon`
- `same_vine_changed_melon`
- `same_melon_moved_vine`
- `legacy_only`

Preferred flow:

```text
context -> semantic pl2ps -> compare-legacy -> AI merge decision -> apply-merge-decision -> PL Excel review -> delivery-from-review
```

The `人工审核` sheet uses a controlled `人工结论` dropdown:

- `保留新表`
- `保留旧表`
- `合并旧表语义`
- `标记冲突`
- `旧表废弃`
- `怀疑新表漏项`
- `待确认`

`人工备注` remains free text.

## Delivery From Review

After PL review, generate a PS delivery workbook only when review decisions change delivery content:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff delivery-from-review `
  reviewed\control_handoff.json `
  reviewed\control_handoff.xlsx `
  --output real_outputs\delivery `
  --summary-json
```

If there is no delivery-impacting difference, no new delivery workbook is generated.

## Feedback Patch

AI or engineers can write learned RTL/BD semantics as structured patch data.

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff feedback-template `
  real_outputs\demo\control_handoff.json `
  --output real_outputs\demo\feedback_patch_template.json

{{REPOKEY_ROOT}}\repokey-client.cmd handoff apply-feedback `
  real_outputs\demo\control_handoff.json `
  feedback_patch.json `
  --output real_outputs\demo_patched `
  --summary-json
```

Patch updates append `semantic_entries`. They do not overwrite hard facts such as BD path, base address, address range, interrupt path, or source evidence.

## Sample Validation Snapshot

Current validation artifacts:

- `real_outputs\sample_project_from_context_cache\legacy_current_compare_v14_optimized.json`
- `real_outputs\sample_project_from_context_cache\merge_decision_ai_review_optimized_v3.json`
- `real_outputs\sample_project_ai_review_optimized_v3\control_handoff.xlsx`
- `real_outputs\sample_project_ai_review_optimized_v3\ps_delivery.xlsx`
- `real_outputs\sample_project_delivery_from_ai_review_optimized_v3\ps_delivery.xlsx`
- `real_outputs\sample_project_semantic_delivery_cn\control_handoff.xlsx`
- `real_outputs\sample_project_semantic_delivery_cn\ps_delivery.xlsx`

The optimized comparison imports legacy rows, filters note noise, parses word offsets, matches equivalent absolute addresses, and leaves AI-reviewed items for PL human review.

The semantic delivery validation uses the current `.vivado_ai_mcp` context as the evidence input and directly emits the final semantic delivery workbook. A separate context-only workbook is not part of the normal handoff result.

## Validate

```powershell
$env:PYTHONPATH='src'
$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
python -m pytest -q -p no:cacheprovider tests\test_handoff_v0.py
python -m compileall -q src tests\test_handoff_v0.py
```
