feat(sync): union-merge .gitignore from upstream with fenced managed block

[MarkMichaelis]

Summary

Refined plan to make upstream IntelliSDLC.ai .gitignore the canonical source of consumer ignore patterns via union-merge with a fenced managed block in the consumer's .gitignore. Also pins down line-ending detection, the no-local-file case, and a consumer-override rule.

See the full plan attached below. This issue is the prerequisite for the follow-up self-refresh abort-path restore work (filed separately, depends on this one).

Scope

• New Merge-GitignoreFromUpstream helper with fenced-block semantics (# --- begin/end sdlc.ai-managed entries ---).
• New merge_paths array in sync-manifest.json; add .gitignore.
• Upstream .gitignore curation (Option B): move dogfood-internal entries (Samples/HAR-Original/, .dogfood-output/, testResults.xml) into .gitignore.dogfood, not propagated.
• Consumer override rule: entries outside the fence win; in-fence duplicates dropped on next write.
• Re-appearance policy: deleted in-fence entries are re-appended next run; override via negation pattern outside the fence or upstream PR.
• CRLF/LF detection; LF default when creating.
• Pester tests (a)-(j) covering create/insert/idempotent/preserve-outside/override/CRLF/LF/cleanup branches.
• README docs update on consumer-owned files section.

Full plan

See attached plan-gitignore-merge.md (uploaded as a comment after issue creation).

Implementation order

This is Step 1 -- implement and merge before the dependent self-refresh restore issue.

[MarkMichaelis]

Plan: Pull-SDLC.ai.ps1 -- .gitignore union-merge + post-run cleanliness (refined)

Refined from the original at session
a572dfb2-4341-4d12-b43f-6a8f48092990/plan.md. All original design
decisions are retained; refinements from review are folded in below
and called out with [REFINED] tags.

Side answers

What created the local .playwright-mcp/?

The Playwright MCP server, when invoked by an AI coding agent (Copilot
CLI / Claude Code) via tools like browser_snapshot, browser_navigate,
browser_console_messages. The MCP server auto-creates the directory on
first write; the upstream .github/copilot-instructions.md pins the
location so all agents agree on where to write.

"Nothing to commit to origin after the pull" -- correct?

Yes. The script protected main by routing everything through the
auto-worktree -> push -> PR flow. Reviewing and merging the resulting
PR brings the IntelliSDLC.ai content into main. No additional commit
is needed.

Fix #1 -- union-merge upstream .gitignore into the consumer's

Design

Upstream IntelliTect-Samples/IntelliSDLC.ai maintains a canonical
.gitignore listing the entries every consuming project should ignore.

The script union-merges upstream's .gitignore into the consumer's
local .gitignore: every non-blank, non-comment entry that is not
already present in the consumer file is appended (inside a clearly
marked managed section). Upstream is the single source of truth for
IntelliSDLC.ai-mandated ignore patterns.

[REFINED] Marker-comment strategy

The merge helper writes managed entries inside an explicit fenced
region of the consumer's .gitignore:

# --- begin sdlc.ai-managed entries (do not edit by hand) ---
.evidence/
.playwright-mcp/
.worktrees/
...
# --- end sdlc.ai-managed entries ---

Rules:

• On every run the helper locates the existing fenced block (if any)
  and rewrites it in full from upstream. Entries outside the fence are
  consumer-owned and never touched.
• If an entry appears both inside the fence and outside it in the
  consumer file, the outside copy wins (consumer override); the
  in-fence duplicate is dropped on next write.
• If the fence is absent, the helper appends it at the end of the file,
  preceded by exactly one blank line.
• Comment-only blocks from upstream that have no entries are not
  propagated inside the fence.
• This replaces the prior "chunk-aware (comment + entry)" rule, which
  was ambiguous on orphaned comments.

[REFINED] Deleted-then-re-appeared entry policy

Documented behavior: upstream entries are canonical. If a consumer
manually deletes an entry from within the fence, the next sync run will
re-append it. To suppress an upstream entry intentionally, the consumer
must either:

1. Add a negation pattern (!path/) outside the fence, or
2. Open an upstream PR to remove the entry from the canonical list.

[REFINED] Option B chosen on upstream curation

Curate upstream .gitignore so only workflow-shared entries ship to
consumers:

• Keep in upstream .gitignore (propagated): .evidence/,
  .playwright-mcp/, .worktrees/, OS cruft (.DS_Store,
  Thumbs.db, *.swp, *~).
• Move to upstream .gitignore.dogfood (NOT propagated):
  Samples/HAR-Original/, .dogfood-output/, testResults.xml.

Rationale: avoids leaking IntelliSDLC.ai layout into every consumer's
ignore file.

Sync-manifest change

Add a new merge_paths array to sync-manifest.json alongside paths
and consumer_owned; add .gitignore to it.

[REFINED] No-local-.gitignore case

If the consumer's .gitignore does not exist, the helper creates it
containing only the fenced managed block. No leading blank line.

[REFINED] Line-ending policy

• Detection: read the consumer's existing .gitignore as bytes; count
  \r\n vs bare \n. If \r\n > 0, treat as CRLF; else LF.
• Creation case: new files use LF.
• Write back: all lines use the detected separator.

Helper signature

function Merge-GitignoreFromUpstream {
    param(
        [Parameter(Mandatory)][string]$RepoRoot,
        [Parameter(Mandatory)][string]$UpstreamRef
    )
    # 1. Read upstream blob: git show "$UpstreamRef:.gitignore"
    # 2. Read local .gitignore (or treat as empty -> create)
    # 3. Detect line-ending; default LF if absent
    # 4. Strip existing fenced block, if any
    # 5. Build new fenced block from upstream entries
    # 6. Omit upstream entries that exist outside the fence (consumer override)
    # 7. Append (or insert at original fence position) the new block
    # 8. Write back using detected line ending
}

Idempotent by construction.

Fix #2 -- Pull-SDLC.ai.ps1 shows untracked/modified post-run

Note: this fix shipped in an earlier upstream PR and is in the current
code as Invoke-MainTreeCleanup. The success-path coverage is
complete; the abort-path gap is tracked in the follow-up issue.

After Invoke-AutoWorktreeSync returns 0, in main's working tree:

• For each manifest path untracked-and-identical-to-upstream, delete
  from main. PR merge will restore as tracked.
• For each manifest path tracked-and-modified-to-identical-to-upstream,
  git checkout -- <path>.
• If content differs, skip + warn. Never silent data loss.

Todos

1. inspect-self-refresh -- Re-read self-refresh path to confirm
   where Pull-SDLC.ai.ps1 is written in main vs worktree.
2. manifest-merge-paths -- Add merge_paths array to
   sync-manifest.json.
3. curate-upstream-gitignore -- Split upstream .gitignore; move
   dogfood-internal entries to .gitignore.dogfood.
4. add-merge-helper -- Implement Merge-GitignoreFromUpstream with
   fenced-block semantics, consumer-override, CRLF/LF detection,
   no-local-file case.
5. wire-into-pull -- Call helper from inside Invoke-PullSDLC
   (worktree checkout) before the git add -A block. Include
   .gitignore in $addPaths.
6. tests -- Pester cases (a)-(j): create-when-absent, insert-fence-
   when-no-fence, idempotent rewrite, preserve outside entries,
   consumer override, CRLF preserve, LF preserve, cleanup branches.
7. docs -- Update upstream README.md's consumer-owned files
   section to document fenced block, override mechanism, and
   .gitignore.dogfood upstream-only convention.
8. upstream-pr -- Open PR in
   IntelliTect-Samples/IntelliSDLC.ai. Note tier-crossing rationale.

Phase 2 -- Re-sync ScoopBucket to pick up upstream merge

Pre-flight checks

1. Self-refresh shim present in local script:
   Select-String -Path .\Pull-SDLC.ai.ps1 -Pattern 'self-refresh|sdlc\.ai/main' -List
2. Snapshot working tree: git status -uall > .pre-sync-status.txt
3. Confirm remote: git remote get-url sdlc.ai && git fetch sdlc.ai main && git rev-parse sdlc.ai/main

Phase 2 todos

1. preflight -- Run pre-flight checks.
2. run-pull-sdlc -- Execute .\Pull-SDLC.ai.ps1 from
   D:\Git\ScoopBucket on main.
3. verify-pr -- Confirm the sync PR has a new commit with merged
   .gitignore (fenced block) and updated .sdlc-ai-sync.json anchor.
4. verify-clean-status -- git status -uall diff against
   .pre-sync-status.txt.
5. merge-pr -- Rebase-merge the sync PR.
6. cleanup-snapshot -- Delete .pre-sync-status.txt.

Notes / caveats

• Tier-crossing reminder: Pull-SDLC.ai.ps1 is upstream-managed; the
  drift guard trips on local edits.
• Fenced-block design means future "delete this upstream entry" changes
  ship cleanly: next sync rewrites the fence and the removed line is
  gone for all consumers.