📝 docs(ci): design scoped tsl playbook sync

2026-07-13 09:56:25 +08:00
parent e7110bd3b1
commit 9fc823d893
1 changed files with 116 additions and 0 deletions
@@ -0,0 +1,116 @@
 # Sync TSL Playbook Workflow Upgrade Design
 ## Background
 The `tsl-playbook` branch is a mixed branch: the synchronization workflow owns the
 generated TSL playbook paths, while README files and other manually maintained
 content must survive each publication.
 The current workflow treats the whole `docs/` and `skills/` directories as generated:
 ```bash
 generated_paths=(AGENTS.md docs skills)
 ```
 That ownership boundary is wider than the bundle actually owns. TSL syntax is now
 provided by `tsl-syntax-reference`, while the branch may also contain unrelated
 documentation and Skills that the workflow must not delete.
 ## Goal
 Redesign `.gitea/workflows/sync-tsl-playbook.yml` so it updates only the TSL
 playbook paths while preserving every unrelated target-branch file.
 ## Managed Paths
 The workflow exclusively owns these four paths:
 ```text
 AGENTS.md
 docs/tsl/
 skills/tsl-syntax-reference/
 skills/tsl-api-reference/
 ```
 It must preserve all other paths, including:
 - root files such as `README.md`;
 - non-TSL documentation under `docs/`;
 - unrelated Skills under `skills/`;
 - any other manually maintained target-branch content.
 The workflow does not special-case `docs/tsl/syntax`. Whether that path exists is
 determined by the source tree and the bundle builder, not by publication logic.
 ## Publication Flow
 1. Clone and check out the latest `origin/main` in a temporary repository.
 2. Build the TSL bundle outside the repository working tree.
 3. Validate that all four managed paths exist in the bundle.
 4. Check out the existing remote target branch, or create an orphan target branch.
 5. Remove only the four managed paths from the target working tree.
 6. Copy each managed path explicitly from the bundle.
 7. Stage changes only for the four managed paths.
 8. Exit successfully without a commit when the staged diff is empty.
 9. Otherwise commit with the source SHA footer and push the target branch.
 Explicit copying is preferred over copying the bundle root. This keeps the workflow's
 write behavior aligned with its declared ownership boundary even if the bundle gains
 additional top-level files later.
 ## Branch Behavior
 For an existing `tsl-playbook` branch, the workflow starts from
 `origin/tsl-playbook`, so unmanaged files retain their current content and history.
 For a new target branch, the workflow creates an orphan branch and clears the inherited
 index before adding the four managed paths. Source-only files from `main` must not leak
 into the new branch.
 The workflow must not merge the source and target branches. It publishes a generated
 commit directly on the target branch.
 ## Failure Handling and Security
 - Missing bundle paths fail before the target branch is modified.
 - `set -euo pipefail` remains enabled for shell steps.
 - The bundle remains outside the repository so branch checkout cannot clobber it.
 - Authentication continues through `GIT_ASKPASS`; credentials are never embedded in
  the remote URL.
 - Temporary bundle and askpass files are removed through existing cleanup paths.
 - A failed copy or validation must prevent commit and push.
 ## Test Strategy
 Update the workflow contract and integration tests before changing the workflow.
 The tests must demonstrate that:
 - the managed path list contains the four exact paths and not the broad `docs` or
  `skills` directories;
 - root files outside the managed set survive synchronization;
 - non-TSL documentation under `docs/` survives synchronization;
 - unrelated Skills under `skills/` survive synchronization;
 - stale files inside each managed directory are deleted;
 - a newly created target branch contains the bundle paths without source-branch
  leakage;
 - an unchanged bundle produces no commit;
 - token handling remains based on `GIT_ASKPASS` and a credential-free repository URL.
 ## Non-Goals
 - Do not change the contents of `AGENTS.md`, TSL documentation, or either TSL Skill.
 - Do not add special handling for obsolete syntax-document paths.
 - Do not redesign `scripts/build_tsl_playbook.py` unless a workflow test exposes an
  interface mismatch required by the exact managed-path contract.
 - Do not delete or rewrite unrelated files on the target branch.
 - Do not change the target branch name or commit-message convention.
 ## Acceptance Criteria
 - Publication changes are limited to the four managed paths.
 - Unmanaged target-branch files are byte-for-byte preserved.
 - Stale content inside managed paths is removed.
 - New target branches contain no accidental files inherited from `main`.
 - Existing workflow security assertions and sync integration tests pass.
 - The full `test_build_tsl_playbook.py` suite passes.