bug(init): avoid selecting one-character literals as the agent name

[pengfei-threemoonslab]

Summary

agents-shipgate init selected the one-character identifier t as the generated agent.name for the Strix repository, even though the same static pass also found the much more plausible candidate Strix.

This can produce a syntactically valid manifest whose declared agent identity is misleading. The user must correct it manually before relying on later reports or handoffs.

Reproduction

From a local clone of usestrix/strix:

env AGENTS_SHIPGATE_AGENT_MODE=1 \
  PYTHONPATH=/path/to/agents-shipgate/src \
  python -m agents_shipgate init \
  --workspace /path/to/strix \
  --write \
  --json

Relevant output:

{
  "auto_detected": {
    "is_agent_project": true,
    "frameworks": [
      {
        "type": "openai_agents_sdk",
        "score": 64.0,
        "confidence": "high"
      }
    ],
    "agent_name": "t",
    "agent_name_candidates": [
      { "value": "t", "source": "Agent_name_literal" },
      { "value": "Strix", "source": "Agent_name_literal" },
      { "value": "strix", "source": "workspace_dir" }
    ]
  }
}

The command successfully wrote shipgate.yaml and a managed .gitignore block. The issue is the automatic choice of t as the manifest's agent identity, not framework detection or file writing.

Actual behavior

• The repository is correctly detected as a high-confidence OpenAI Agents SDK project.
• The one-character literal t is ranked above Strix.
• init --write uses t as the generated agent name.

Expected behavior

When several literals are available, a one-character, context-poor identifier should not be silently selected over a plausible project/agent identity.

Possible fail-closed behavior:

1. Penalize or exclude very short/generic name literals unless they are the only candidate.
2. Prefer candidates with stronger agent-definition context and meaningful names.
3. If ambiguity remains material, write a CHANGE_ME placeholder (or emit an explicit diagnostic) rather than asserting an unreliable agent identity.

Why this matters

agent.name appears in scan output and reviewer/agent-handoff artifacts. Selecting the wrong identity makes reports harder to interpret and can lead users to trust an auto-generated manifest that needs semantic correction.

This is a static candidate-ranking problem. It does not require executing the Strix agent, calling tools, or making network requests.

[pengfei-threemoonslab]

Confirmed at 7e0bfdf5 — and the underlying cause is more basic than "ranking needs tuning": there is no ranking at all.

cli/discovery/signals.py:567-578:

def _agent_name_candidates(facts: list[_PyFacts], workspace: Path) -> list[NameCandidate]:
    candidates: list[NameCandidate] = []
    seen: set[str] = set()
    for fact in facts:
        for literal in fact.agent_name_literals:
            if literal not in seen:
                candidates.append(NameCandidate(value=literal, source="Agent_name_literal"))
                seen.add(literal)
    ...

Candidates are appended in file-iteration then AST order, with no scoring, no length filter, and no context weighting. cli/_register_init.py:363-364 then takes the first candidate whose source is Agent_name_literal or ADK_name_field. So t did not out-rank Strix — it was simply encountered first, and "first" is the entire policy.

That explains this issue and #324 as one defect with two faces: #320 is a candidate-quality problem and #324 is a candidate-hierarchy problem, but both exist because the selection step has no notion of either. They share one function and should be fixed together, with a single ranking pass rather than two stacked filters.

Suggested split of responsibility, since the two halves have very different costs:

• This issue (cheap, general): a quality floor in the ranking — penalize very short and context-poor identifiers, so a loop variable or comprehension target can never outrank a real name. This helps every framework, including the OpenAI Agents SDK case here where no structural root exists to appeal to.
• bug(init/google-adk): infer App root_agent instead of selecting the first literal sub-agent #324 (structural, ADK-specific): resolve App(root_agent=...) to the actual coordinator. That fix subsumes this one for ADK but does nothing for Strix.

Both are needed. The acceptance criterion worth adding to whichever lands first is that agent_name_candidates carry their ranking rationale, which #324 already asks for — without it, a future regression in ordering is invisible in the output.

Labeled P2 / v0.17.0: the manifest is schema-valid and the identity is human-correctable, so it degrades interpretation rather than the gate.